Agent Skills: CLI for Agents

CLI for Agents

Prefer command patterns that work headlessly, compose in pipelines, and fail in ways an agent can recover from quickly.

Non-Interactive First

• Express every required input as a flag or flag value.
• Fall back to interactive prompts only when flags are missing and an interactive session is appropriate.
• Avoid arrow-key menus, timed prompts, and flows that block stdin-driven execution.

Bad: mycli deploy prompts for an environment. Good: mycli deploy --env staging

Layer Help Incrementally

• Keep top-level help short and let each subcommand own its own --help.
• Expect agents to discover commands step by step: mycli, then mycli deploy --help.
• Do not print the entire manual on every invocation.

Make --help Copy-Pasteable

• Add --help to every subcommand.
• Include real Examples: blocks with valid invocations, not placeholders alone.
• Show the common safe path first, then destructive or forceful variants.

Options:
  --env     Target environment (staging, production)
  --tag     Image tag (default: latest)
  --dry-run Preview the deployment plan
  --yes     Skip confirmation

Examples:
  mycli deploy --env staging --tag v1.2.3 --dry-run
  mycli deploy --env staging --tag v1.2.3
  mycli deploy --env production --tag v1.2.3 --yes

Support Flags, Stdin, and Pipelines

• Accept stdin where it is a natural input path.
• Avoid positional argument patterns that are easy to scramble.
• Keep outputs chainable so one command can feed another.

Examples:

• cat config.json | mycli config import --stdin
• mycli deploy --env staging --tag "$(mycli build --output tag-only)"

Fail Fast With Actionable Errors

• Exit immediately on missing required flags or invalid combinations.
• Print a short error plus a correct example invocation.
• Prefer guidance that helps the next command succeed without opening external docs.

Error: missing required flag --tag
Try:
  mycli deploy --env staging --tag <image-tag>
List tags:
  mycli build list --output tags

Design for Retries

• Make successful commands safe to retry.
• Return explicit no-op or already-done messages instead of duplicating side effects.
• Keep side effects narrow and obvious so agents can reason about re-runs.

Guard Destructive Actions

• Provide --dry-run or an equivalent preview mode.
• Provide --yes or --force for non-interactive confirmation bypass.
• Keep the default behavior safe for humans while leaving a clear headless path for automation.

Keep Command Shapes Predictable

• Use one command grammar consistently across resources and verbs.
• Reuse option names when they mean the same thing.
• Avoid making one command tree resource-first and another verb-first unless there is a strong reason.

Return Machine-Useful Success Output

• Include IDs, URLs, paths, counts, or durations in success output.
• Plain text is fine if the data is stable and easy to parse.
• Do not rely only on decorative output or prose summaries.

deployed v1.2.3 to staging
url: https://staging.myapp.com
deploy_id: dep_abc123
duration: 34s

Review Checklist

When reviewing an existing CLI, check for:

• A complete non-interactive path
• Short layered help instead of one giant manual
• Real Examples: blocks on --help
• Sensible stdin and pipeline support
• Actionable errors with correct invocations
• Retry-safe and idempotent behavior
• --dry-run plus confirmation bypass flags for risky actions
• Consistent command and option naming
• Success output with machine-useful fields