create-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create CLI

创建CLI

Design CLI surface area (syntax + behavior), agent-aware, human-friendly.

设计CLI界面（语法+行为），兼顾Agent适配性与人类友好性。

Phase 1 — Prepare

阶段1 — 准备

Read

${CLAUDE_PLUGIN_ROOT}/skills/create-cli/references/cli-guidelines.md

. Apply it as the default CLI rubric, including the Agent Ergonomics section.

For new CLI designs, also read

${CLAUDE_PLUGIN_ROOT}/skills/create-cli/references/language-selection.md

to inform the language recommendation in Phase 2. Skip it for audits — the language is already chosen.

Proceed when cli-guidelines.md is loaded.

阅读

${CLAUDE_PLUGIN_ROOT}/skills/create-cli/references/cli-guidelines.md

。将其作为默认的CLI评估标准，包括「Agent人机工程学」章节。

对于新的CLI设计，还需阅读

${CLAUDE_PLUGIN_ROOT}/skills/create-cli/references/language-selection.md

，为阶段2的语言推荐提供依据。审核现有CLI时可跳过此步骤——语言已确定。

加载cli-guidelines.md后即可进入下一阶段。

Phase 2 — Clarify

阶段2 — 明确需求

Determine whether this is a new design or an audit from the user's trigger.

根据用户的触发请求，确定这是新设计还是审核任务。

New design

新设计

Ask, then proceed with best-guess defaults if user is unsure:

Command name + one-sentence purpose.
Primary consumer: agent/LLM, human at a terminal, scripted automation, or mixed.
Input sources: args vs stdin; files vs URLs; secrets (never via flags).
Output contract: human text by default,
```
--json
```
for structured output, exit codes.
Interactivity: prompts allowed? need
```
--no-input
```
? confirmations for destructive ops?
Config model: flags/env/config-file; precedence; XDG vs repo-local.
Language & distribution: ask for the user's preferred implementation language, or offer to recommend one. Ask whether a single binary (no runtime needed on target machine) is required, or whether a runtime dependency is acceptable. Apply language-selection.md to recommend if the user is unsure. Platform: macOS/Linux/Windows.

If an existing CLI spec or tool description is provided, read it first — skip questions already answered by it.

询问以下问题，若用户不确定则采用最佳默认值：

命令名称+一句话用途说明。
主要使用者：Agent/大语言模型、终端用户、脚本自动化，还是混合场景。
输入来源：参数 vs 标准输入；文件 vs URL；敏感信息（绝不能通过标志传递）。
输出约定：默认输出人类可读文本，
```
--json
```
用于结构化输出，明确退出码规则。
交互性：是否允许提示？是否需要
```
--no-input
```
？破坏性操作是否需要确认？
配置模型：标志/环境变量/配置文件；优先级；XDG标准 vs 仓库本地配置。
语言与分发：询问用户偏好的实现语言，或主动提供推荐。询问是否需要单二进制文件（目标机器无需运行时），还是可接受运行时依赖。若用户不确定，参考language-selection.md给出推荐。平台：macOS/Linux/Windows。

若用户提供了现有CLI规范或工具描述，先阅读该内容——跳过已回答的问题。

Audit

审核

Ask:

CLI name and source location (repo path, or provide
```
--help
```
output).
Primary consumer: agent, human, or mixed.
Known pain points or specific areas to focus on.

Then explore the codebase: use Glob/Grep to find command definitions, flag registrations, output formatting, and error handling. Run

<cli> --help

via Bash to capture actual behavior.

Proceed when answers are confirmed or user is unsure — use best-guess defaults.

询问：

CLI名称和源码位置（仓库路径，或提供
```
--help
```
输出）。
主要使用者：Agent、人类，还是混合场景。
已知痛点或需重点关注的特定领域。

然后探索代码库：使用Glob/Grep查找命令定义、标志注册、输出格式化和错误处理逻辑。通过Bash运行

<cli> --help

以捕获实际行为。

确认答案后进入下一阶段，若用户不确定则采用最佳默认值。

Phase 3 — Conventions

阶段3 — 遵循约定

Apply the conventions from cli-guidelines.md (loaded in Phase 1), including the Agent Ergonomics section. The rules below are the key conventions to enforce — cli-guidelines.md provides the full rubric for edge cases.

