Cli DevelopmentCAUTION

The AI toolkit for building reliable browser automations

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: cli-development
description: |
  Design and implement command-line interfaces with subcommand-scoped help, actionable success output, and debuggable failure output. Use when creating or modifying CLI commands, argument parsing, help and usage text, exit codes, or command UX for humans and agents.
---

# CLI Development

Build CLIs that stay actionable in both success and failure paths.

## Core Principles

1. Avoid dead ends.
   - Print next steps when a reasonable next action exists.
   - On terminal completion, state that no further action is required.
2. Make failures diagnosable.
   - Print known state, failed operation, and likely cause.
   - Include recovery commands and focused help text.
   - Include usage text for argument or syntax errors.
3. Keep output minimal and context-efficient.
   - Use short defaults.
   - Show detail only when requested by flags or when needed to recover from failure.
4. Scope help to subcommands.
   - Keep root help high-level.
   - Put detailed flags, examples, and edge cases in subcommand help.

## Command Contract

1. Keep output deterministic.
   - Use stable wording and field names.
   - Avoid random ordering in lists.
2. Use conventional stream behavior.
   - Write primary result data to stdout.
   - Write diagnostics, warnings, and human-oriented guidance to stderr.
   - In machine mode (`--json`), print a complete structured success or error object to stdout.
   - Document that automation should capture both stdout and stderr for full logs.
3. Return meaningful exit codes.
   - `0` for success.
   - Non-zero codes map to clear failure classes.
4. Support automation.
   - Add machine-readable output mode such as `--json`.
   - Keep human-readable output as the default.
5. Support safe execution.
   - Add `--dry-run` for mutating commands.
   - Make retry behavior explicit.

## Help and Error Pattern

Use this pattern for each subcommand:

1. One-line purpose.
2. Usage line.
3. Required arguments.
4. Optional flags.
5. Examples, including one failure-recovery example.

When returning an error, format output in this order:

1. Error summary.
2. Known state.
3. Recovery options.
4. Exact next command.
5. Relevant subcommand help hint.

## Output Templates

Success with next step:

```text
Created release r123.
Next: mycli release publish r123
```

Success without next step:

```text
Published release r123.
No further action required.
```

Failure with recovery:

```text
Error: failed to publish release r123 (artifact missing).
Known state: release exists, build step did not produce dist/app.tar.gz.
Try: mycli release build r123
Then: mycli release publish r123
Help: mycli help release publish
```

## Implementation Checklist

- Define root command and subcommand boundaries.
- Write subcommand help before command logic.
- Implement parser and validate required arguments.
- Implement success and failure output contracts.
- Verify stream contract: parseable payloads on stdout, diagnostics on stderr.
- Add tests for success, parser errors, and runtime failures.
- Verify each failure path includes state and next steps.

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

.claude/skills/glimpse-changes

.claude/skills/improve-codebase-architecture

.claude/skills/mintlify

.claude/skills/turborepo

.claude/skills/writing-tests

Gates applied: no_behavioural_pass.