agentic-cli-design

Files (5)

• SKILL.md
• anti-patterns.md · references/
• principles.md · references/
• scorecard.md · references/
• templates.md · references/

SKILL.md (first lines)

# Agentic CLI Design

## Overview

**Agentic CLI Design** is a design philosophy that treats CLIs not as "tools for humans to operate in terminals," but as **protocols/APIs that LLMs/agents can safely, reliably, and repeatably invoke**.

The success criteria is that agents can operate the CLI:

- **Without confusion** (options are explicit)
- **Without breaking things** (safe-by-default)
- **Without getting stuck** (non-interactive, timeout/retry strategies)
- **Repeatedly** (idempotent, re-execution tolerant)
- **With self-healing** (observable, self-describing)

This skill provides a comprehensive framework for designing and evaluating CLI tools for agent use.

## Core Definition

**Agentic CLI Design** = _Design principles for CLIs that enable LLM/agents to execute commands safely and reliably in non-interactive, repetitive, failure-prone environments._

Rather than optimizing for human "feel," we optimize for **machines to read, decide, re-execute, and recover**.

## The 7 Principles

### P1. Machine-readable (Primary Output Format)

**Machine-readable output is the primary interface, not human-readable text.**

- Provide `--json` / `--output json|yaml|text` as a first-class option
- Strict separation: stdout=results / stderr=logs/progress (never mix)
- **Errors are also structured** (preferably JSON)
- Schema stability (manage breaking changes with `schemaVersion`)

**When to use**: Every CLI command should support structured output.

### P2. Non-interactive by Default

**Interactive prompts should not be the default behavior.**

- Don't assume interactive prompts
- Provide `--yes` / `--force` / `--no-confirm` / `--non-interactive` flags
- Must complete successfully in TTY-less environments (CI, job runners)

**When to use**: Any command that might prompt for user input.

### P3. Idempotent & Replayable

**Commands should be safe to run multiple times with the same result.**

- Send/create operations accept dedupe-key / client-request-id
- "Already exists" behavior is configurable: `--if-exists skip|update|error`
- Retrieval uses explicit pagination: `--limit` `--cursor` `--all`

**When to use**: Any write operation or data retrieval command.

### P4. Safe-by-default

**Destructive operations require explicit confirmation.**

- Destructive operations support `--dry-run` / `--confirm <id>`
- Deletion requires `--force` or similar (default prevents accidents)
- Permissions/scopes are minimized; insufficient permissions return "next steps"

**When to use**: Any command that modifies or deletes data.

### P5. Observable & Debuggable

**Operations must be traceable and debuggable.**

- Provide `--verbose` / `--debug` / `--log-format json`
- Accept `--trace-id` for correlation IDs
- Exit codes are categorized for automatic recovery:
  - 0: success
  - 2: invalid arguments
  - 3: authentication/permission
  - 4: retryable (rate limit, transient errors)

**When to use**: All commands should support observability flags.

### P6. Context-efficient

**Minimize token/context consumption for LLM agents.**

- `--fields/--select` (projection)
- `--output ndjson` (streaming)
- Default is summary; details via `get`/`--include-*` explicitly
- Rich server-side filtering (since/until/query/type...)

**When to use**: Commands that return large datasets or detailed information.

### P7. Introspectable (Self-describing CLI)

**The CLI itself can emit its specification in machine-readable format.**

MCP tools have schema definitions, but CLIs are often black boxes. Solution: **CLI emits its own specification**.

- `commands --json` (list commands and arguments)
- `schema --command ... --output json-schema` (per-command JSON Schema)
- `--help --json` (examples, exit codes, error vocabulary)
- `install-skills` (emit/install the CLI's own agent skill from `<project dir>/skills`)
- `--output json` top-level fixed fields:
  - `schemaVersion`, `type`, `ok`

Recommended `install-skills` behavior:

- Installs the CLI's own usage skill, not arbitrary third-party skills
- Reads skill source from `<project dir>/skills`
- Default destination: `./.agents/skills`
- `install-skills --global`: `~/.agents/skills`
- `install-skills --claude`: `./.claude/skills`
- `install-skills --claude --global`: `~/.claude/skills`

**When to use**: For CLIs that need to be discoverable and self-documenting to agents.

## Reference Documentation

This skill includes detailed reference materials organized by topic:

### [references/principles.md](references/principles.md)

From marcioaltoe/skills, MIT.

More from marcioaltoe/skills