creating-cli-tools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Create CLI

设计CLI

Design CLI surface area (syntax + behavior), human-first, script-friendly.

设计CLI交互层面（语法+行为），以人为本，同时兼顾脚本友好性。

Do This First

首先完成以下步骤

Read

agent-scripts/skills/create-cli/references/cli-guidelines.md

and apply it as the default rubric.

Upstream/full guidelines: https://clig.dev/ (propose changes: https://github.com/cli-guidelines/cli-guidelines)
Ask only the minimum clarifying questions needed to lock the interface.

阅读

agent-scripts/skills/create-cli/references/cli-guidelines.md

并将其作为默认准则。

完整上游准则：https://clig.dev/（提交修改建议：https://github.com/cli-guidelines/cli-guidelines）
仅提出锁定界面所需的最少澄清问题。

Clarify (fast)

快速澄清

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

Command name + one-sentence purpose.
Primary user: humans, scripts, or both.
Input sources: args vs stdin; files vs URLs; secrets (never via flags).
Output contract: human text,
```
--json
```
,
```
--plain
```
, exit codes.
Interactivity: prompts allowed? need
```
--no-input
```
? confirmations for destructive ops?
Config model: flags/env/config-file; precedence; XDG vs repo-local.
Platform/runtime constraints: macOS/Linux/Windows; single binary vs runtime.

提出以下问题，若用户不确定则采用最佳默认值推进：

命令名称+一句话用途说明。
主要用户群体：人类用户、脚本，还是两者兼顾。
输入来源：参数 vs 标准输入；文件 vs URL；敏感信息（绝不能通过标志传递）。
输出约定：人类可读文本、
```
--json
```
、
```
--plain
```
、退出码。
交互性：是否允许提示？是否需要
```
--no-input
```
？破坏性操作是否需要确认？
配置模型：标志/环境变量/配置文件；优先级；XDG标准 vs 仓库本地配置。
平台/运行时约束：macOS/Linux/Windows；单二进制文件 vs 依赖运行时。

Deliverables (what to output)

交付成果（输出内容）

When designing a CLI, produce a compact spec the user can implement:

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; TTY detection;
```
--json
```
/
```
--plain
```
;
```
--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).

设计CLI时，需生成一份用户可直接实现的简洁规范：

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

Default Conventions (unless user says otherwise)

默认约定（除非用户另有说明）

```
-h/--help
```
always shows help and ignores other args.
```
--version
```
prints version to stdout.
Primary data to stdout; diagnostics/errors to stderr.
Add
```
--json
```
for machine output; consider
```
--plain
```
for stable line-based text.
Prompts only when stdin is a TTY;
```
--no-input
```
disables prompts.
Destructive operations: interactive confirmation + non-interactive requires
```
--force
```
or explicit
```
--confirm=...
```
.
Respect
```
NO_COLOR
```
,
```
TERM=dumb
```
; provide
```
--no-color
```
.
Handle Ctrl-C: exit fast; bounded cleanup; be crash-only when possible.

```
-h/--help
```
始终显示帮助信息并忽略其他参数。
```
--version
```
将版本信息输出到标准输出。
主要数据输出到标准输出；诊断信息/错误输出到标准错误。
添加
```
--json
```
用于机器可读输出；可考虑
```
--plain
```
用于稳定的行文本输出。
仅当标准输入为TTY时显示提示；
```
--no-input
```
禁用提示。
破坏性操作：交互式确认 + 非交互式场景需使用
```
--force
```
或显式
```
--confirm=...
```
。
遵循
```
NO_COLOR
```
、
```
TERM=dumb
```
环境变量；提供
```
--no-color
```
选项。
处理Ctrl-C：快速退出；有限清理；尽可能支持崩溃即终止模式。

Templates (copy into your answer)

模板（复制到你的回复中）

CLI spec skeleton

CLI规范框架

Fill these sections, drop anything irrelevant:

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
```
/
```
--plain
```
(if applicable)

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:
- …

填写以下部分，删除无关内容：

名称：
```
mycmd
```
一句话描述：
```
...
```

使用方法：

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

子命令：
- ```
mycmd init ...
```
- ```
mycmd run ...
```

全局标志：

```
-h, --help
```
```
--version
```
```
-q, --quiet
```
/
```
-v, --verbose
```
（明确定义）
```
--json
```
/
```
--plain
```
（如适用）

I/O约定：
- 标准输出：
- 标准错误：
退出码：
- ```
0
```
  成功
- ```
1
```
  通用失败
- ```
2
```
  无效使用（解析/验证错误） -（仅在真正有用时添加命令特定的退出码）
环境变量/配置：
- 环境变量：
- 配置文件路径+优先级：
示例：
- …

Notes

注意事项

Prefer recommending a parsing library (language-specific) only when asked; otherwise keep this skill language-agnostic.
If the request is “design parameters”, do not drift into implementation.

仅在被询问时才推荐特定语言的解析库；否则保持本技能与语言无关。
如果请求是“设计参数”，请勿偏离到实现细节。