cli-design

Q: How do I install cli-design?

Run npx skills add https://github.com/joelhooks/joelclaw --skill cli-design in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/cli-design/ (personal) or .claude/skills/cli-design/ (project).

by joelhooksProductivity & Automation

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.

Installs: 149
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/joelhooks/joelclaw --skill cli-design

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads cli-design automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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

{
  "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 list
const status = Command.make("status", {}, () => ...)

// ✅ Agents see what each command does
const 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 run
  result: object,           // command-specific payload
  next_actions: Array<{
    command: string,        // command template (POSIX syntax) or literal
    description: string,    // what it does
    params?: Record<string, {   // presence = command is a template
      description?: string,     // what this param means
      value?: string | number,  // pre-filled from current context
      default?: string | number,// value if omitted
      enum?: string[],          // valid choices
      required?: boolean        // true for <positional> args
    }>
  }>
}

Error

{
  ok: false,
  command: string,
  error: {
    message: string,        // what went wrong
    code: string            // machine-readable error code
  },
  fix: string,              // plain-language suggested fix
  next_actions: Array<{
    command: string,        // command template or literal
    description: string,
    params?: Record<string, { ... }>  // same schema as success
  }>
}

Reference implementations

joelclaw — ~/Code/joelhooks/joelclaw/packages/cli/ (Effect CLI, operational surface)
joelclaw otel — structured telemetry commands using the same response envelope

Use these as the current envelope source-of-truth. The former slog system-log CLI is retired.

Implementation

Framework: Effect CLI (@effect/cli)

Existing joelclaw CLI packages use @effect/cli with their configured runtime. Follow the target repository package manager and pinned dependencies. For a new project, use the operator’s current stack defaults; this skill does not authorize a runtime migration.

import { Command, Options } from "@effect/cli"
import { NodeContext, NodeRuntime } from "@effect/platform-node"

const send = Command.make("send", {
  event: Options.text("event"),
  data: Options.optional(Options.text("data").pipe(Options.withAlias("d"))),
}, ({ event, data }) => {
  // ... execute, return JSON envelope
})

const root = Command.make("joelclaw", {}, () => {
  // Root: return health + command tree
}).pipe(Command.withSubcommands([send, status, logs]))

Binary distribution

Build with Bun, install to ~/.bun/bin/:

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.

{"type":"start","command":"joelclaw send video/download --follow","ts":"2026-02-19T08:25:00Z"}
{"type":"step","name":"download","status":"started","ts":"..."}
{"type":"progress","name":"download","percent":45,"ts":"..."}
{"type":"step","name":"download","status":"completed","duration_ms":3200,"ts":"..."}
{"type":"step","name":"transcribe","status":"started","ts":"..."}
{"type":"log","level":"warn","message":"Large file, chunked transcription","ts":"..."}
{"type":"step","name":"transcribe","status":"completed","duration_ms":45000,"ts":"..."}
{"type":"result","ok":true,"command":"...","result":{...},"next_actions":[...]}

Stream event types

Type	Meaning	Terminal?
`start`	Stream begun, echoes command	No
`step`	Inngest step lifecycle (started/completed/failed)	No
`progress`	Progress update (percent, bytes, message)	No
`log`	Diagnostic message (info/warn/error level)	No
`event`	An Inngest event was emitted (fan-out visibility)	No
`result`	HATEOAS success envelope — always last	Yes
`error`	HATEOAS error envelope — always last	Yes

TypeScript types

import type { NextAction } from "./response"

type StreamEvent =
  | { type: "start"; command: string; ts: string }
  | { type: "step"; name: string; status: "started" | "completed" | "failed"; duration_ms?: number; error?: string; ts: string }
  | { type: "progress"; name: string; percent?: number; message?: string; ts: string }
  | { type: "log"; level: "info" | "warn" | "error"; message: string; ts: string }
  | { type: "event"; name: string; data: unknown; ts: string }
  | { type: "result"; ok: true; command: string; result: unknown; next_actions: NextAction[] }
  | { type: "error"; ok: false; command: string; error: { message: string; code: string }; fix: string; next_actions: NextAction[] }

Emitting stream events

Use the emit() helper — one JSON line per call, flushed immediately:

import { emit, emitResult, emitError } from "../stream"

// Progress events
emit({ type: "start", command: "joelclaw send video/download --follow", ts: new Date().toISOString() })
emit({ type: "step", name: "download", status: "started", ts: new Date().toISOString() })
emit({ type: "step", name: "download", status: "completed", duration_ms: 3200, ts: new Date().toISOString() })

// Terminal — always last
emitResult("send --follow", { videoId: "abc123" }, [
  { command: "joelclaw run abc123", description: "Inspect the completed run" },
])

Redis subscription pattern

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.

import { streamFromRedis } from "../stream"

