cli-for-agents

CLI for agents

Human-oriented CLIs often block agents: interactive prompts, huge upfront docs, and help text without copy-pasteable examples. Prefer patterns that work headlessly and compose in pipelines.

Non-interactive first

• Every input should be expressible as a flag or flag value. Do not require arrow keys, menus, or timed prompts.
• If flags are missing, then fall back to interactive mode—not the other way around.

Bad: mycli deploy → ? Which environment? (use arrow keys) Good: mycli deploy --env staging

Discoverability without dumping context

• Agents discover subcommands incrementally: mycli, then mycli deploy --help. Do not print the entire manual on every run.
• Let each subcommand own its documentation so unused commands stay out of context.
• If the CLI needs extensive agent guidance, keep the default skill/help thin and point to versioned, CLI-served instructions. See references/agent-browser-runtime-skills.md.

--help that works

• Every subcommand has --help.
• Every --help includes Examples with real invocations. Examples do more than prose for pattern-matching.

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

stdin, flags, and pipelines

• Accept stdin where it makes sense (e.g. cat config.json | mycli config import --stdin).
• Avoid odd positional ordering and avoid falling back to interactive prompts for missing values.
• Support chaining: mycli deploy --env staging --tag $(mycli build --output tag-only).

Fail fast with actionable errors

• On missing required flags: exit immediately with a clear message and a correct example invocation, not a hang.

Error: No image tag specified.
  mycli deploy --env staging --tag <image-tag>
  Available tags: mycli build list --output tags