If primary consumer is human-only, the Errors and Reduce Tool Calls subsections are optional — apply them only if the user wants script-friendliness.

应用阶段1加载的cli-guidelines.md中的约定，包括「Agent人机工程学」章节。以下是需强制执行的核心约定——cli-guidelines.md提供了针对边缘情况的完整评估标准。

若主要使用者仅为人类，「错误处理」和「减少工具调用」小节为可选内容——仅当用户需要脚本友好性时才应用。

Output

输出

Default output is human-readable text.
```
--json
```
gives structured JSON. Explicit is better than implicit — no TTY sniffing, no surprises.
List commands in
```
--json
```
mode use NDJSON (one JSON object per line) — enables streaming and
```
jq
```
piping without buffering. For paginated results with metadata, a JSON object with an
```
items
```
array is acceptable. If the CLI extends an existing ecosystem that uses JSON arrays (kubectl, aws, gh), match the ecosystem convention.
Primary data to stdout; diagnostics/errors to stderr.
Suppress ANSI codes, progress spinners, and decorative output when
```
--json
```
is passed or when stdout is not a TTY.

默认输出为人类可读文本。
```
--json
```
输出结构化JSON。明确优于隐含——不进行TTY检测，避免意外行为。
列表类命令在
```
--json
```
模式下使用NDJSON（每行一个JSON对象）——支持流式处理和
```
jq
```
管道，无需缓冲。若结果需分页并附带元数据，可使用包含
```
items
```
数组的JSON对象。若CLI属于现有生态系统（如kubectl、aws、gh）且该生态系统使用JSON数组，则遵循生态系统约定。
主数据输出到stdout；诊断/错误信息输出到stderr。
当传递
```
--json
```
或stdout不是TTY时，禁用ANSI代码、进度 spinner 和装饰性输出。

Errors (agent/mixed consumers only)

错误处理（仅适用于Agent/混合使用者）

When
```
--json
```
is active, emit error objects on stderr:
```
{"error": "<snake_case_code>", "message": "...", "hint": "<exact CLI invocation or null>"}
```
— so agent callers can route recovery logic without parsing free-text stderr. The
```
hint
```
field must be an executable command, not prose.
Exit codes:
```
0
```
success,
```
1
```
runtime error,
```
2
```
invalid usage; add command-specific codes only when genuinely useful.

当
```
--json
```
启用时，在stderr输出错误对象：
```
{"error": "<snake_case_code>", "message": "...", "hint": "<精确的CLI调用命令或null>"}
```
——以便Agent调用者无需解析自由文本stderr即可执行恢复逻辑。
```
hint
```
字段必须是可执行命令，而非描述性文本。
退出码：
```
0
```
表示成功，
```
1
```
表示运行时错误，
```
2
```
表示无效用法；仅当真正有用时才添加命令特定的退出码。

Flags

标志

```
-h/--help
```
always shows help; ignores other args.
```
--version
```
prints version to stdout.
```
--json
```
preferred for structured output.
```
--output json
```
/
```
-o json
```
acceptable when the CLI needs multiple output formats (yaml, table, csv) under a single flag. Pick one and apply consistently.
Consistent flag names across all subcommands for the same concept (
```
--id
```
,
```
--force
```
,
```
--json
```
) — agents learn the naming pattern once and apply it everywhere without guessing.
Prompts only when stdin is a TTY;
```
--no-input
```
disables prompts.
```
--non-interactive
```
acceptable if the ecosystem already uses it.
Destructive operations: interactive confirmation; non-interactive requires
```
--force
```
.
Respect
```
NO_COLOR
```
,
```
TERM=dumb
```
; provide
```
--no-color
```
.
Handle Ctrl-C: exit fast; bounded cleanup; crash-only when possible.

```
-h/--help
```
始终显示帮助信息；忽略其他参数。
```
--version
```
将版本信息输出到stdout。
优先使用
```
--json
```
进行结构化输出。当CLI需要多种输出格式（yaml、table、csv）时，
```
--output json
```
/
```
-o json
```
是可接受的选择。选择其一并保持一致性。
所有子命令中同一概念的标志名称需保持一致（如
```
--id
```
、
```
--force
```
、
```
--json
```
）——Agent只需学习一次命名模式，即可在所有场景中应用，无需猜测。
仅当stdin是TTY时才显示提示；
```
--no-input
```
禁用提示。若生态系统已使用
```
--non-interactive
```
，则可使用该标志。
破坏性操作：需交互式确认；非交互式场景需使用
```
--force
```
。
遵守
```
NO_COLOR
```
、
```
TERM=dumb
```
环境变量；提供
```
--no-color
```
标志。
处理Ctrl-C：快速退出；有限清理；尽可能采用崩溃即停止的设计。