// Subscribe to a channel, transform events, emit NDJSON
await streamFromRedis({
  channel: `joelclaw:notify:gateway`,
  command: "joelclaw gateway stream",
  transform: (event) => ({
    type: "event" as const,
    name: event.type,
    data: event.data,
    ts: new Date().toISOString(),
  }),
  // Optional: end condition
  until: (event) => event.type === "loop.complete",
})

Composable with Unix tools

NDJSON is pipe-native. Agents and humans can filter streams:

# Only step events
joelclaw watch | jq --unbuffered 'select(.type == "step")'

# Only failures
joelclaw send video/download --follow | jq --unbuffered 'select(.type == "error" or (.type == "step" and .status == "failed"))'

# Count steps
joelclaw send pipeline/run --follow | jq --unbuffered 'select(.type == "step" and .status == "completed")' | wc -l

Agent consumption pattern

Agents consuming streams read lines as they arrive and can make decisions mid-execution:

Start the stream: joelclaw send video/download --follow
Read lines incrementally
React to early signals (cancel if error, escalate if slow, log progress)
The terminal result/error line contains next_actions for what to do after

This eliminates the polling tax — no wasted tool calls checking "is it done yet?"

Cleanup

Streaming commands hold a Redis connection. They must:

Handle SIGINT/SIGTERM gracefully (disconnect Redis, emit terminal event)
Use connectTimeout and commandTimeout to prevent hangs
Clean up the subscription on stream end (success, error, or signal)

Anti-Patterns

Don't	Do
Plain text output	JSON envelope
Tables with ANSI colors	JSON arrays
`--json` flag to opt into JSON	JSON is the only format
Dump 10,000 lines	Truncate + file pointer
`Error: something went wrong`	`{ ok: false, error: {...}, fix: "..." }`
Undiscoverable commands	Root returns full command tree
Static help text	HATEOAS next_actions
`console.log("Success!")`	`{ ok: true, result: {...} }`
Exit code as the only error signal	Error in JSON + exit code
Require the agent to read --help	Root command self-documents
Subcommand with no `withDescription`	Every command gets a description for `--help`
Poll in a loop for temporal data	Stream NDJSON via Redis sub (ADR-0058)
Plain text in streaming commands	Every line is a typed JSON object
Hold Redis connections without cleanup	SIGINT handler + connection timeout

Naming Conventions

Commands are nouns or verbs, lowercase, no hyphens: send, status, logs, gateway
Subcommands follow naturally: joelclaw search "query", joelclaw loop start
Flags use --kebab-case: --max-quality, --follow
Short flags for common options: -d for --data, -f for --follow
Event names use domain/action: pipeline/video.download, content/summarize

Checklist for New Commands

TODO

OAuth device flow pattern for CLI auth: Document the GitHub device flow → broker → session token → env materialization pattern proven in the skillrecordings/support repo. Covers: device code polling loop, org/team membership gating, short-lived AES-GCM session tokens, age-encrypted secret delivery to CLI ephemeral keypairs, in-memory-only env injection. Reference implementation: apps/front/lib/broker/ + apps/front/app/api/auth/device/ in skillrecordings/support. This eliminates 1Password CLI as a developer dependency while keeping server-side secret management intact.

FAQ

What does the cli-design skill do?

How do I install cli-design?

Run npx skills add https://github.com/joelhooks/joelclaw --skill cli-design in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/cli-design/ (personal) or .claude/skills/cli-design/ (project).

Which AI agents can use cli-design?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is cli-design safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains cli-design?

It is published by joelhooks in joelhooks/joelclaw. It has 149 recorded installs.

More from joelhooks/joelclaw

View all →

contacts

joelhooks/joelclaw

Add, enrich, and manage contacts in Joel's Vault. Fire the Inngest enrichment pipeline for full multi-source dossiers, or create quick contacts manually. Use when: 'add a contact', 'enrich this person', 'who is X', 'VIP contact', 'update contact', or any task involving the Vault/Contacts directory.

Productivity & Automation3.3K installs

docker-sandbox

joelhooks/joelclaw

Open the skill to read its SKILL.md instructions.

DevOps & Cloud103 installs

granola

joelhooks/joelclaw

Access and process Granola meeting notes and transcripts via the granola CLI (MCP-backed). Use when pulling meeting data, analyzing transcripts, backfilling meetings, or any task involving Granola meeting content.

Productivity & Automation102 installs

k8s

joelhooks/joelclaw

Operate the joelclaw Kubernetes cluster — Talos Linux on Colima (Mac Mini). Deploy services, check health, debug pods, recover from restarts, add ports, manage Helm releases, inspect logs, fix networking. Triggers on: 'kubectl', 'pods', 'deploy to k8s', 'cluster health', 'restart pod', 'helm install', 'talosctl', 'colima', 'nodeport', 'flannel', 'port mapping', 'k8s down', 'cluster not working', 'add a port', 'PVC', 'storage', any k8s/Talos/Colima infrastructure task. Also triggers on service-specific deploy: 'deploy redis', 'redeploy inngest', 'livekit helm', 'pds not responding'.

