2. 管道友好的输出

您的输出将通过 head、tail、grep、jq、awk 和 wc 进行管道传输。每个设计决策都源于此。

每行一条记录。 每一行必须是一个自包含的意义单元。这是最重要的一条规则——它使得每个标准的 Unix 工具都能免费工作。

对于单个对象响应，输出一行紧凑的 JSON：

$ my-cli status --output json
{"name":"my-service","status":"running","uptime_seconds":13320}

打印数组或大型集合时使用 NDJSON。 当命令返回列表、数组或任何可能的大型记录集合时，请使用 NDJSON（换行分隔的 JSON）——每行一个 JSON 对象，不包裹数组。这使得消费者可以流式处理、grep 和切片，而无需缓冲或解析整个输出。

# NDJSON — 每行都可独立解析
$ my-cli list --output json
{"id":"svc-1","name":"api","status":"running"}
{"id":"svc-2","name":"worker","status":"stopped"}
{"id":"svc-3","name":"gateway","status":"running"}

# 标准工具可以直接使用：
$ my-cli list --output json | head -1          # 第一条记录
$ my-cli list --output json | tail -5          # 最后 5 条记录
$ my-cli list --output json | grep '"running"' # 无需 jq 即可过滤
$ my-cli list --output json | wc -l            # 统计记录数

避免将集合包裹在 JSON 数组中（[{...},{...}]）。数组会强制消费者在访问任何单个记录之前加载并解析整个输出。

何时使用 NDJSON 与单个 JSON 对象：

• 单个对象（状态、配置、按 ID 获取）→ 一行 JSON
• 集合（列表、搜索、日志、事件）→ NDJSON，每行一个对象

stdout 仅用于数据——不要有横幅、提示、装饰性方框或日志消息。stderr 用于诊断——进度信息、警告和调试消息应发送到 stderr。将两者混合会破坏管道。

一致的形状——同一个命令应始终返回相同的 JSON 模式，对于缺失的字段使用 null 而不是省略键。代理会根据您的模式硬编码解析器。

3. 两次尝试的错误恢复

错误消息必须包含足够的上下文，以便调用者能在下一次尝试中成功。第三次尝试意味着您的错误消息失败了。

每个错误都应包括：

1. 出了什么问题——具体的失败原因
2. 期望是什么——正确的类型、形状或值
3. 一个示例——一个可行的具体命令

# 错误
Error: invalid argument

