[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-92589":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":29,"readmeContent":30,"aiSummary":31,"trendingCount":15,"starSnapshotCount":15,"syncStatus":32,"lastSyncTime":33,"discoverSource":34},92589,"instagui","Soutar97\u002Finstagui","Soutar97","Turn any CLI into a web GUI with one command","",null,"TypeScript",85,4,52,0,33,45.4,"MIT License",false,"main",true,[23,24,25,26,27,28],"ai","claude","cli","developer-tools","ffmpeg","gui","2026-07-22 04:02:06","# instagui\n\n**Any CLI. Instant GUI. One command.**\n\nAs featured in [The Register](https:\u002F\u002Fwww.theregister.com\u002Fsoftware\u002F2026\u002F07\u002F07\u002Fnew-tool-gives-clis-a-warm-and-gui-feeling-instead\u002F5267798)\n\nTurn any command-line tool into a clean local web form — no config, no code changes to the tool.\n\n\u003C!-- TODO(pre-launch): record and drop the money-demo GIF here.\n     ~10s: `npx instagui ffmpeg` → browser opens → fill a couple fields → Run → output streams.\n     Save as docs\u002Fdemo.gif and it renders below. -->\n![instagui demo — npx instagui ffmpeg opens a web form, click Run, output streams](docs\u002Fdemo.gif)\n\n```sh\nnpx instagui ffmpeg\n```\n\nThat's it. instagui reads the tool's `--help`, turns it into a web form, opens your browser, and\n(when you click **Run**) executes the command locally and streams the output back — while always\nshowing you the exact command it will run, so it teaches you the CLI instead of hiding it.\n\n---\n\n## Why\n\nThousands of powerful CLIs (ffmpeg, pandoc, yt-dlp, curl, imagemagick…) are unfriendly to anyone\nwho doesn't live in a terminal — and even experts re-read man pages to recall flag syntax. Tools\nlike Gooey require the tool's *author* to change their code. instagui needs nothing from the tool: it\nparses the tool's own `--help` text with AI into a structured schema and renders that as a form.\n\n## Quick start\n\nThe three demo tools ship with **bundled schemas**, so they work instantly with **no API key**:\n\n```sh\nnpx instagui ffmpeg      # video\u002Faudio transcoding\nnpx instagui yt-dlp      # download media\nnpx instagui pandoc      # convert documents\n```\n\nFor any *other* tool, instagui extracts the schema on first run using the Claude API (see\n[How it stays free](#how-it-stays-free)):\n\n```sh\nexport ANTHROPIC_API_KEY=sk-ant-...    # POSIX\n$env:ANTHROPIC_API_KEY=\"sk-ant-...\"    # Windows \u002F PowerShell\nnpx instagui curl\n```\n\nGet a key at \u003Chttps:\u002F\u002Fconsole.anthropic.com>. The first extraction is cached, so every launch\nafter that is instant and free.\n\n## How it works\n\n1. **Capture** — run `\u003Ctool> --help` (falling back to `-h`, `help`, then the man page), reading\n   both stdout and stderr, under a timeout and size cap so a misbehaving tool can't hang the launch.\n2. **Extract** — send the help text to the Claude API (`claude-haiku-4-5`) and get back a validated\n   JSON schema of the tool's options (name, flag, type, description, enum values, required, grouping)\n   plus positional arguments. Invalid output is retried once, then fails clearly.\n3. **Serve** — render the schema as a single-page form on `http:\u002F\u002F127.0.0.1`, grouped, with the\n   right control per type (checkbox \u002F dropdown \u002F number \u002F text).\n4. **Preview** — show the exact command as you edit the form, one-click copyable.\n5. **Run** — execute the command with `spawn` (arguments array, never a shell string) and stream\n   stdout\u002Fstderr live into the page until it exits.\n\n## How it stays free\n\ninstagui resolves a schema in this order, and only the last step costs an API call:\n\n| Precedence | Source | Needs a key? |\n| --- | --- | --- |\n| 1 | `--schema \u003Cfile>` override you supply | no |\n| 2 | Your cache in `~\u002F.instagui\u002F` (written on first extraction) | no |\n| 3 | Bundled schemas shipped with the package (ffmpeg, yt-dlp, pandoc) | no |\n| 4 | Fresh extraction via the Claude API | **yes** |\n\nSo the demo tools are free forever, any tool you've used once is free forever after, and you only\nneed a key the first time you point instagui at a brand-new tool. A friendly message tells you exactly\nwhat to do if a key is needed and missing — you're never dropped into a stack trace.\n\n- `--refresh` re-extracts and overwrites your cache entry.\n- `--schema .\u002Fmytool.json` uses a hand-tuned schema and skips capture **and** the AI entirely.\n\n## Usage\n\n```\ninstagui \u003Ctool>                 resolve \u003Ctool>'s Schema and serve the Form (auto-opens the browser)\ninstagui \u003Ctool> --print         resolve and print the Schema JSON instead of serving\ninstagui \u003Ctool> --schema \u003Cpath> use a hand-supplied Schema file (no capture, no AI)\ninstagui \u003Ctool> --refresh       ignore cache + bundled and re-extract fresh\ninstagui \u003Ctool> --help-file \u003Cp> extract from a captured help-text file\n\u003Ctool> --help | instagui \u003Ctool> or pipe help text on stdin\n\n  --port \u003Cn>     preferred port for the Form server (default 5177; falls back if busy)\n  --no-open      do not auto-open the browser (still prints the URL)\n  --model \u003Cid>   extraction model (default: claude-haiku-4-5)\n  -v, --version  print the instagui version\n  -h, --help     show help\n```\n\n## Security \u002F threat model\n\ninstagui is a **local, single-user tool**. Be clear-eyed about what it does:\n\n- **It runs commands you compose.** The whole point is to execute a real CLI with the arguments you\n  set in the form. Treat the form like your own terminal — don't run something you wouldn't type.\n- **The exact command is always shown before you Run it.** No hidden arguments; preview is generated\n  from the *same* argument array that Run executes, so what you see is what runs.\n- **Arguments are passed as an array to `spawn`, never concatenated into a shell.** A value\n  containing spaces, quotes, `;`, or `&&` is passed verbatim as a single argument — there is no\n  shell to interpret it, so form input can't inject extra commands.\n- **The server binds `127.0.0.1` only.** It is not reachable from your network.\n- **State-changing requests fail closed.** `POST \u002Frun` and `POST \u002Fstop` require a matching `Origin`\n  header; a missing or foreign origin is rejected (CSRF protection). Exactly one run at a time, and\n  closing the tab (dropping the stream) kills the child process — no orphans.\n- **Your API key is never logged, echoed, or embedded in any served page.** The only data that\n  leaves your machine is the tool's help text, sent to the Claude API for extraction. No telemetry.\n\n## Contribute a schema\n\nWant a tool to work keyless for everyone, like the demo tools do? Bundled schemas live in\n[`schemas\u002F`](schemas\u002F) and are generated from captured `--help` fixtures:\n\n1. Capture the tool's help into `test\u002Ffixtures\u002F\u003Ctool>-help.txt`.\n2. Add the tool to `scripts\u002Fgen-bundled-schemas.ts`.\n3. Regenerate with your key: `ANTHROPIC_API_KEY=sk-ant-... npx tsx scripts\u002Fgen-bundled-schemas.ts`\n   (a hallucination guard + golden check run before anything is written).\n4. Open a PR with the fixture and the generated `schemas\u002F\u003Ctool>.json`.\n\nEach generated schema is validated so every flag appears verbatim in the source help text — no\nhallucinated options. See [`schemas\u002FREADME.md`](schemas\u002FREADME.md) for provenance details.\n\n## Requirements\n\n- **Node.js ≥ 22**\n- An `ANTHROPIC_API_KEY` only for extracting a tool that isn't bundled or cached.\n\n## Non-goals (v0.1)\n\nDeliberately out of scope to keep it small and sharp: interactive\u002FTUI programs (vim, top, REPLs);\nsubcommand trees (flat tools only — `git commit` vs `git push` is v0.2); native file-picker dialogs;\na hosted version, auth, telemetry, or a plugin system; a local-LLM option (contributions welcome).\n\n## License\n\nMIT © Omar\n","instagui 是一个将任意命令行工具（CLI）一键转化为本地网页图形界面（GUI）的开发工具。它通过解析 CLI 的 --help 输出（优先使用内置预置 schema，如 ffmpeg\u002Fyt-dlp\u002Fpandoc；其余工具调用 Claude API 提取结构化参数 schema），自动生成带表单验证、实时命令预览、流式输出展示的 Web 界面，并安全地本地执行命令。核心特点包括零代码侵入、AI 辅助 schema 解析、命令透明可复制、无远程依赖（除首次 schema 提取）、支持多类主流 CLI 工具。适用于开发者快速为终端工具提供可视化入口，或非技术用户安全使用专业 CLI（如音视频处理、文档转换、媒体下载等场景）。",2,"2026-07-09 02:30:25","CREATED_QUERY"]