# CLI For Agent

> Design or review CLIs so coding agents can run them reliably: non-interactive flags first, layered --help with real copy-pasteable examples, stdin/pipeline support, fail-fast errors that include a correct invocation, idempotency, --dry-run/--yes for destructive actions, and machine-useful success output. Use when building a CLI, adding commands or subcommands, writing --help text, or when asked for an "agent-friendly CLI". Not for GUIs, TUIs, or library APIs (no CLI surface to design).

- Skill: `ariadoss/cli-for-agent` (Agent Skill)
- Install (CLI): `npx get-skill add ariadoss/cli-for-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ariadoss/cli-for-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: ariadoss (https://skillmd.com/u/ariadoss)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/ariadoss/cli-for-agent

---


# /cli-for-agent

Human-oriented CLIs 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.

## `--help` that works

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

```text
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.

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

## Idempotency

- Agents retry often. The same successful command run twice should be safe
  (no-op or explicit "already done"), not duplicate side effects.

## Destructive actions

- Add `--dry-run` (or equivalent) so agents can preview plans before
  committing.
- Offer `--yes`/`--force` to skip confirmations while keeping the safe default
  for humans.

## Predictable structure

- Use a consistent pattern everywhere, e.g. `resource` + `verb`: if `mycli
  service list` exists, `mycli deploy list` and `mycli config list` should
  follow the same shape.

## Success output

- On success, return machine-useful data: IDs, URLs, durations. Plain text is
  fine; avoid relying on decorative output alone.

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

## When reviewing an existing CLI

- Check: non-interactive path, layered help, examples on `--help`,
  stdin/pipeline story, error messages with invocations, idempotency,
  dry-run, confirmation bypass flags, consistent command structure,
  structured success output.

---

Adapted from [cursor/plugins](https://github.com/cursor/plugins)
`cli-for-agent/skills/cli-for-agents/SKILL.md` (MIT, © Cursor). Vendored per
the superskills imported-skills rule; changes here do not track upstream.

