cli-for-agents

What this skill does

# CLI For Agents

Build CLIs as one engine with two renderers:
- human mode: readable text or TUI
- agent mode: deterministic JSON or NDJSON

Do not maintain separate doctrine for the two audiences. Keep one command model and one source of truth, then render it differently.

## Use When

- designing a new CLI
- reviewing an existing CLI for agent compatibility
- adding commands, flags, or help text
- building watch/status/list commands that must work for both humans and agents
- tightening tests or guardrails around CLI output shape

## Core Model

### Dual-audience design

- Separate data production from presentation.
- The same command should support both human-readable and machine-readable output.
- Prefer `--json` for bounded results and `--ndjson` for streams or watch modes.
- If a TUI exists, provide a non-TUI path for the same command.

Examples:

```bash
# Human
mycli watch --task abc123

# Agent
mycli watch --task abc123 --ndjson --no-tui
```

### Canonical behavior

- The machine-readable mode is not a second implementation.
- Do not let TUI logic become the only place where important state transitions exist.
- The CLI should emit the same underlying facts in both modes.

### Stable contract model

- Treat `--json` as the stable contract for agents, scripts, and tests.
- Human-formatted output may change as wording, spacing, and styling improve.
- If a command is consumed programmatically, say so explicitly in help:
  - script against `--json`
  - human output may change

## Bounded default output

### Protect the context window

- Default output must be the minimum useful response, not the maximum available data.
- Pre-sort items so the most important rows appear first.
- Truncate long fields by default.
- Require explicit opt-in such as `--full`, `--verbose`, or `--raw` for large payloads.
- Preserve critical head and tail context when truncating command output.

Bad:

```bash
mycli list
# dumps every row and every field
```

Good:

```bash
mycli list
# top items only, scoped fields only

mycli list --full
# full payload
```

### Progressive disclosure

Prefer graduated retrieval over one-shot dumps:

- `list` or `search` for routing
- `summary` for bounded orientation
- `show --section <name>` for targeted expansion
- `show --full` only by explicit opt-in
- Discovery responses should stay routing-sized. A good default JSON envelope is:
  - `status`
  - `query`
  - `count`
  - `results`
  - `schema_version`
  - `next_step` when it makes the cheapest follow-up obvious
- Bounded reads should report how resolution happened when the command accepted natural input.
  Use fields such as `matched_on` or `resolved_from` so agents know whether they are operating on an exact ID or a search-resolved target.

If a CLI owns rich documents, logs, or traces, build commands around:

```text
summary -> section -> full
```

This is better for both humans and agents than dumping the entire surface by default.

## Structured discoverability

- Root help should group commands by job, not alphabetically.
- Mark likely entry points with hints like `start here`.
- Prefer command families that separate:
  - discovery
  - resolve
  - read
  - write
- Every command should define:
  - short summary: 5-10 words, starts with an action verb
  - long description: what it does, when to use it, how it differs from nearby commands
  - examples: 3-5 concrete copy-pasteable invocations
- Examples matter more than prose. Agents infer flag shape from examples.

Example layout:

```text
Task Management:
  send        Send a message to start or continue a task (start here)
  watch       Subscribe to live updates for a running task
  get         Retrieve the current state of a task

Discovery:
  describe    Inspect identity, skills, and capabilities
```

For repeated external-service, archive, or admin workflows, aim for:

```text
doctor      Verify setup, auth, version, and reachability
discover    Find top-level resources or containers
resolve     Turn names, URLs, or slugs into stable IDs
read        Fetch exact objects or bounded lists
write       Perform one named mutation with preview or dry-run support
request     Raw escape hatch
```

## Metadata quality is routing quality

- Titles, summaries, tags, and identifiers determine what an agent loads next.
- Short descriptions must be specific, not generic boilerplate.
- Result-card summaries and longer detail summaries should be distinct.
- Tags should be deterministic and meaningful, not inferred freeform when routing quality matters.
- Cross-links between related entities or docs should be deliberate, not opportunistic.

If the CLI returns knowledge-like records, every item should have:

- a strong title
- a bounded short summary
- optional deeper summary or section handles
- useful tags or categories
- adjacent links or next-hop identifiers when available

## Agent-first interoperability

### `doctor` is first-class

- Durable agent-facing CLIs should expose a `doctor` or equivalent command.
- `doctor --json` should verify config, auth source, version, endpoint reachability, and missing setup.
- If offline or fixture mode exists, `doctor --json` should report that explicitly instead of failing ambiguously.
- Later tasks should be able to run `tool-name --json doctor` first without reading docs.

### Non-interactive first

- Every required input must be expressible as a flag, stdin, or positional argument.
- Interactive prompts are fallback only, never the default requirement.
- Respect `NO_COLOR` and `[APP]_NO_TUI` environment variables.
- When stdout is piped, suppress TUI, prompts, spinners, and decorative color.

### `--json` on everything that returns data

- Commands that return data should support `--json`.
- Keep machine output bounded too; large structured payloads still need scoping.
- Prefer `--ndjson` for streaming or watch commands.
- Never force agents to scrape tables or prose when the command already knows the schema.
- Do not return silent false-positive success payloads for misses. If resolution fails, return a deterministic error shape with retry guidance and, when possible, ranked suggestions.

### Pipelines and stdin

- Accept stdin when composition is natural.
- Support `-` as stdin where appropriate.
- Let one command feed the next without requiring temp files.

Examples:

```bash
mycli search "stalled tasks" --json | mycli rerank --stdin
mycli build --json | mycli deploy --spec-json -
```

### Discover, then resolve, then read

- Discovery commands should return bounded lists with stable handles.
- Resolve commands should convert human input such as names, URLs, slugs, or permalinks into canonical IDs.
- Read commands should accept those stable IDs directly.
- Do not force agents to repeat broad searches when an exact read can follow a resolve step.
- If a command accepts natural-language input directly, let `summary` or `read` auto-resolve obvious first-try matches and expose the resolution mode in machine output.
- Multi-word natural queries should not require brittle quoting if the command intent is retrieval rather than mutation.

## Headless authentication

- Agents cannot complete browser auth flows reliably.
- Support headless auth such as env vars, tokens, service accounts, or pre-authenticated config.
- If interactive auth is unavoidable, fail immediately with a clear actionable hint.
- Never hang waiting for a browser login when running in no-TUI or machine-readable mode.

## Mutative safety

- Mutating commands should support `--dry-run`.
- Commands with confirmations should offer `--yes` or `--force`.
- Default behavior should remain safe for humans.
- Repeat successful operations safely: no-op or explicit `already done` beats duplicate side effects.

## Error guidance

- Fail fast on invalid flags, missing config, missing auth, or missing prerequisites.
- Print exact next-step commands in errors.
- Emit errors to stderr.
- Return deterministic exit codes:
  - `0` success
  - `1` gener