cli-for-agents

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent-Friendly CLI Design Best Practices

Agent友好型CLI设计最佳实践

Prescriptive design and review standards for Command-Line Interface Design targeting AI agents and scripts, not just humans typing at a prompt. Human-oriented CLIs often block agents: interactive prompts, huge upfront docs, help text without copy-pasteable examples, error messages without fixes, no dry-run mode. This skill prioritizes rules by blast radius — from "the agent cannot use this CLI at all" (CRITICAL) to "the agent has to read help one extra time" (MEDIUM).

Use this skill both when building a new CLI and when reviewing an existing one for agent-friendliness.

This skill contains 45 rules across 8 categories.

本指南针对AI Agent和脚本（而非仅针对手动输入的人类用户），提供命令行界面（CLI）设计与审查的规范性标准。面向人类的CLI通常会阻碍Agent的使用：比如交互式提示、冗长的前置文档、无可复制示例的帮助文本、无修复方案的错误消息、无试运行模式等。本技能按影响范围优先级排序规则——从“Agent完全无法使用此CLI”（严重CRITICAL）到“Agent需额外阅读一次帮助文档”（中等MEDIUM）。

此技能适用于构建新CLI以及审查现有CLI的Agent友好性两种场景。

本技能包含8大类别共45条规则。

When to Apply

适用场景

Reference these guidelines when:

Writing
```
--help
```
text for any subcommand
Designing new flags, arguments, or subcommands
Crafting error messages or exit codes
Adding destructive operations that need dry-run or confirmation
Choosing between interactive prompts and flag-only inputs
Shaping success output so agents can chain commands
Reviewing an existing CLI for headless-usability regressions

在以下场景中参考本指南：

为任何子命令编写
```
--help
```
文本
设计新的标志、参数或子命令
编写错误消息或退出码
添加需试运行或确认的破坏性操作
在交互式提示与仅标志输入之间做选择
设计成功输出以支持Agent链式调用命令
审查现有CLI的无头可用性退化问题

Rule Categories by Priority

按优先级划分的规则类别


interact-
help-
err-
safe-
input-
output-
idem-
struct-

Priority	Category	Impact	Prefix
1	Non-interactive Operation	CRITICAL	`interact-`
2	Help Text Design	HIGH	`help-`
3	Error Messages	HIGH	`err-`
4	Destructive Action Safety	HIGH	`safe-`
5	Input Handling	HIGH	`input-`
6	Output Format	MEDIUM-HIGH	`output-`
7	Idempotency & Retries	MEDIUM-HIGH	`idem-`
8	Command Structure	MEDIUM	`struct-`

Note:

help-examples-in-help

is rated CRITICAL within the HIGH

help-

category because its specific failure — help text without examples — makes every other help rule moot. The category label reflects the average, not the worst case.


interact-
help-
err-
safe-
input-
output-
idem-
struct-

优先级	类别	影响程度	前缀
1	非交互式操作	严重（CRITICAL）	`interact-`
2	帮助文本设计	高（HIGH）	`help-`
3	错误消息	高（HIGH）	`err-`
4	破坏性操作安全保障	高（HIGH）	`safe-`
5	输入处理	高（HIGH）	`input-`
6	输出格式	中高（MEDIUM-HIGH）	`output-`
7	幂等性与重试	中高（MEDIUM-HIGH）	`idem-`
8	命令结构	中等（MEDIUM）	`struct-`

注意：在高优先级的

help-

类别中，

help-examples-in-help

规则被评为严重（CRITICAL），因为该规则失效（帮助文本无示例）会导致其他所有帮助规则形同虚设。类别标签反映的是平均优先级，而非最坏情况。

Quick Reference

快速参考

1. Non-interactive Operation (CRITICAL)

1. 非交互式操作（严重CRITICAL）

