---
name: CLI Development
slug: cli-development
category: Automation
description: CLI Development designs command-line interfaces with scoped help, clear success messages, and diagnosable failures. Use it when creating or updating commands, argument parsing, exit codes, or human- and machine-friendly CLI output.
github: "https://github.com/saffron-health/libretto/tree/main/.agents/skills/cli-development"
language: TypeScript
stars: 877
forks: 67
install: "npx degit https://github.com/saffron-health/libretto/tree/main/.agents/skills/cli-development ~/.claude/skills/cli-development"
installs_to: ~/.claude/skills/cli-development
source_path: .agents/skills/cli-development/SKILL.md
collection_size: 23
category_size: 1523
collection_url: "https://dirskills.com/collections/saffron-health/libretto"
added: 2026-08-22T05:21:17.911Z
last_synced: 2026-08-22T05:21:17.911Z
canonical_url: "https://dirskills.com/skills/cli-development"
---

# CLI Development

CLI Development designs command-line interfaces with scoped help, clear success messages, and diagnosable failures. Use it when creating or updating commands, argument parsing, exit codes, or human- and machine-friendly CLI output.

**Install:**

```bash
npx degit https://github.com/saffron-health/libretto/tree/main/.agents/skills/cli-development ~/.claude/skills/cli-development
```

## README

# 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.