agent-cli

Agent-Friendly CLI Builder

Convert Python CLI scripts from human-only output to agent-consumable NDJSON, or scaffold a complete cli_utils package ready for open-source distribution.

Two Modes

Mode A: Convert an existing script

When the user points at a script and says "make this agent-friendly" or "add --json":

1. Scan the script for output points
2. Generate cli_utils.py if the project doesn't have one
3. Replace all output with structured helpers
4. Verify no raw output leaks in JSON mode

Mode B: Scaffold a complete package

When the user says "create a cli_utils package" or wants an open-source library:

1. Scaffold a full Python package with pyproject.toml, tests, license, README
2. Include all helpers: json_log, json_error, die, log, add_json_flag, enable_json, is_json
3. Add pytest test suite with full coverage
4. Add MIT license (or ask user preference)

Core Architecture

The fundamental pattern: every script gets a --json flag. When active, all stdout becomes newline-delimited JSON (NDJSON). Each line is a self-contained JSON object with a standard envelope.

The NDJSON Event Envelope

Every JSON line has at minimum:

{"event": "ready", "ts": "2026-04-30T14:00:00+00:00", "pid": 1234, "port": 8765}

• event — what happened (snake_case string)
• ts — ISO 8601 UTC timestamp
• Additional fields are event-specific kwargs

Why This Design

• NDJSON over JSON arrays: processable line-by-line, one bad line doesn't break the stream, works with grep/jq, low memory for long-running processes
• --json opt-in over default: preserves human DX, doesn't break existing scripts or habits
• Global mode flag over per-call checks: set once at startup, every helper respects it automatically
• die() over repeated if/else: the pattern if is_json(): json_error(); sys.exit(1) else: print(); sys.exit() appears constantly — die() collapses it to one line

The cli_utils.py Reference Implementation