cli-ops（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

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

Standard Resource Actions

Flags & Options

Mandatory Flags

Every command MUST support:

Root command MUST additionally support:

Recommended Flags

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:

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()

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:

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

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

1. OS Keyring (primary storage - secure)

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

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

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