create-cli

Create CLI

Build CLIs for AI agents. Assume 100% agent usage.

Default Assumptions

• Language: Shell script (bash) by default. Use Python (uv + typer) or TypeScript (bun + commander) only when:
  • SDK works better in that language
  • Requires specific packages (e.g., data analysis → Python)
  • User explicitly requests it
• Non-interactive: Agents cannot respond to prompts—commands just hang
• Parseable output: JSON for machine consumption; human-readable as fallback

Core Principles

1. Non-interactive first

Agents cannot answer prompts. Every input must be expressible as a flag.

# Bad: hangs the agent
mycli deploy
? Which environment? (use arrow keys)

# Good: works
mycli deploy --env staging

• Gate confirmations behind --yes or --force flags
• If required input is missing, fail immediately with an actionable error—don't prompt
• For optional human interactivity, gate behind --interactive flag

2. Layered discovery

Agents discover incrementally: mycli → mycli deploy --help. Don't dump all docs upfront.

• Each subcommand has its own --help
• Every --help includes Examples (agents pattern-match faster than reading prose)
• Suggest next commands in output when helpful

Options:
  --env     Target environment (staging, production)
  --tag     Image tag (default: latest)
  --force   Skip confirmation

Examples:
  mycli deploy --env staging
  mycli deploy --env production --tag v1.2.3
  mycli deploy --env staging --force

3. JSON input for complex data

Prefer --json for structured input—agents generate it directly with zero translation loss.

# Accept full JSON payload
mycli create --json '{"title": "Doc", "locale": "en_US", "gridProperties": {"frozenRowCount": 1}}'

# Also accept JSON from stdin
cat config.json | mycli create --stdin

JSON maps directly to API schemas. No need to flatten nested structures into flags.

4. Parseable output

• Provide --json for structured output; human-readable text as default
• On success, return machine-useful data: IDs, URLs, durations, state changes