```
interact-flags-first
```
— Express every input as a flag first; prompts are TTY-only fallback
```
interact-detect-tty
```
— Check
```
isatty()
```
before prompting
```
interact-no-arrow-menus
```
— Replace arrow-key menus with flag-selected choices
```
interact-no-input-flag
```
— Support
```
--no-input
```
to force non-interactive mode
```
interact-no-timed-prompts
```
— Never use timed prompts or press-any-key screens
```
interact-no-hang-on-stdin
```
— Don't block on stdin when a TTY is attached

```
interact-flags-first
```
— 优先以标志形式表达所有输入；仅当为TTY环境时才回退到提示
```
interact-detect-tty
```
— 提示前先检查
```
isatty()
```
```
interact-no-arrow-menus
```
— 用标志选择替代箭头键菜单
```
interact-no-input-flag
```
— 支持
```
--no-input
```
以强制启用非交互式模式
```
interact-no-timed-prompts
```
— 绝不要使用定时提示或任意键继续的界面
```
interact-no-hang-on-stdin
```
— 当连接TTY时，不要阻塞等待标准输入（stdin）

2. Help Text Design (HIGH)

2. 帮助文本设计（高HIGH）

```
help-examples-in-help
```
— Include copy-pasteable examples in every
```
--help
```
```
help-per-subcommand
```
— Every subcommand owns its own
```
--help
```
```
help-no-flag-required
```
— Show help when invoked with zero arguments
```
help-layered-discovery
```
— Top-level help is a navigational index
```
help-flag-summary
```
— List both short and long forms for every flag
```
help-suggest-next-steps
```
— Suggest what to run next in help and success output

```
help-examples-in-help
```
— 在每个
```
--help
```
中包含可复制粘贴的示例
```
help-per-subcommand
```
— 每个子命令都有独立的
```
--help
```
```
help-no-flag-required
```
— 当无参数调用时显示帮助信息
```
help-layered-discovery
```
— 顶层帮助为导航索引
```
help-flag-summary
```
— 列出每个标志的短格式与长格式
```
help-suggest-next-steps
```
— 在帮助与成功输出中建议下一步操作

3. Error Messages (HIGH)

3. 错误消息（高HIGH）

```
err-exit-fast-on-missing-required
```
— Exit fast on missing required flags
```
err-actionable-fix
```
— Include a concrete fix in every error message
```
err-stderr-not-stdout
```
— Send errors to stderr, not stdout
```
err-non-zero-exit-codes
```
— Use distinct non-zero exit codes for distinct failures
```
err-include-example-invocation
```
— Include a correct example invocation in errors
```
err-no-stack-traces-by-default
```
— Reserve stack traces for
```
--debug
```
mode

```
err-exit-fast-on-missing-required
```
— 缺少必填标志时立即退出
```
err-actionable-fix
```
— 在每条错误消息中包含具体的修复方案
```
err-stderr-not-stdout
```
— 将错误发送到标准错误（stderr）而非标准输出（stdout）
```
err-non-zero-exit-codes
```
— 为不同的失败场景使用不同的非零退出码
```
err-include-example-invocation
```
— 在错误消息中包含正确的调用示例
```
err-no-stack-traces-by-default
```
— 仅在
```
--debug
```
模式下显示堆栈跟踪

4. Destructive Action Safety (HIGH)

4. 破坏性操作安全保障（高HIGH）

```
safe-dry-run-flag
```
— Provide
```
--dry-run
```
for every destructive command
```
safe-force-bypass-flag
```
— Provide
```
--yes
```
/
```
--force
```
to skip confirmations
```
safe-confirm-by-typing-name
```
— Require typing the resource name for irreversible actions
```
safe-no-prompts-with-no-input
```
— Never prompt when
```
--no-input
```
is set
```
safe-idempotent-cleanup
```
— Exit successfully when delete targets are already gone
```
safe-crash-only-recovery
```
— Design multi-step commands for crash-only recovery

