Design and build agent-first CLIs with HATEOAS JSON responses, context-protecting output, and self-documenting command trees. Use when creating new CLI tools, adding commands to existing CLIs such as joelclaw, or reviewing CLI design for agent-friendliness. Triggers on 'build a CLI', 'add a command', 'CLI design', 'agent-friendly output', or any task involving command-line tool creation.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Design and build agent-first CLIs with HATEOAS JSON responses, context-protecting output, and self-documenting command trees. Use when creating new CLI tools, adding commands to existing CLIs such as joelclaw, or reviewing CLI design for agent-friendliness. Triggers on 'build a CLI', 'add a command', 'CLI design', 'agent-friendly output', or any task involving command-line tool creation.
version
1.1.0
author
Joel Hooks
tags
["joelclaw","cli","agentic","ux","json"]
disable-model-invocation
true
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:
params.*.value — pre-filled from context (agent can override)
params.*.default — value if omitted
params.*.enum — valid choices
{"ok":true,"command":"joelclaw send pipeline/video.download","result":{"event_id":"01KHF98SKZ7RE6HC2BH8PW2HB2","status":"accepted"},"next_actions":[{"command":"joelclaw run <run-id>","description":"Check run status for this event","params":{"run-id":{"value":"01KHF98SKZ7RE6HC2BH8PW2HB2","description":"Run ID (ULID)"}}},{"command":"joelclaw logs <source> [--lines <lines>] [--grep <text>] [--follow]","description":"View worker logs","params":{"source":{"enum":["worker","errors","server"],"default":"worker"}}},{"command":"joelclaw status","description":"Check system health"}]}
next_actions are contextual — they change based on what just happened. A failed command suggests different next steps than a successful one. Templates are the agent's affordances — they show what's parameterizable, what values are valid, and what the current context pre-fills.
3. Self-documenting command tree
Agents discover commands via two paths: the root command (JSON tree) and --help (Effect CLI auto-generated). Both must be useful.
Root command (no args) returns the full command tree as JSON:
{"ok":true,"command":"joelclaw","result":{"description":"JoelClaw — personal AI system CLI","health":{"server":{...},"worker":{...}},"commands":[{"name":"send","description":"Send event to Inngest","usage":"joelclaw send <event> -d '<json>'"},{"name":"status","description":"System status","usage":"joelclaw status"},{"name":"gateway","description":"Gateway operations","usage":"joelclaw gateway status"}]},"next_actions":[...]}
--help output is auto-generated by Effect CLI from Command.withDescription(). Every subcommand must have a description — agents always call --help and a bare command list with no descriptions is useless.
// ❌ Agents see a blank command listconst status = Command.make("status", {}, () => ...)
// ✅ Agents see what each command doesconst status = Command.make("status", {}, () => ...).pipe(
Command.withDescription("Active sessions, queue depths, Redis health")
)
COMMANDS
- status Active sessions, queue depths, Redis health
- diagnose [--hours integer] Layer-by-layer health check
- review [--hours integer] Recent session context
4. Context-protecting output
Agents have finite context windows. CLI output must not blow them up.
Rules:
Terse by default — minimum viable output
Auto-truncate large outputs (logs, lists) at a reasonable limit
When truncated, include a file path to the full output
Never dump raw logs, full transcripts, or unbounded lists
{"ok":true,"command":"joelclaw logs","result":{"lines":20,"total":4582,"truncated":true,"full_output":"/var/folders/.../joelclaw-logs-abc123.log","entries":["...last 20 lines..."]},"next_actions":[{"command":"joelclaw logs <source> [--lines <lines>]","description":"Show more log lines","params":{"source":{"enum":["worker","errors","server"],"default":"worker"},"lines":{"default":20,"description":"Number of lines"}}}]}
5. Errors suggest fixes
When something fails, the response includes a fix field — plain language telling the agent what to do about it.
{"ok":false,"command":"joelclaw send pipeline/video.download","error":{"message":"Inngest server not responding","code":"SERVER_UNREACHABLE"},"fix":"Start the Inngest server pod: kubectl rollout restart statefulset/inngest -n joelclaw","next_actions":[{"command":"joelclaw status","description":"Re-check system health after fix"},{"command":"kubectl get pods [--namespace <ns>]","description":"Check pod status","params":{"ns":{"default":"joelclaw"}}}]}
Response Envelope
Every command uses this exact shape:
Success
{
ok: true,
command: string, // the command that was runresult: object, // command-specific payloadnext_actions: Array<{
command: string, // command template (POSIX syntax) or literaldescription: string, // what it doesparams?: Record<string, { // presence = command is a templatedescription?: string, // what this param meansvalue?: string | number, // pre-filled from current contextdefault?: string | number,// value if omittedenum?: string[], // valid choicesrequired?: boolean// true for <positional> args
}>
}>
}
Error
{
ok: false,
command: string,
error: {
message: string, // what went wrongcode: string// machine-readable error code
},
fix: string, // plain-language suggested fixnext_actions: Array<{
command: string, // command template or literaldescription: string,
params?: Record<string, { ... }> // same schema as success
}>
}
bun build src/cli.ts --compile --outfile joelclaw
cp joelclaw ~/.bun/bin/
Adding a new command
Define the command with Command.make
Return the standard JSON envelope (ok, command, result, next_actions)
Include contextual next_actions — what makes sense AFTER this specific command
Handle errors with the error envelope (ok: false, error, fix, next_actions)
Add to the root command's subcommands
Add to the root command's commands array in the self-documenting output
Rebuild and install
Streaming Protocol (NDJSON) — ADR-0058
Request-response covers the spatial dimension (what's the state now?). Streamed NDJSON covers the temporal dimension (what's happening over time?). Together they make the full system observable through one protocol.
When to stream
Stream when the command involves temporal operations — watching, following, tailing. Not every command needs streaming. Point-in-time queries (status, functions, runs) stay as single envelopes.
Streaming is activated by command semantics (--follow, watch, gateway stream), never by a global --stream flag.
Protocol: typed NDJSON with HATEOAS terminal
Each line is a self-contained JSON object with a type discriminator. The last line is always the standard HATEOAS envelope (result or error). Tools that don't understand streaming read the last line and get exactly what they expect.
Streaming commands subscribe to the same Redis pub/sub channels the gateway extension uses. pushGatewayEvent() middleware is the emission point — the CLI is just another subscriber.
