0xDarkMatter/cli-ops

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

This is the most critical rule:

| Stream | Content | When | |--------|---------|------| | stdout | Data only | Always | | stderr | Everything else | Interactive mode |

stdout receives:

• JSON when --json is set
• Minimal text output when interactive
• Nothing else. Ever.

stderr receives:

• Progress indicators (spinners, bars)
• Status messages ("Fetching...", "Done")
• Warnings
• Rich formatted tables
• Colors and decoration
• Debug information (--verbose)

Interactive Detection

import sys

def is_interactive() -> bool:
    """True if connected to a terminal, not piped."""
    return sys.stdout.isatty() and sys.stderr.isatty()

| Context | stdout.isatty() | Behavior | |---------|-----------------|----------| | Terminal | True | Rich output to stderr, summary to stdout | | Piped (\| jq) | False | Minimal/JSON to stdout | | Redirected (> file) | False | Minimal to stdout | | --json flag | Any | JSON to stdout, suppress stderr noise |

JSON Output Schema

See references/json-schemas.md for complete JSON response patterns.

Key conventions:

• List responses: {"data": [...], "meta": {...}}
• Single item: {"data": {...}}
• Errors: {"error": {"code": "...", "message": "..."}}
• ISO 8601 dates, decimal money, string IDs

---

Exit Codes

Semantic exit codes that scripts can rely on:

| Code | Name | Meaning | When | |------|------|---------|------| | 0 | SUCCESS | Operation completed | Everything worked | | 1 | ERROR | General/unknown error | Unexpected failures | | 2 | AUTH_REQUIRED | Not authenticated | No token, token expired | | 3 | NOT_FOUND | Resource missing | ID doesn't exist | | 4 | VALIDATION | Invalid input | Bad arguments, failed validation | | 5 | FORBIDDEN | Permission denied | Authenticated but not authorized | | 6 | RATE_LIMITED | Too many requests | API throttling | | 7 | CONFLICT | State conflict | Concurrent modification, duplicate |

Usage

# Script can branch on exit code
mytool items get item-001 --json
case $? in
  0) echo "Success" ;;
  2) echo "Need to authenticate" && mytool auth login ;;
  3) echo "Item not found" ;;
  *) echo "Error occurred" ;;
esac

Implementation

# Constants
EXIT_SUCCESS = 0
EXIT_ERROR = 1
EXIT_AUTH_REQUIRED = 2
EXIT_NOT_FOUND = 3
EXIT_VALIDATION = 4
EXIT_FORBIDDEN = 5
EXIT_RATE_LIMITED = 6
EXIT_CONFLICT = 7

# Usage
raise typer.Exit(EXIT_NOT_FOUND)

---

Error Handling

Error Output Format

With --json, errors output structured JSON to stdout AND a message to stderr:

stderr:

Error: Item not found

stdout:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Item not found",
    "details": {
      "item_id": "bad-id"
    }
  }
}

Error Codes

| Code | Exit | Meaning | |------|------|---------| | AUTH_REQUIRED | 2 | Must authenticate first | | TOKEN_EXPIRED | 2 | Token needs refresh | | FORBIDDEN | 5 | Insufficient permissions | | NOT_FOUND | 3 | Resource doesn't exist | | VALIDATION_ERROR | 4 | Invalid input | | INVALID_ARGUMENT | 4 | Bad argument value | | MISSING_ARGUMENT | 4 | Required argument missing | | RATE_LIMITED | 6 | Too many requests | | CONFLICT | 7 | State conflict | | ALREADY_EXISTS | 7 | Duplicate resource | | INTERNAL_ERROR | 1 | Unexpected error | | API_ERROR | 1 | Upstream API failed | | NETWORK_ERROR | 1 | Connection failed |

Implementation Pattern

def _error(
    message: str,
    code: str = "ERROR",
    exit_code: int = EXIT_ERROR,
    details: dict = None,
    as_json: bool = False,
):
    """Output error and exit."""
    error_obj = {"error": {"code": code, "message": message}}
    if details:
        error_obj["error"]["details"] = details

    if as_json:
        print(json.dumps(error_obj, indent=2))

    # Always print human message to stderr
    console.print(f"[red]Error:[/red] {message}")
    raise typer.Exit(exit_code)

---

Help System

Help Requirements

Every --help output MUST include:

1. Brief description (one line)
2. Usage syntax
3. Options with descriptions
4. Examples (critical for discovery)

Help Format Template

<one-line description>

Usage: <tool> <resource> <action> [OPTIONS] [ARGS]

Arguments:
  <arg>          Description of positional argument

Options:
  -s, --status TEXT    Filter by status
  -n, --limit INTEGER  Max results [default: 20]
  --json               Output as JSON
  -h, --help           Show this help

Examples:
  <tool> <resource> <action>
  <tool> <resource> <action> --status active
  <tool> <resource> <action> --json | jq '.[0]'

Examples Are Critical

Examples should show:

1. Basic usage - Simplest invocation
2. Common filters - Most-used options
3. JSON piping - How to chain with jq
4. Real-world scenarios - Actual use cases

---

Authentication

Auth Commands

Tools requiring authentication MUST implement:

<tool> auth login      # Interactive authentication
<tool> auth status     # Check current state
<tool> auth logout     # Clear credentials

Credential Storage Priority

Recommended: OS keyring with fallbacks for maximum security