```
safe-dry-run-flag
```
— 为每个破坏性命令提供
```
--dry-run
```
选项
```
safe-force-bypass-flag
```
— 提供
```
--yes
```
/
```
--force
```
选项以跳过确认
```
safe-confirm-by-typing-name
```
— 不可逆操作要求输入资源名称进行确认
```
safe-no-prompts-with-no-input
```
— 当设置
```
--no-input
```
时绝不显示提示
```
safe-idempotent-cleanup
```
— 当删除目标已不存在时，仍成功退出
```
safe-crash-only-recovery
```
— 设计多步骤命令以支持崩溃后仅恢复

5. Input Handling (HIGH)

5. 输入处理（高HIGH）

```
input-accept-stdin-dash
```
— Accept
```
-
```
as filename for stdin and stdout
```
input-flags-over-positional
```
— Prefer named flags over positional arguments
```
input-stdin-for-secrets
```
— Accept secrets through stdin or file, never as flag values
```
input-env-var-fallback
```
— Accept common flags through environment variables
```
input-no-prompt-fallback
```
— Never fall back to a prompt when a flag is missing

```
input-accept-stdin-dash
```
— 接受
```
-
```
作为标准输入（stdin）和标准输出（stdout）的文件名
```
input-flags-over-positional
```
— 优先使用命名标志而非位置参数
```
input-stdin-for-secrets
```
— 通过标准输入（stdin）或文件接收密钥，绝不作为标志值
```
input-env-var-fallback
```
— 通过环境变量接受常用标志
```
input-no-prompt-fallback
```
— 当缺少标志时，绝不要回退到提示

6. Output Format (MEDIUM-HIGH)

6. 输出格式（中高MEDIUM-HIGH）

```
output-json-flag
```
— Provide
```
--json
```
for stable machine-readable output
```
output-ndjson-streaming
```
— Stream large result sets as NDJSON
```
output-bounded-by-default
```
— Bound default output size with
```
--limit
```
and
```
--all
```
```
output-machine-ids-on-success
```
— Return chainable values on success, not just "Done"
```
output-respect-no-color
```
— Disable ANSI color when
```
NO_COLOR
```
or non-TTY
```
output-no-decorative-only
```
— Avoid relying on decorative output to convey state
```
output-one-record-per-line
```
— One record per line for grep-able human output

```
output-json-flag
```
— 提供
```
--json
```
选项以生成稳定的机器可读输出
```
output-ndjson-streaming
```
— 以NDJSON格式流式传输大型结果集
```
output-bounded-by-default
```
— 默认限制输出大小，提供
```
--limit
```
和
```
--all
```
选项调整
```
output-machine-ids-on-success
```
— 成功时返回可链式调用的值，而非仅返回“完成”
```
output-respect-no-color
```
— 当设置
```
NO_COLOR
```
或非TTY环境时，禁用ANSI颜色
```
output-no-decorative-only
```
— 避免仅依赖装饰性输出传递状态
```
output-one-record-per-line
```
— 每行一条记录，生成便于grep处理的人类可读输出

7. Idempotency & Retries (MEDIUM-HIGH)

7. 幂等性与重试（中高MEDIUM-HIGH）

```
idem-retry-safe
```
— Make running the same command twice safe
```
idem-create-or-skip
```
— Make create commands skip when target already exists
```
idem-stable-output-on-skip
```
— Return the same output shape whether acting or skipping
```
idem-state-reconciliation
```
— Prefer "ensure state" semantics over delta application
```
idem-stable-identifiers
```
— Accept user-provided names instead of auto-generating IDs

```
idem-retry-safe
```
— 确保重复执行同一命令是安全的
```
idem-create-or-skip
```
— 创建命令在目标已存在时跳过执行
```
idem-stable-output-on-skip
```
— 无论执行还是跳过，返回相同格式的输出
```
idem-state-reconciliation
```
— 优先使用“确保状态”语义而非增量应用
```
idem-stable-identifiers
```
— 接受用户提供的名称，而非自动生成ID

8. Command Structure (MEDIUM)

8. 命令结构（中等MEDIUM）