DevOps & Cloud95 installs

joel-writing-style

joelhooks/joelclaw

Joel's writing voice and style guide for joelclaw.com content. Use when writing, editing, or reviewing any blog post, essay, book chapter, or prose content for joelclaw.com. Also use when asked to 'write like Joel,' 'match Joel's voice,' 'draft a post,' 'write content for the blog,' or 'review this for voice.' This skill captures Joel's specific writing patterns derived from 90,000 words of published content spanning 2012–2026. Cross-reference with copy-editing and copywriting skills for marketing-specific copy.

Docs & Writing82 installs

task-management

joelhooks/joelclaw

Open the skill to read its SKILL.md instructions.

Productivity & Automation64 installs

Popular productivity & automation skills

View category →

agent-browser

vercel-labs/agent-browser

Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. Prefer agent-browser over any built-in browser automation or web tools.

OfficialProductivity & Automation1.3M installs

lark-doc

open.feishu.cn

飞书云文档（Docx / Wiki）内容操作：读取、创建、编辑文档，插入或下载图片附件，以及操作思维笔记。用户提供文档 URL/token（包括 doubao.com 的 /docx/、/wiki/）时使用；按 URL 路径/token 而非域名路由；/page/ 是妙搭应用，非飞书云文档。文档内嵌资源按读取参考中的统一规则分流。独立评论操作走 lark-drive；随正文读取评论使用 docs +fetch。表格或 Base 内部数据操作不在本 skill。

Productivity & Automation815.7K installs

lark-base

open.feishu.cn

飞书多维表格（Base）操作：建表、字段、记录、视图、统计、公式/lookup、表单、仪表盘、应用模式（BaseApp/AppMode 页面与组件）、Workspace 目录、workflow、角色权限、模板中心（多维表格模板分类/列表/搜索）；遇到 Base/多维表格/bitable、BaseApp/AppMode、/base/ 或 /app/ 链接时使用。BaseApp 不走 lark-apps；文件导入/导出转 lark-drive，认证/授权转 lark-shared。

Productivity & Automation815K installs

lark-drive

open.feishu.cn

飞书云空间（云盘/云存储）：管理 Drive 文件和文件夹，包含上传/下载、创建文件夹、复制/移动/删除、查看元数据、查询权限设置、评论/权限/订阅、标题、版本、飞书文档密级标签（secure labels）和本地文件导入。用户需要整理云盘目录、处理云空间资源 URL/token、判断链接类型/真实 token/标题，或导入 Word/Markdown/Excel/CSV/PPTX/.base 为 docx/sheet/bitable/slides 时使用；doubao.com 云空间 URL/token 也按资源路径和 token 路由，不回退 WebFetch。不负责：文档内容编辑（走 lark-doc）、表格/Base 表内数据操作（走 lark-sheets/lark-base）、知识空间节点/成员管理（走 lark-wiki）、原生 Markdown 文件读写/patch/diff（走 lark-markdown）。

Productivity & Automation815K installs

lark-shared

open.feishu.cn

Use for lark-cli setup/auth tasks: auth login/status/logout, user vs bot identity, business-domain permissions (--domain, including all/docs/drive), missing scopes, revoking authorization, or handling notice JSON.

Productivity & Automation814.8K installs

lark-im

open.feishu.cn

飞书即时通讯：收发消息和管理群聊。发送和回复消息、搜索聊天记录、管理群聊成员、上传下载图片和文件、管理表情回复、发送应用内/短信/电话加急、发送和处理交互卡片（Interactive Card）、监听卡片按钮回调（card.action.trigger）。当用户需要发消息、查看或搜索聊天记录、下载聊天中的文件、查看群成员、搜索群、创建群聊或话题群、管理标记数据、管理 Feed 置顶（添加/移除/查询置顶会话）、管理标签数据、处理卡片回调时使用。

Productivity & Automation814.1K installs

cli-design

Install

Install

Describe the task

Review the result

SKILL.md

Agent-First CLI Design

Core Principles

1. JSON always

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

3. Self-documenting command tree

4. Context-protecting output

5. Errors suggest fixes

Response Envelope

Success

Error

Reference implementations

Implementation

Framework: Effect CLI (@effect/cli)

Binary distribution

Adding a new command

Streaming Protocol (NDJSON) — ADR-0058

When to stream

Protocol: typed NDJSON with HATEOAS terminal

Stream event types

TypeScript types

Emitting stream events

Redis subscription pattern

Composable with Unix tools

Agent consumption pattern

Cleanup

Anti-Patterns

Naming Conventions

Checklist for New Commands

TODO

FAQ

More from joelhooks/joelclaw

Popular productivity & automation skills