1. Environment variable (CI/CD, testing)

   • MYTOOL_API_TOKEN or similar
   • Highest priority, overrides all other sources

2. OS Keyring (primary storage - secure)

   • Windows: Credential Manager
   • macOS: Keychain
   • Linux: Secret Service (GNOME Keyring, KWallet)
   • Encrypted at rest, per-user isolation

3. .env file (development fallback)

   • Plain text in current directory
   • Convenient for local development
   • Must be in .gitignore

Dependencies:

dependencies = [
    "keyring>=24.0.0",      # OS keyring access
    "python-dotenv>=1.0.0", # .env file support
]

Simple alternative: Just config file in ~/.config/<tool>/

• Good for tools without sensitive credentials
• Or when OS keyring adds too much complexity

See references/implementation.md for complete credential storage implementations.

Unauthenticated Behavior

When auth is required but missing:

$ mytool items list
Error: Not authenticated. Run: mytool auth login
# exit code: 2

$ mytool items list --json
# stderr: Error: Not authenticated. Run: mytool auth login
{"error": {"code": "AUTH_REQUIRED", "message": "Not authenticated. Run: mytool auth login"}}
# exit code: 2

---

Data Conventions

Date Handling

Input (Flexible): Accept multiple formats for user convenience

| Format | Example | Interpretation | |--------|---------|----------------| | ISO date | 2025-01-15 | Exact date | | ISO datetime | 2025-01-15T10:30:00Z | Exact datetime | | Relative | today, yesterday, tomorrow | Current/previous/next day | | Relative | last, this (with context) | Previous/current period |

Output (Strict): Always output ISO 8601

{
  "created_at": "2025-01-15T10:30:00Z",
  "due_date": "2025-02-15",
  "month": "2025-01"
}

Money

• Store as decimal number, not cents
• Include currency when ambiguous
• Never format (no "$" or "," in JSON)

{
  "total": 1250.50,
  "currency": "USD"
}

IDs

• Always strings (even if numeric)
• Preserve exact format from source

{
  "id": "abc_123",
  "legacy_id": "12345"
}

Enums

• UPPER_SNAKE_CASE in JSON
• Case-insensitive input

# All equivalent
--status DRAFT
--status draft
--status Draft

{"status": "IN_PROGRESS"}

---

Filtering & Pagination

Common Filter Patterns

# By status
--status DRAFT
--status active,pending    # Multiple values

# By date range
--from 2025-01-01 --to 2025-01-31
--month 2025-01
--month last

# By related entity
--user "Alice"
--project "Project X"

# Text search
--search "keyword"
-q "keyword"

# Boolean filters
--archived
--no-archived
--include-deleted

Pagination

# Limit results
--limit 50
-n 50

# Offset-based
--page 2
--offset 20

# Cursor-based
--cursor "eyJpZCI6MTIzfQ=="
--after "item_123"

---

Implementation

See references/implementation.md for complete Python implementation templates including:

• CLI skeleton with Typer
• Client pattern with httpx
• Error handling
• Authentication flows
• Testing patterns

---

Anti-Patterns

❌ Output Pollution

# BAD: Progress to stdout
$ bad-tool items list --json
Fetching items...
[{"id": "1"}]
Done!

# GOOD: Only JSON to stdout
$ good-tool items list --json
[{"id": "1"}]

❌ Interactive Prompts

# BAD: Prompts in non-interactive context
$ bad-tool items create
Enter name: _

# GOOD: Fail fast with required flags
$ good-tool items create
Error: --name is required

❌ Inconsistent Flags

# BAD: Different flags for same concept
$ tool1 list -j
$ tool2 list --format=json

# GOOD: Same flags everywhere
$ tool1 list --json
$ tool2 list --json

❌ Silent Failures

# BAD: Success exit code on failure
$ bad-tool items delete bad-id
Item not found
$ echo $?
0

# GOOD: Semantic exit code
$ good-tool items delete bad-id
Error: Item not found: bad-id
$ echo $?
3

---

Quick Reference

Must-Have Checklist

• [ ] <tool> --version
• [ ] <tool> --help with examples
• [ ] <tool> <resource> list [--json]
• [ ] <tool> <resource> get <id> [--json]
• [ ] Semantic exit codes (0, 1, 2, 3, 4, 5, 6, 7)
• [ ] Errors to stderr, data to stdout
• [ ] Valid JSON on --json
• [ ] Stream separation (stdout = data, stderr = UI)

Recommended Additions

• [ ] Authentication commands (auth login, auth status, auth logout)
• [ ] Create/Update/Delete operations
• [ ] --quiet and --verbose modes
• [ ] --dry-run for mutations
• [ ] Pagination (--limit, --page)
• [ ] Filtering (status, date range, search)
• [ ] Automated tests

---

Framework Choice

Typer (preferred for new tools):

• Type hints provide automatic validation
• Built-in help generation
• Rich integration for beautiful output
• Less boilerplate than Click

Click (acceptable for existing tools):

• Typer is built on Click (100% compatible)
• Well-structured Click code doesn't need migration
• Both must follow same output conventions

# Typer (preferred)
import typer
from rich.console import Console

app = typer.Typer()
console = Console(stderr=True)  # UI to stderr

# Click (acceptable)
import click
from rich.console import Console

console = Console(stderr=True)  # Same pattern