CLI Patterns for Agentic Workflows Skill

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

stdout is sacred - Only data. Never progress, never logging, never decoration.
stderr is for humans - Progress bars, colors, tables, warnings live here.
Exit codes have meaning - Scripts can branch on failure mode.
Help includes examples - The fastest path to understanding.
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

Boolean flags take no value: --json not --json=true
Short flags can combine: -vq equals -v -q
Unknown flags are errors: Never silently ignore
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:

Brief description (one line)
Usage syntax
Options with descriptions
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:

Basic usage - Simplest invocation
Common filters - Most-used options
JSON piping - How to chain with jq
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

Environment variable (CI/CD, testing)
- MYTOOL_API_TOKEN or similar
- Highest priority, overrides all other sources
OS Keyring (primary storage - secure)
- Windows: Credential Manager
- macOS: Keychain
- Linux: Secret Service (GNOME Keyring, KWallet)
- Encrypted at rest, per-user isolation
.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

Agent Skills: CLI Patterns for Agentic Workflows

Install this agent skill to your local

Skill Files