Flagpost

Paste a terminal command and see what every part means, get a warning before a risky one, or build a command by filling in blanks. It runs entirely in your browser: no server, no account, nothing you type is sent anywhere.

A student rebuild of the idea behind Fig (the terminal autocomplete tool that was acquired and shut down). Fig helped people who could not remember flags. Flagpost keeps that idea and drops the parts that needed an installed app and a cloud account.

Live demo: https://jay-m007.github.io/flagpost/ (once published)

What it does

• Explain: splits a command into parts (command, subcommand, flags, values, pipes) and says what each one does in plain words. Clustered flags like -xzvf are split apart.
• Did you mean: git psuh becomes "did you mean push?" using edit distance that counts a swapped pair as one slip.
• Warn: checks the parsed command, not a text pattern, for things like rm -rf ~/*, git push --force, curl ... | bash, chmod -R 777, find -delete. Each warning says why and offers a safer version. --force-with-lease is correctly left alone.
• Autocomplete: suggests commands, subcommands and flags from the same list, with a short meaning.
• Build: 39 "I want to..." recipes (undo a commit, unpack a tar file, free a port, run a container). Fill the blanks, copy the command. Values are shell-quoted so a name with spaces or quotes cannot break out.

Run it

npm test          # 26 tests, no dependencies
npm run serve     # builds, then http://localhost:8080

Needs Node 18 or newer. Pure ES modules, no packages to install.

How it is built

File	Job
engine/spec.js	Hand-written list of about 70 tools and several hundred flags
engine/tokenize.js	Shell tokenizer: quotes, pipes, &&, redirects
engine/explain.js	Matches tokens against the list; edit-distance suggestions
engine/danger.js	Rules on the parsed command
engine/complete.js	Autocomplete
engine/recipes.js	The build recipes
web/	The page. Text goes in with textContent only; CSP forbids network, inline script and inline style

Tests include a round trip: every recipe's output must be fully understood by the explainer, and none may trigger a high or critical warning. The warning tests use a small labelled set of dangerous and safe commands.

Honest limits

• The command list is written by hand. It covers common tools, not everything. An "unknown" word may simply be missing.
• Explanations are rule-based, not an AI model. Unusual flag combinations get a flag-by-flag reading only.
• The warnings are rules of thumb. A clean result does not mean a command is safe. This is not a security tool.
• The danger test set is small and was written by the author, so its 100% result says the rules do what the author intended, not that they catch everything.
• Shell features such as variables, $(...), loops and aliases are only partly understood.
• Bash-style syntax only. PowerShell and cmd are not covered.
• No study with real users has been done.

Licence

MIT