# 正确
Error: <uri> must be a URL (e.g. https://api.example.com/agents/echo)
  or a registered short name (e.g. echo-agent).
  Run 'my-cli list' to see available agents.

4. 自描述的命令

CLI 必须无需外部文档即可描述自身：

• my-cli、my-cli --help 和 my-cli help 都应打印完整的命令列表
• 每个命令在其 --help 输出中应至少包含一个具体的使用示例
• 在帮助文本中按类别对命令进行分组，以便代理（和人类）能找到他们需要的内容

$ my-cli --help
Usage: my-cli <command> [options]

Lifecycle:
  init          Initialize configuration
  doctor        Run health checks
  whoami        Show current identity

Resources:
  list          List available resources
  get <id>      Get a resource by ID
  create        Create a new resource

Run 'my-cli <command> --help' for details on a specific command.

5. 有意义的退出代码

使用退出代码，以便代理无需解析输出即可检测成功或失败：

失败时始终以非零值退出。切勿将 "error" 打印到 stdout 并以 0 退出。

6. 尽可能实现幂等性

代理可能会重试命令。设计命令时要确保重新运行是安全的：

• create 应该成功，或者如果资源已存在则返回现有资源（或提供 --if-not-exists 选项）
• delete 即使资源已经消失也应该成功
• config set 如果值已经设置，应该是一个空操作

7. 可预测的参数模式

在所有命令中使用一致的模式：

my-cli <noun> <verb> [arguments] [--flags]
# 或
my-cli <verb> <noun> [arguments] [--flags]

选择一种模式并坚持使用。常见的标志约定：

• --output <format> 或 -o <format> —— 输出格式（json、text、csv）
• --yes 或 --confirm —— 跳过破坏性操作的确认
• --quiet 或 -q —— 抑制非必要的输出
• --verbose 或 -v —— 增加日志详细程度（输出到 stderr）

实现模式

输出格式化辅助函数

集中处理输出格式化，以便每个命令的行为保持一致。创建一个所有命令都调用的共享辅助函数：

• 当 --output json 时，向 stdout 输出每行一个 JSON 对象（NDJSON）
• 当 --output text（默认）时，向 stdout 写入人类可读的键值行
• 当 stdout 是 TTY 时，可以添加颜色、表格或方框以提高人类可读性
• 当 stdout 被管道传输（不是 TTY）时，自动去除所有 ANSI 代码和装饰
• 切勿混合格式——每次调用必须恰好产生一种格式

启动时间

优化冷启动时间。代理在一个会话中会调用 CLI 数百次——500 毫秒的启动惩罚会迅速累积。

• 延迟加载重量级依赖项——仅导入被调用命令所需的内容
• 避免在启动时进行顶层的网络调用、文件系统扫描或配置验证
• 对于长时间运行的后台工作（监视器、服务器、轮询），使用守护进程模式——生成一个后台进程，并立即返回其 PID 或套接字路径

带有恢复提示的错误处理

将错误包装在一致的格式中，以便代理可以解析并采取行动。每个错误路径都应：

1. 将错误消息写入 stderr（而不是 stdout）
2. 包含一个恢复提示，其中包含正确调用的示例
3. 以非零代码退出

# 示例错误输出（在 stderr 上）：
Error: "foobar" is not a valid URI.
Hint: Provide a full URL (e.g. https://example.com/api) or a short name
  (e.g. my-agent). Run 'my-cli list' to see available options.

具有安全默认值的配置

切勿因缺少配置而崩溃。返回合理的默认值，以便命令开箱即用：

• 如果不存在配置文件，则静默使用内置默认值
• 将用户配置合并到默认值之上，以便新字段始终存在
• 在 --help 输出中记录配置文件的位置

应避免的反模式

测试清单

审查或测试面向代理的 CLI 时，请验证：

• 每个命令都无需 TTY 即可运行（echo "" | my-cli command 不会挂起）
• 单对象命令产生一行有效的 JSON
• 集合命令产生 NDJSON（每行一个 JSON 对象，不包裹数组）
• my-cli list --output json | head -1 返回一个有效的、自包含的 JSON 对象
• my-cli list --output json | grep "keyword" 返回有效的 JSON 行
• 错误发送到 stderr，数据发送到 stdout
• 所有失败路径都返回非零退出代码
• --help 包含每个命令至少一个使用示例
• 错误消息包含期望的内容和恢复提示
• 命令是幂等的，或明确记录为非幂等的
• 当 stdout 被管道传输（不是 TTY）时，没有 ANSI 代码、方框或装饰
• 简单命令的启动时间在 100 毫秒以内

每周安装数

1

仓库

agentlyhq/skills

首次出现

1 天前

安全审计

Gen Agent Trust HubPassSocketPassSnykPass

安装于

amp1

cline1

opencode1

cursor1

kimi-cli1

codex1

TTY-only decoration. Colors, boxes (boxen), tables, spinners, and progress bars are fine — but only when stdout is a TTY. When piped, output must be plain. Check isatty(stdout) (or your language's equivalent) and strip all decoration when it returns false. Never use box-drawing libraries like boxen in non-TTY mode — they break grep and head.

2. Pipeline-Friendly Output

Your output will be piped through head, tail, grep, jq, awk, and wc. Every design decision flows from this.

One record per line. Each line must be a self-contained unit of meaning. This is the single most important rule — it makes every standard Unix tool work for free.

For a single object response, emit one compact JSON line:

$ my-cli status --output json
{"name":"my-service","status":"running","uptime_seconds":13320}

Use NDJSON when printing arrays or large collections. When a command returns a list, array, or any potentially large collection of records, use NDJSON (Newline-Delimited JSON) — one JSON object per line, no wrapping array. This lets consumers stream, grep, and slice without buffering or parsing the entire output.

# NDJSON — each line is independently parseable
$ my-cli list --output json
{"id":"svc-1","name":"api","status":"running"}
{"id":"svc-2","name":"worker","status":"stopped"}
{"id":"svc-3","name":"gateway","status":"running"}

# Standard tools just work:
$ my-cli list --output json | head -1          # first record
$ my-cli list --output json | tail -5          # last 5 records
$ my-cli list --output json | grep '"running"' # filter without jq
$ my-cli list --output json | wc -l            # count records

Avoid wrapping collections in a JSON array ([{...},{...}]). An array forces the consumer to load and parse the entire output before accessing any single record.

When to use NDJSON vs a single JSON object:

• Single object (status, config, get-by-id) → one JSON line
• Collection (list, search, logs, events) → NDJSON, one object per line

stdout is for data only — no banners, tips, decorative boxes, or log messages. stderr is for diagnostics — progress info, warnings, and debug messages go to stderr. Mixing the two corrupts pipelines.

Consistent shape — the same command should always return the same JSON schema, using null for missing fields rather than omitting keys. Agents hardcode parsers against your schema.

3. 2-Attempt Error Recovery

Error messages must include enough context for the caller to succeed on the next attempt. A third attempt means your error message failed.

Every error should include:

1. What went wrong — the specific failure
2. What was expected — the correct type, shape, or value
3. An example — a concrete command that would work

# Bad

Error: invalid argument

# Good
Error: <uri> must be a URL (e.g. https://api.example.com/agents/echo)
  or a registered short name (e.g. echo-agent).
  Run 'my-cli list' to see available agents.

4. Self-Describing Commands

The CLI must describe itself without external documentation:

• my-cli, my-cli --help, and my-cli help should all print the full command listing

• Every command should include at least one concrete usage example in its --help output

• Group commands by category in help text so agents (and humans) can find what they need

  $ my-cli --help Usage: my-cli <command> [options]

  Lifecycle: init Initialize configuration doctor Run health checks whoami Show current identity

  Resources: list List available resources get <id> Get a resource by ID create Create a new resource

  Run 'my-cli <command> --help' for details on a specific command.

5. Meaningful Exit Codes

Use exit codes so agents can detect success or failure without parsing output:

Always exit non-zero on failure. Never print "error" to stdout and exit 0.

6. Idempotent Where Possible

Agents may retry commands. Design commands to be safe to re-run:

• create should succeed or return the existing resource if it already exists (or offer --if-not-exists)
• delete should succeed even if the resource is already gone
• config set should be a no-op if the value is already set

7. Predictable Argument Patterns

Use consistent patterns across all commands:

my-cli <noun> <verb> [arguments] [--flags]
# or
my-cli <verb> <noun> [arguments] [--flags]

Pick one pattern and stick with it. Common flag conventions:

• --output <format> or -o <format> — output format (json, text, csv)
• --yes or --confirm — skip confirmation for destructive actions
• --quiet or -q — suppress non-essential output
• --verbose or -v — increase log detail (to stderr)

Implementation Patterns

Output Formatting Helper

Centralize output formatting so every command behaves consistently. Create a shared helper that all commands call:

• When --output json, emit one JSON object per line (NDJSON) to stdout
• When --output text (default), write human-readable key-value lines to stdout
• When stdout is a TTY, you may add colors, tables, or boxes for human readability
• When stdout is piped (not a TTY), strip all ANSI codes and decoration automatically
• Never mix formats — each invocation must produce exactly one format

Startup Time

Optimize cold-start time. Agents invoke CLIs hundreds of times in a session — a 500ms startup penalty compounds fast.

• Lazy-load heavy dependencies — only import what the invoked command needs
• Avoid top-level network calls, filesystem scans, or config validation on startup
• For long-running background work (watchers, servers, polling), use a daemon pattern — spawn a background process and return immediately with its PID or socket path

Error Handling with Recovery Hints

Wrap errors in a consistent format that agents can parse and act on. Every error path should:

1. Write the error message to stderr (not stdout)
2. Include a recovery hint with an example of a correct invocation
3. Exit with a non-zero code

# Example error output (on stderr):

Error: "foobar" is not a valid URI.
Hint: Provide a full URL (e.g. https://example.com/api) or a short name
  (e.g. my-agent). Run 'my-cli list' to see available options.

Config with Safe Defaults

Never crash on missing config. Return sensible defaults so commands work out of the box:

• If no config file exists, use built-in defaults silently
• Merge user config over defaults so new fields are always present
• Document the config file location in --help output

Anti-Patterns to Avoid

Testing Checklist

When reviewing or testing an agent-facing CLI, verify:

• Every command runs without a TTY (echo "" | my-cli command doesn't hang)
• Single-object commands produce one valid JSON line
• Collection commands produce NDJSON (one JSON object per line, no wrapping array)
• my-cli list --output json | head -1 returns a valid, self-contained JSON object
• my-cli list --output json | grep "keyword" returns valid JSON lines
• Errors go to stderr, data goes to stdout
• Non-zero exit code on all failure paths
• --help includes at least one usage example per command
• Error messages include what was expected and a recovery hint
• Commands are idempotent or clearly documented as non-idempotent
• No ANSI codes, boxes, or decoration when stdout is piped (not a TTY)
• Startup time is under 100ms for simple commands

Weekly Installs

1

Repository

agentlyhq/skills

First Seen

1 day ago

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

amp1

cline1

opencode1

cursor1

kimi-cli1

codex1