create-cli

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
```
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.

阅读
```
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.

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

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

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时，需生成一份用户可直接实现的简洁规范：

命令树+使用概要。
参数/标志表格（类型、默认值、必填/可选、示例）。
子命令语义（每个子命令的功能；幂等性；状态变更情况）。
输出规则：标准输出与标准错误；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.

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