Cli Design

Agent-First CLI Design

CLIs in this system are agent-first, human-distant-second. Every command returns structured JSON that an agent can parse, act on, and follow. Humans are welcome to pipe through jq.

Core Principles

1. JSON always

Every command returns JSON. No plain text. No tables. No color codes. Agents parse JSON; they don't parse prose.

# This is the ONLY output format
joelclaw status
# → { "ok": true, "command": "joelclaw status", "result": {...}, "next_actions": [...] }

No --json flag. No --human flag. JSON is the default and only format.

2. HATEOAS — every response tells you what to do next

Every response includes next_actions — an array of command templates the agent can run next. Templates use standard POSIX/docopt placeholder syntax:

• <placeholder> — required argument
• [--flag <value>] — optional flag with value
• [--flag] — optional boolean flag
• No params field — literal command (run as-is)
• params present — template (agent fills placeholders)
• params.*.value — pre-filled from context (agent can override)
• params.*.default — value if omitted
• params.*.enum — valid choices