Instagui – turn any CLI into a web GUI with one command

Instagui, a new open-source tool, lets users turn any command-line interface into a web GUI with a single command by parsing the tool's --help text using AI. The tool requires no code changes to the CLI and works instantly with bundled schemas for ffmpeg, yt-dlp, and pandoc, while other tools need a one-time Claude API key for schema extraction. It aims to make powerful CLIs accessible to non-terminal users while teaching them the underlying commands.

Any CLI. Instant GUI. One command. Turn any command-line tool into a clean local web form — no config, no code changes to the tool. npx instagui ffmpeg That's it. instagui reads the tool's --help , turns it into a web form, opens your browser, and when you click Run executes the command locally and streams the output back — while always showing you the exact command it will run, so it teaches you the CLI instead of hiding it. Thousands of powerful CLIs ffmpeg, pandoc, yt-dlp, curl, imagemagick… are unfriendly to anyone who doesn't live in a terminal — and even experts re-read man pages to recall flag syntax. Tools like Gooey require the tool's author to change their code. instagui needs nothing from the tool: it parses the tool's own --help text with AI into a structured schema and renders that as a form. The three demo tools ship with bundled schemas , so they work instantly with no API key : npx instagui ffmpeg video/audio transcoding npx instagui yt-dlp download media npx instagui pandoc convert documents For any other tool, instagui extracts the schema on first run using the Claude API see How it stays free how-it-stays-free : export ANTHROPIC API KEY=sk-ant-... POSIX $env:ANTHROPIC API KEY="sk-ant-..." Windows / PowerShell npx instagui curl Get a key at https://console.anthropic.com https://console.anthropic.com . The first extraction is cached, so every launch after that is instant and free. Capture — run <tool --help falling back to -h , help , then the man page , reading both stdout and stderr, under a timeout and size cap so a misbehaving tool can't hang the launch. Extract — send the help text to the Claude API claude-haiku-4-5 and get back a validated JSON schema of the tool's options name, flag, type, description, enum values, required, grouping plus positional arguments. Invalid output is retried once, then fails clearly. Serve — render the schema as a single-page form on http://127.0.0.1 , grouped, with the right control per type checkbox / dropdown / number / text . Preview — show the exact command as you edit the form, one-click copyable. Run — execute the command with spawn arguments array, never a shell string and stream stdout/stderr live into the page until it exits. instagui resolves a schema in this order, and only the last step costs an API call: | Precedence | Source | Needs a key? | |---|---|---| | 1 | --schema <file override you supply | no | | 2 | Your cache in ~/.instagui/ written on first extraction | no | | 3 | Bundled schemas shipped with the package ffmpeg, yt-dlp, pandoc | no | | 4 | Fresh extraction via the Claude API | yes | So the demo tools are free forever, any tool you've used once is free forever after, and you only need a key the first time you point instagui at a brand-new tool. A friendly message tells you exactly what to do if a key is needed and missing — you're never dropped into a stack trace. --refresh re-extracts and overwrites your cache entry. --schema ./mytool.json uses a hand-tuned schema and skips capture and the AI entirely. instagui <tool resolve <tool 's Schema and serve the Form auto-opens the browser instagui <tool --print resolve and print the Schema JSON instead of serving instagui <tool --schema <path use a hand-supplied Schema file no capture, no AI instagui <tool --refresh ignore cache + bundled and re-extract fresh instagui <tool --help-file <p extract from a captured help-text file <tool --help | instagui <tool or pipe help text on stdin --port <n preferred port for the Form server default 5177; falls back if busy --no-open do not auto-open the browser still prints the URL --model <id extraction model default: claude-haiku-4-5 -v, --version print the instagui version -h, --help show help instagui is a local, single-user tool . Be clear-eyed about what it does: It runs commands you compose. The whole point is to execute a real CLI with the arguments you set in the form. Treat the form like your own terminal — don't run something you wouldn't type. The exact command is always shown before you Run it. No hidden arguments; preview is generated from the same argument array that Run executes, so what you see is what runs. Arguments are passed as an array to A value containing spaces, quotes, spawn , never concatenated into a shell. ; , or && is passed verbatim as a single argument — there is no shell to interpret it, so form input can't inject extra commands. The server binds It is not reachable from your network. 127.0.0.1 only. State-changing requests fail closed. POST /run and POST /stop require a matching Origin header; a missing or foreign origin is rejected CSRF protection . Exactly one run at a time, and closing the tab dropping the stream kills the child process — no orphans. Your API key is never logged, echoed, or embedded in any served page. The only data that leaves your machine is the tool's help text, sent to the Claude API for extraction. No telemetry. Want a tool to work keyless for everyone, like the demo tools do? Bundled schemas live in schemas/ /Soutar97/instagui/blob/main/schemas and are generated from captured --help fixtures:- Capture the tool's help into test/fixtures/<tool -help.txt . - Add the tool to scripts/gen-bundled-schemas.ts . - Regenerate with your key: ANTHROPIC API KEY=sk-ant-... npx tsx scripts/gen-bundled-schemas.ts a hallucination guard + golden check run before anything is written . - Open a PR with the fixture and the generated schemas/<tool .json . Each generated schema is validated so every flag appears verbatim in the source help text — no hallucinated options. See schemas/README.md /Soutar97/instagui/blob/main/schemas/README.md for provenance details. Node.js ≥ 22 - An ANTHROPIC API KEY only for extracting a tool that isn't bundled or cached. Deliberately out of scope to keep it small and sharp: interactive/TUI programs vim, top, REPLs ; subcommand trees flat tools only — git commit vs git push is v0.2 ; native file-picker dialogs; a hosted version, auth, telemetry, or a plugin system; a local-LLM option contributions welcome . MIT © Omar