Reduce Tool Calls (agent/mixed consumers only)

减少工具调用（仅适用于Agent/混合使用者）

Compound output: operations return enough data to avoid a follow-up call.
```
create
```
returns the new resource's ID and key fields.
```
delete
```
echoes what was removed.
Rich JSON defaults: in
```
--json
```
mode, return full objects not just IDs.
Bounded lists: list commands default to a safe limit (e.g., 50 items) with
```
--limit
```
to adjust. In JSON mode, include
```
has_more
```
(bool) and optionally
```
next_cursor
```
for keyset pagination. Unbounded output wastes tokens and risks context overflow for agent callers.
Idempotent by default: where possible, commands are safe to repeat; document preconditions explicitly — agents rely on safe retries for error recovery without human intervention.

Apply all applicable conventions, then proceed to Phase 4.

复合输出：操作返回足够的数据，避免后续调用。
```
create
```
命令返回新资源的ID和关键字段。
```
delete
```
命令回显已删除的内容。
丰富的JSON默认值：在
```
--json
```
模式下，返回完整对象而非仅ID。
有限列表：列表类命令默认采用安全限制（如50条），可通过
```
--limit
```
调整。在JSON模式下，包含
```
has_more
```
（布尔值）和可选的
```
next_cursor
```
用于键集分页。无限制输出会浪费令牌，并可能导致Agent调用者的上下文溢出。
默认幂等：尽可能使命令可安全重复执行；明确记录前置条件——Agent依赖安全重试进行错误恢复，无需人工干预。

应用所有适用的约定后，进入阶段4。

Phase 4 — Deliver

阶段4 — 交付成果

Audits

审核任务

Evaluate the existing CLI against every Phase 3 subsection. For each convention, state: what the CLI does today, whether it conforms, and what to change. Also check:

Flag naming consistency across subcommands.
Help text quality (examples present, common flags first, fits one screen).
Config precedence (flags > env > project config > user config > defaults).
Destructive-op safety (confirmations, --force, --dry-run).
Shell completion availability.

Produce a gap report organized by severity: Breaking (requires API change), Major (agent-breaking or convention violation), Minor (cosmetic/polish). Each finding: current behavior, convention violated, recommended fix with migration risk (none/low/breaking).

根据阶段3的每个小节评估现有CLI。对于每个约定，说明：当前CLI的行为、是否符合约定、以及需要修改的内容。同时检查：

子命令间的标志命名一致性。
帮助文本质量（是否包含示例、常用标志优先、是否适配单屏显示）。
配置优先级（标志 > 环境变量 > 项目配置 > 用户配置 > 默认值）。
破坏性操作的安全性（确认机制、--force、--dry-run）。
Shell补全的可用性。

生成按严重性分类的差距报告：重大（需要API变更）、主要（影响Agent使用或违反约定）、次要（优化/ cosmetic）。每个发现需包含：当前行为、违反的约定、推荐修复方案及迁移风险（无/低/重大）。

New designs

新设计任务

Produce a compact spec the user can implement. Include all relevant sections:

Command tree + USAGE synopsis.
Args/flags table (types, defaults, required/optional, examples).
Subcommand semantics (what each does; idempotence; state changes).
Output rules: stdout vs stderr;
```
--json
```
for structured output;
```
--quiet
```
/
```
--verbose
```
.
Error + exit code map (top failure modes).
Safety rules:
```
--dry-run
```
, confirmations,
```
--force
```
,
```
--no-input
```
.
Config/env rules + precedence (flags > env > project config > user config > system).
Shell completion story (if relevant): install/discoverability; generation command or bundled scripts.
5–10 example invocations (common flows; include piped/stdin examples).

Use this skeleton, dropping irrelevant sections:

Language & distribution:
```
Go
```
·
```
cobra
```
· single binary ·
```
goreleaser
```
for CI (Omit if language was not determined.)
Name:
```
mycmd
```
One-liner:
```
...
```

