home / skills / michalvavra / agents / create-cli

create-cli skill

safe

/skills/create-cli

This skill guides you design CLI tools with consistent UX, robust options, clear help, and safe error handling.

npx playbooks add skill michalvavra/agents --skill create-cli

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.1 KB

---
name: create-cli
description: Design CLI tools with consistent UX patterns.
---

# Create CLI

Design CLI surface area: syntax, flags, output, error handling.

## Conventions

- Long options preferred (`--from` not `-f`)
- stdout for data, stderr for progress/errors
- Exit codes: 0=success, 1=runtime error, 2=usage error
- Include `--help`, `--json`, `--quiet`
- Validate early, fail fast

## Output

- Default: human-readable tables
- `--json`: JSON output (implies quiet)
- `--quiet`: suppress progress
- Respect `NO_COLOR` env

## Errors

```
<name>: <message>
Try '<name> --help'
```

## Destructive Operations

- Confirm when stdin is TTY
- `--force` to skip confirmation
- `--dry-run` to preview

## Help Format

```
<name> - <one-line description>

USAGE
    <name> [OPTIONS] <ARGS>

OPTIONS
    --option <VALUE>    Description [default: X]
    --help              Show this help

EXAMPLES
    <name> arg1 arg2
```

---

See [references/node-js.md](references/node-js.md) - Node.js with parseArgs
See [references/python-uv.md](references/python-uv.md) - Python with uv

See [clig.dev](https://clig.dev/) for comprehensive guidelines.

Overview

This skill helps design command-line interfaces with consistent UX patterns for shell-based tools. It captures conventions for syntax, flags, output formats, error handling, and destructive operation safeguards to produce predictable, user-friendly CLIs. It is focused on practical rules you can apply across languages and runtimes.

How this skill works

The skill inspects a proposed CLI surface and enforces conventions: prefer long options, separate data (stdout) from progress/errors (stderr), and apply standard exit codes. It specifies help layout, default human-readable output with an optional --json mode, and behavior for quiet and non-interactive runs. It also defines confirmation and dry-run behavior for destructive commands.

When to use it

Designing new command-line tools or wrapping APIs with a CLI
Standardizing CLI behavior across a team or organization
Revamping an existing tool to improve UX consistency
Creating CLIs that will be consumed by scripts or CI systems
Ensuring accessibility for both interactive and programmatic use

Best practices

Use long options by default (e.g., --from) and include clear, one-line descriptions
Send data to stdout and progress/errors to stderr; support --json for machine output
Implement exit codes: 0 success, 1 runtime error, 2 usage error
Provide --help, --json, and --quiet; make --json imply quiet and stable output
Fail fast: validate inputs early and display usage on incorrect arguments
Respect NO_COLOR and avoid color in non-TTY or when NO_COLOR is set

Example use cases

A file-transfer CLI that prints progress to stderr and outputs machine-readable JSON on --json
An admin tool that prompts for confirmation on destructive actions, supports --dry-run, and accepts --force to skip prompts
A deployment helper that exposes consistent --help and examples blocks for discoverability
A wrapper script intended for CI that relies on exit codes and quiet, non-interactive behavior

FAQ

What should --json include versus human output?

--json must provide structured data representing the core result (no progress text). Human output can be formatted tables; --json implies --quiet so only the machine-readable payload is emitted.

When to require confirmation and when to use --force?

Require interactive confirmation when stdin is a TTY for destructive actions. Provide --force to skip confirmation and --dry-run to preview changes; CI should use --force in controlled contexts.