agent-cli
Add agent-friendly --json NDJSON output to Python CLI scripts, or scaffold a complete cli_utils package for a project. Use this skill when the user wants to make scripts machine-readable for AI agents, add --json flags, convert print statements to structured JSON, build a CLI helper library, create an open-source CLI-for-agents package, add structured logging, or make CLI output machine-readable. Also use when the user mentions NDJSON, structured CLI output, agent-friendly CLI, non-interactive scripts, or JSON I/O for automation.
glebis · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add glebis/claude-skills --skill agent-cliAbout this skill
name: agent-cli description: Add agent-friendly --json NDJSON output to Python CLI scripts, or scaffold a complete cli_utils package for a project. Use this skill when the user wants to make scripts machine-readable for AI agents, add --json flags, convert print statements to structured JSON, build a CLI helper library, create an open-source CLI-for-agents package, add structured logging, or make CLI output machine-readable. Also use when the user mentions NDJSON, structured CLI output, agent-friendly CLI, non-interactive scripts, or JSON I/O for automation.
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":
- Scan the script for output points
- Generate
cli_utils.pyif the project doesn't have one - Replace all output with structured helpers
- 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:
- Scaffold a full Python package with pyproject.toml, tests, license, README
- Include all helpers:
json_log,json_error,die,log,add_json_flag,enable_json,is_json - Add pytest test suite with full coverage
- 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
--jsonopt-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 patternif 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
When generating cli_utils.py, produce exactly this (adapt only if the project has specific needs):
"""Shared helpers for JSON CLI output."""
import json
import os
import sys
from datetime import datetime, timezone
_json_mode = False
def enable_json():
global _json_mode
_json_mode = True
def is_json():
return _json_mode
def json_log(event: str, **kwargs):
"""Emit one NDJSON line to stdout."""
obj = {"event": event, "ts": datetime.now(timezone.utc).isoformat(), **kwargs}
print(json.dumps(obj, default=str), flush=True)
def json_error(message: str, **kwargs):
"""Emit a structured error event."""
json_log("error", message=message, **kwargs)
def die(message: str, code: int = 1, **kwargs):
"""Print error and exit — JSON or human depending on mode."""
if _json_mode:
json_error(message, **kwargs)
else:
print(message, file=sys.stderr)
sys.exit(code)
def add_json_flag(parser):
"""Add --json flag to an argparse parser."""
parser.add_argument("--json", action="store_true",
help="NDJSON output for agent consumption")
def log(message: str, **json_kwargs):
"""Print human message normally, or emit JSON event if --json is active."""
if _json_mode:
json_log(json_kwargs.pop("event", "info"), message=message, **json_kwargs)
else:
print(message)
def json_ready(**kwargs):
"""Emit the readiness signal — only in JSON mode. Call early in daemon startup."""
if _json_mode:
json_log("ready", pid=os.getpid(), **kwargs)
Converting a Script — Step by Step
Step 1: Scan for output points
Search the target script for all places that produce output or exit:
grep -n 'print(\|sys\.exit\|exit(\|input(\|os\.system.*say' TARGET.py
Categorize each hit:
- Informational print → replace with
log(message, event="descriptive_name") - Error + exit → replace with
die(message) - Status line with \r → replace with
if is_json(): json_log("status", ...) else: print("\r...", end="", flush=True) - Interactive input() → guard with
if not is_json():or add--no-interactiveflag - Side effects (say, osascript, notifications) → guard with
if not is_json(): - Import-time errors (before argparse runs) → use
sys.exit("message")(writes to stderr)
Step 2: Add the import and flag
At the top of the script, after existing imports:
from cli_utils import add_json_flag, enable_json, is_json, json_log, log, die
In the if __name__ == "__main__" block, add to argparse:
add_json_flag(parser)
args = parser.parse_args()
if args.json:
enable_json()
Step 3: Replace each output point
Apply the categorization from Step 1. Key patterns:
Simple informational:
# Before
print(f"Connected to {device}")
# After
log(f"Connected to {device}", event="connected", device=device)
Error + exit:
# Before
print("Device not found")
sys.exit(1)
# After
die("Device not found")
Daemon readiness (first output after initialization):
# Before
print(f"Server running on port {port}")
# After — json_ready() only emits in JSON mode, so always call it + human fallback
json_ready(port=port)
log(f"Server running on port {port}", event="ready", port=port)
Status lines (\r overwrite):
# B
Read the complete source ↗