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):
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. 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 onhttp://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 withspawn
(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 captureand 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 thesameargument 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
andPOST /stop
require a matchingOrigin
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/ 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 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