CLI for Agents

CLI for Agents is a design checklist for command-line tools that coding agents have to operate. It is short, about 470 words, and it names the failure modes that make a human-friendly CLI unusable in a headless session: arrow-key prompts, a manual dumped on every invocation, help text with no examples, hangs on missing input, and retries that duplicate side effects.

It ships in cursor/plugins as part of the cli-for-agent plugin, authored by Eric Zakariasson. The plugin has its own MIT LICENSE and plugin.json; the skill is one folder inside it.

Source and revision

What the skill actually does

The skill gives eight design rules:

1. Non-interactive first

Every input should be expressible as a flag or flag value. 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

2. Discoverability without dumping context

An agent discovers subcommands incrementally: mycli, then mycli deploy --help. Do not print the entire manual on every run. Each subcommand owns its documentation so unused commands stay out of context.

3. Help that works

Every subcommand has --help, and every help output includes real invocation examples. Examples do more than prose for pattern matching.

4. stdin, flags, and pipelines

Accept stdin where it makes sense, avoid odd positional ordering, and support chaining. The skill's example:

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

5. Fail fast with actionable errors

On a missing required flag, exit immediately with a clear message and a correct example invocation. Do not hang.

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

6. Idempotency

Agents retry. The same successful command run twice should be safe: a no-op or an explicit "already done," not a duplicate side effect.

7. Destructive actions

Add --dry-run so an agent can preview a plan before committing. Offer --yes or --force to skip confirmations while keeping the safe default for humans.

8. Predictable structure and success output

Use a consistent resource + verb pattern. On success, return machine-useful data: IDs, URLs, durations. Plain text is fine; decorative output alone is not.

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

The final section is a review checklist for an existing CLI: non-interactive path, layered help, examples, stdin, errors with invocations, idempotency, dry-run, confirmation bypass, consistent structure, structured success output.

Why this matters for agents

An agent does not have a human's patience or context. A prompt that waits for arrow keys blocks the session. A help screen that prints 400 lines consumes context the agent needs for the actual task. An error that says "invalid input" without the valid form forces a guess. A retry after a timeout that creates a second resource is worse than a failure.

The skill is short because the rules are simple. The hard part is applying them consistently across every subcommand, including the ones added later.

Illustrative review

This is a constructed example, not a review of a real CLI.

Existing command:

$ mycli deploy
? Select environment (Use arrow keys)
❯ staging
  production

Findings from the checklist:

• Non-interactive path: missing. Add --env.
• Help: mycli deploy --help prints options but no examples. Add three real invocations.
• Error behavior: if --tag is omitted, the command prompts instead of failing. In CI, that is a hang. Fail with an example.
• Idempotency: running the same deploy twice creates a second release. Make the second run a no-op or return the existing release ID.
• Destructive action: no dry-run. Add --dry-run that prints the resolved environment, image, and target without deploying.
• Success output: prints a ASCII banner and no deploy ID. Add deploy_id, url, and duration.

Expected artifact: a short design review with one finding per rule, not a rewrite of the CLI. The skill is guidance; it does not generate the implementation.

When to use it

• You are building a CLI that an agent will invoke in a script or tool loop.
• You are reviewing an existing CLI for headless usability.
• You need a checklist for help text, exit behavior, and idempotency.
• You are writing a tool definition or MCP wrapper and want the underlying command to be predictable.

When not to use it

• You need a CLI generator or a full argument-parsing framework. This is design guidance, not code.
• The tool is interactive by nature, such as a REPL or a TUI. The non-interactive rules still apply to the automatable subset, but the whole product is not a batch CLI.
• You need shell completion, packaging, or distribution advice. The skill does not cover those.
• You need a security review of the command's privileges. The skill mentions dry-run and confirmations, not threat modeling.

Install

npx skills add cursor/plugins --skill cli-for-agents -a claude-code

Prerequisites and footprint

This is one of the lowest-risk installs in the collection. The main risk is not the skill; it is the CLI it helps you design. A dry-run flag is not a sandbox.

Limitations

• Guidance, not generation. The skill will not write the argument parser or enforce the rules.
• Human and agent needs can conflict. A rich interactive mode is still valuable for humans. The skill asks for a non-interactive path, not the removal of interactivity.
• No security model. --force and --yes are convenience flags; they do not replace authorization or audit logging.
• No test harness. The skill says to check idempotency and dry-run, but it does not provide a way to prove them.
• Plugin-level license. The skill file has no license: field. The plugin LICENSE and plugin.json declare MIT, which resolves the scope for this plugin, but not for every plugin in the repository.
• Short source. The page adds the worked review because the source is only a checklist.

Verify it yourself

1. Read the skill and compare it with your CLI's --help output. Check for examples and a non-interactive path on every subcommand.
2. Run the same successful command twice in a disposable environment. If it creates a duplicate, the idempotency rule is unmet.
3. Trigger a missing required flag in a non-TTY context. It should exit with an example, not hang.
4. Check whether --dry-run actually avoids side effects. A flag that prints a plan and still deploys is worse than no flag.
5. Inspect the plugin LICENSE and plugin.json if you plan to redistribute the skill. Attribute the plugin, not the whole repository.

Review transparency

This is an original guide with short attributed references. It does not reproduce the full skill text.

Related

• Verify This — prove the CLI change with baseline and treatment
• skill-creator — package a workflow, not a CLI
• OpenCode Configuration — where skills and tools live
• MCP Implementation Guide — the tool-server alternative
• How to Vet an Agent Skill — review before installing