USAGE:

mycmd [global flags] <subcommand> [args]

Subcommands:
- ```
mycmd init ...
```
- ```
mycmd run ...
```
Global flags:
- ```
-h, --help
```
- ```
--version
```
- ```
-q, --quiet
```
  /
```
-v, --verbose
```
  (define exactly)
- ```
--json
```
  (structured JSON output; NDJSON for list commands)
I/O contract:
- stdout:
- stderr:
Exit codes:
- ```
0
```
  success
- ```
1
```
  generic failure
- ```
2
```
  invalid usage (parse/validation)
- (add command-specific codes only when actually useful)
Env/config:
- env vars:
- config file path + precedence:
Examples:
- …

See

${CLAUDE_PLUGIN_ROOT}/skills/create-cli/examples/example-cli-spec.md

for a complete worked example.

If the spec is destined for a skill body or CLAUDE.md, omit unused sections entirely (do not mark them "N/A") and limit examples to ≤5 invocations that each demonstrate multiple patterns.

生成用户可实现的简洁规范。包含所有相关章节：

命令树 + 使用概要。
参数/标志表（类型、默认值、必填/可选、示例）。
子命令语义（每个子命令的功能、幂等性、状态变化）。
输出规则：stdout vs stderr；
```
--json
```
用于结构化输出；
```
--quiet
```
/
```
--verbose
```
。
错误+退出码映射（主要失败场景）。
安全规则：
```
--dry-run
```
、确认机制、
```
--force
```
、
```
--no-input
```
。
配置/环境变量规则+优先级（标志 > 环境变量 > 项目配置 > 用户配置 > 系统默认）。
Shell补全方案（若相关）：安装/发现方式；生成命令或捆绑脚本。
5–10个示例调用（常见流程；包含管道/stdin示例）。

使用以下框架，删除无关章节：

语言与分发：
```
Go
```
·
```
cobra
```
· 单二进制文件 ·
```
goreleaser
```
用于CI （若未确定语言则省略此部分。）
名称：
```
mycmd
```
一句话描述：
```
...
```

使用方法：

mycmd [全局标志] <子命令> [参数]

子命令：
- ```
mycmd init ...
```
- ```
mycmd run ...
```
全局标志：
- ```
-h, --help
```
- ```
--version
```
- ```
-q, --quiet
```
  /
```
-v, --verbose
```
  （明确定义）
- ```
--json
```
  （结构化JSON输出；列表命令使用NDJSON）
I/O约定：
- stdout：
- stderr：
退出码：
- ```
0
```
  成功
- ```
1
```
  通用失败
- ```
2
```
  无效用法（解析/验证错误） -（仅当真正有用时才添加命令特定的退出码）
环境变量/配置：
- 环境变量：
- 配置文件路径+优先级：
示例：
- …

完整示例可参考

${CLAUDE_PLUGIN_ROOT}/skills/create-cli/examples/example-cli-spec.md

。

若规范将用于Skill主体或CLAUDE.md，完全省略未使用的章节（不要标记为"N/A"），并将示例限制为≤5个，每个示例需展示多种模式。

Phase 5 — Verify

阶段5 — 验证

For new specs: confirm the spec covers all applicable sections from the Phase 4 skeleton. Verify the examples section demonstrates at least:

--json

output, error recovery (if agent/mixed consumer), and one piped/stdin usage.

For audits: confirm the gap report addresses every Phase 3 subsection and includes at least one example invocation showing the recommended fix for each Major finding.

Skill is complete when verification passes.

对于新规范：确认规范涵盖阶段4框架中的所有适用章节。验证示例部分至少展示：

--json

输出、错误恢复（若为Agent/混合使用者场景）、以及一个管道/stdin用法示例。

对于审核任务：确认差距报告涵盖阶段3的每个小节，并为每个主要发现至少包含一个展示推荐修复方案的示例调用。

验证通过后，Skill任务完成。

Notes

注意事项

Once language is selected (Phase 2), include the idiomatic parsing library in the spec (see language-selection.md). If language remains undetermined, omit the library.
If the request is "design parameters", do not drift into implementation.

一旦确定语言（阶段2），在规范中包含惯用的解析库（参考language-selection.md）。若语言未确定，则省略库信息。
若请求为「设计参数」，请勿偏离到实现细节。