CLI Creator
Build a durable CLI that agents can run from any working directory.
Start
Define:
- Source: API docs, OpenAPI JSON, SDK docs, curl examples, web app, or existing script.
- Jobs: literal reads/writes such as
list drafts, download logs, search messages, upload media.
- Install name: short binary name like
ci-logs, slack-cli, sentry-cli.
Check if the name already exists:
command -v <tool-name> || true
Choose the runtime
Inspect the machine:
command -v cargo rustc node pnpm npm python3 uv || true
Choose the least surprising option:
- Rust for durable, fast binaries with strong JSON handling.
- TypeScript/Node when the SDK or browser tooling is the reason the CLI is better.
- Python for data, notebooks, SQLite, or existing Python-heavy tooling.
Command surface
Sketch before coding. Every CLI should have:
--help showing every major capability.--json doctor verifying config, auth, version, and endpoint reachability.init for local config when env-only auth is painful.- Discovery commands for top-level containers.
- Resolve commands turning names, URLs, or slugs into stable IDs.
- Read commands with bounded
--limit or clear pagination.
- Write commands that are narrow, named actions with
--dry-run or preview when possible.
- A raw escape hatch named honestly, e.g.
request or api.
Auth and config
Precedence:
- Environment variable with the service's standard name, e.g.
GITHUB_TOKEN.
- User config under
~/.<tool-name>/config.toml.
--api-key flag only for explicit one-off tests.
Never print full tokens. doctor --json reports the auth source category and missing setup.
Build workflow
- Read the source to inventory resources, auth, pagination, IDs, file flows, rate limits, and dangerous writes.
- Sketch the command list in chat.
- Scaffold the CLI with a README.
- Implement
doctor, discovery, resolve, read, and a narrow dry-run write path.
- Install the CLI on PATH.
- Smoke test from another repo or
/tmp.
- Run format, typecheck, build, and unit tests.
Defaults
Rust: clap, reqwest, serde, toml, anyhow. Add make install-local to ~/.local/bin.
TypeScript/Node: commander or cac, zod only where needed, package.json bin entry.
Python: argparse or typer, httpx/requests, pyproject.toml console script.
Companion skill
After the CLI works, create a small skill that explains how to verify it, configure auth, discover IDs, run safe reads, and use the write path.
1---2name: cli-creator3description: Build a composable command-line tool from API docs, OpenAPI specs, SDKs, curl examples, or existing scripts. Use when the user wants a durable CLI that future agents can run from any directory.4license: MIT5---67# CLI Creator89Build a durable CLI that agents can run from any working directory.1011## Start1213Define:1415- **Source**: API docs, OpenAPI JSON, SDK docs, curl examples, web app, or existing script.16- **Jobs**: literal reads/writes such as `list drafts`, `download logs`, `search messages`, `upload media`.17- **Install name**: short binary name like `ci-logs`, `slack-cli`, `sentry-cli`.1819Check if the name already exists:2021```bash22command -v <tool-name> || true23```2425## Choose the runtime2627Inspect the machine:2829```bash30command -v cargo rustc node pnpm npm python3 uv || true31```3233Choose the least surprising option:3435- **Rust** for durable, fast binaries with strong JSON handling.36- **TypeScript/Node** when the SDK or browser tooling is the reason the CLI is better.37- **Python** for data, notebooks, SQLite, or existing Python-heavy tooling.3839## Command surface4041Sketch before coding. Every CLI should have:4243- `--help` showing every major capability.44- `--json doctor` verifying config, auth, version, and endpoint reachability.45- `init` for local config when env-only auth is painful.46- Discovery commands for top-level containers.47- Resolve commands turning names, URLs, or slugs into stable IDs.48- Read commands with bounded `--limit` or clear pagination.49- Write commands that are narrow, named actions with `--dry-run` or preview when possible.50- A raw escape hatch named honestly, e.g. `request` or `api`.5152## Auth and config5354Precedence:55561. Environment variable with the service's standard name, e.g. `GITHUB_TOKEN`.572. User config under `~/.<tool-name>/config.toml`.583. `--api-key` flag only for explicit one-off tests.5960Never print full tokens. `doctor --json` reports the auth source category and missing setup.6162## Build workflow63641. Read the source to inventory resources, auth, pagination, IDs, file flows, rate limits, and dangerous writes.652. Sketch the command list in chat.663. Scaffold the CLI with a README.674. Implement `doctor`, discovery, resolve, read, and a narrow dry-run write path.685. Install the CLI on PATH.696. Smoke test from another repo or `/tmp`.707. Run format, typecheck, build, and unit tests.7172## Defaults7374**Rust**: `clap`, `reqwest`, `serde`, `toml`, `anyhow`. Add `make install-local` to `~/.local/bin`.7576**TypeScript/Node**: `commander` or `cac`, `zod` only where needed, `package.json` `bin` entry.7778**Python**: `argparse` or `typer`, `httpx`/`requests`, `pyproject.toml` console script.7980## Companion skill8182After the CLI works, create a small skill that explains how to verify it, configure auth, discover IDs, run safe reads, and use the write path.
aizech