```
struct-resource-verb
```
— Use a consistent resource-verb command shape
```
struct-flag-order-independent
```
— Parse flags in any position relative to subcommands
```
struct-no-hidden-subcommand-catchall
```
— Avoid catch-all handlers for unknown subcommands

struct-standard-flag-names

— Use standard flag names (

--help

--version

--verbose

--quiet

)

```
struct-resource-verb
```
— 使用一致的“资源-动词”命令格式
```
struct-flag-order-independent
```
— 支持标志在子命令任意位置解析
```
struct-no-hidden-subcommand-catchall
```
— 避免为未知子命令设置万能处理程序

struct-standard-flag-names

— 使用标准标志名称（

--help

--version

--verbose

--quiet

）

How to Use

使用方法

When building a new CLI

构建新CLI时

Start at CRITICAL and walk down. The first two categories (

interact-

and

help-

) are non-negotiable — if any rule in these is violated, the CLI is unusable by agents regardless of how good the rest is. After those, work through

err-

safe-

, and

input-

— these are where most real-world friction lives.

output-

idem-

, and

struct-

are polish that compounds across many invocations.

从严重优先级开始依次向下执行。前两个类别（

interact-

和

help-

）是不可协商的——如果其中任何一条规则被违反，无论其他规则多么完善，Agent都完全无法使用此CLI。完成这两个类别后，再处理

err-

、

safe-

和

input-

类别——这些是现实中大部分问题的来源。

output-

、

idem-

和

struct-

类别是优化项，能在多次调用中提升效率。

When reviewing an existing CLI

审查现有CLI时

Run through this checklist in priority order:

Non-interactive path — invoke every subcommand with
```
--no-input
```
or under
```
</dev/null
```
and see which hang
Layered help — does
```
mycli --help
```
list subcommands only, or dump everything?
Examples on
--help
— every subcommand's help should end with a runnable Examples section
Error messages with invocations — does every error tell the caller exactly which flag to add?
stdin/pipeline story — can you pipe output into input? Does
```
-
```
mean stdin?
Exit codes — are usage errors (2), runtime failures (1), and transient failures (69) distinct?
Dry-run — every destructive command has
```
--dry-run
```
(or equivalent)
Confirmation bypass — every destructive command has
```
--yes
```
/
```
--force
```
Consistent command structure — do
```
service list
```
,
```
deploy list
```
,
```
config list
```
all exist and work the same way?
Structured success output — does
```
deploy
```
return a
```
deploy_id
```
the agent can use next?

按优先级顺序执行以下检查：

非交互式路径 — 使用
```
--no-input
```
或在
```
</dev/null
```
环境下调用每个子命令，查看哪些会阻塞
分层帮助 —
```
mycli --help
```
是否仅列出子命令，还是输出所有内容？
--help中的示例 — 每个子命令的帮助是否以可运行的示例部分结尾？
带调用示例的错误消息 — 每条错误是否明确告知调用者需添加的标志？
标准输入/管道支持 — 能否将输出管道输入到下一个命令？
```
-
```
是否代表标准输入？
退出码 — 用法错误（2）、运行时失败（1）和临时失败（69）是否使用不同的退出码？
试运行模式 — 每个破坏性命令是否都有
```
--dry-run
```
（或等效选项）？
确认跳过 — 每个破坏性命令是否都有
```
--yes
```
/
```
--force
```
选项？
一致的命令结构 —
```
service list
```
、
```
deploy list
```
、
```
config list
```
是否都存在且用法一致？
结构化成功输出 —
```
deploy
```
命令是否返回Agent可用于下一步的
```
deploy_id
```
？

Individual rules

单个规则详情

Read individual reference files for detailed explanations and code examples:

Section definitions — Category structure and impact levels
Rule template — Template for adding new rules

阅读单个参考文件获取详细说明和代码示例：

章节定义 — 类别结构与影响级别
规则模板 — 添加新规则的模板

Reference Files

参考文件

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules
metadata.json	Version and reference information

文件	描述
references/_sections.md	类别定义与排序
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息