cli-ops

Files (5)

• SKILL.md
• .gitkeep · assets/
• implementation.md · references/
• json-schemas.md · references/
• .gitkeep · scripts/

SKILL.md (first lines)

# CLI Patterns for Agentic Workflows

Patterns for building CLI tools that AI assistants and power users can chain, parse, and rely on.

## Philosophy

Build CLIs for **agentic workflows** - AI assistants and power users who chain commands, parse output programmatically, and expect predictable behavior.

### Core Principles

| Principle | Meaning | Why It Matters |
|-----------|---------|----------------|
| **Self-documenting** | `--help` is comprehensive and always current | LLMs discover capabilities without external docs |
| **Predictable** | Same patterns across all commands | Learn once, use everywhere |
| **Composable** | Unix philosophy - do one thing well | Tools chain together naturally |
| **Parseable** | `--json` always available, always valid | Machine consumption without parsing hacks |
| **Quiet by default** | Data only, no decoration unless requested | Scripts don't break on unexpected output |
| **Fail fast** | Invalid input = immediate error | No silent failures or partial results |

### Design Axioms

1. **stdout is sacred** - Only data. Never progress, never logging, never decoration.
2. **stderr is for humans** - Progress bars, colors, tables, warnings live here.
3. **Exit codes have meaning** - Scripts can branch on failure mode.
4. **Help includes examples** - The fastest path to understanding.
5. **JSON shape is predictable** - Same structure across all commands.

---

## Command Architecture

### Structural Pattern

```
<tool> [global-options] <resource> <action> [options] [arguments]
```

Every CLI follows this hierarchy:

```
<tool>
├── --version, --help              # Global flags
├── auth                           # Authentication (if required)
│   ├── login
│   ├── status
│   └── logout
└── <resource>                     # Domain resources (plural nouns)
    ├── list                       # Get many
    ├── get <id>                   # Get one by ID
    ├── create                     # Make new (if supported)
    ├── update <id>                # Modify existing (if supported)
    ├── delete <id>                # Remove (if supported)
    └── <custom-action>            # Domain-specific verbs
```

### Naming Conventions

| Element | Convention | Valid Examples | Invalid Examples |
|---------|------------|----------------|------------------|
| Tool name | lowercase, 2-12 chars | `mytool`, `datactl` | `MyTool`, `my-tool-cli` |
| Resource | plural noun, lowercase | `invoices`, `users` | `Invoice`, `user` |
| Action | verb, lowercase | `list`, `get`, `sync` | `listing`, `getter` |
| Long flags | kebab-case | `--dry-run`, `--output-format` | `--dryRun`, `--output_format` |
| Short flags | single letter | `-n`, `-q`, `-v` | `-num`, `-quiet` |

### Standard Resource Actions

| Action | HTTP Equiv | Returns | Idempotent |
|--------|------------|---------|------------|
| `list` | GET /resources | Array | Yes |
| `get <id>` | GET /resources/:id | Object | Yes |
| `create` | POST /resources | Created object | No |
| `update <id>` | PATCH /resources/:id | Updated object | Yes |
| `delete <id>` | DELETE /resources/:id | Confirmation | Yes |
| `search` | GET /resources?q= | Array | Yes |

---

## Flags & Options

### Mandatory Flags

Every command MUST support:

| Flag | Short | Behavior | Output |
|------|-------|----------|--------|
| `--help` | `-h` | Show help with examples | Help text to stdout, exit 0 |
| `--json` | | Machine-readable output | JSON to stdout |

Root command MUST additionally support:

| Flag | Short | Behavior | Output |
|------|-------|----------|--------|
| `--version` | `-V` | Show version | `<tool> <version>` to stdout, exit 0 |

### Recommended Flags

| Flag | Short | Type | Purpose | Default |
|------|-------|------|---------|---------|
| `--quiet` | `-q` | bool | Suppress non-essential stderr | false |
| `--verbose` | `-v` | bool | Increase detail level | false |
| `--dry-run` | | bool | Preview without executing | false |
| `--limit` | `-n` | int | Max results to return | 20 |
| `--output` | `-o` | path | Write output to file | stdout |
| `--format` | `-f` | enum | Output format | varies |

### Flag Behavior Rules

1. **Boolean flags take no value**: `--json` not `--json=true`
2. **Short flags can combine**: `-vq` equals `-v -q`
3. **Unknown flags are errors**: Never silently ignore
4. **Repeated flags**: Last value wins (or error if inappropriate)

---

## Output Specification

### Stream Separation

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods