agent-cli

name	agent-cli
description	Patterns for building CLIs that serve both humans and AI agents. Covers tri-modal output (JSON/JSONL/human), typed exit codes, structured error contracts, zero-dependency arg parsing, topic-based help, service discovery, field projection, and auto agent-mode detection. Reference implementation: @side-quest/observability CLI. Use when: building a CLI, adding a command, CLI output format, agent-friendly CLI, machine-readable output, JSON CLI contract, exit codes, --json flag, NDJSON streaming, how should my CLI work with agents, CLI design patterns.
allowed-tools	Read, Glob, Grep

Agent-Native CLI Patterns

Patterns for building CLIs that work for humans and AI agents, based on the @side-quest/observability reference implementation.

Reference Implementation

File: packages/server/src/cli/command.ts (1634 lines) Tests: packages/server/src/cli/command.test.ts Repo: ~/code/side-quest-observability

This is a production CLI that demonstrates every pattern documented here. When answering questions, read the relevant sections of command.ts to show real code -- not hypothetical examples.

Classification

Route the user's question to the appropriate reference file based on their intent.

Intent	Trigger Signals	Reference File
Output format	JSON, JSONL, human output, --json, machine-readable, output contract	references/output-contract.md