cli-builder

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CLI Builder

CLI 构建工具

Build production-quality CLI tools for any module or application, in any language.

Reference files (read on demand, not upfront):

```
references/cli-libraries.md
```
— read during Step 2 (Design) to recommend libraries and during Step 4 (Execute) for starter scaffolds
```
references/testing-patterns.md
```
— read during Step 4 (Execute) when writing tests

为任意语言的模块或应用构建生产级别的CLI工具。

参考文件（按需读取，无需预先读取）：

```
references/cli-libraries.md
```
— 在步骤2（设计）中读取以推荐库，在步骤4（执行）中读取以获取初始脚手架
```
references/testing-patterns.md
```
— 在步骤4（执行）编写测试时读取

Repo Sync Before Edits (mandatory)

编辑前的仓库同步（必填）

Before creating/updating/deleting files in an existing repository, sync the current branch with remote:

bash

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

If the working tree is not clean, stash first, sync, then restore:

bash

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

origin

is missing, pull is unavailable, or rebase/stash conflicts occur, stop and ask the user before continuing.

在现有仓库中创建/更新/删除文件前，将当前分支与远程仓库同步：

bash

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin
git pull --rebase origin "$branch"

如果工作区未清理，请先暂存，同步后再恢复：

bash

git stash push -u -m "pre-sync"
branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin && git pull --rebase origin "$branch"
git stash pop

如果缺少

origin

、无法拉取或出现变基/暂存冲突，请停止操作并询问用户后再继续。

Branch-First Safety Rule

分支优先安全规则

Before changing any file, check the current branch. Only create a new branch if on

main

master

— otherwise continue on the existing branch (the user likely set it up already or is resuming work):

bash

current_branch="$(git rev-parse --abbrev-ref HEAD)"
if [ "$current_branch" = "main" ] || [ "$current_branch" = "master" ]; then
  slug="$(echo "${CLI_NAME:-cli}" | tr '[:upper:] ' '[:lower:]-' | tr -cd 'a-z0-9-')"
  ts="$(date +%Y%m%d-%H%M%S)"
  git checkout -b "feat/cli-${slug}-${ts}"
fi

修改任何文件前，检查当前分支。仅当处于

main

或

master

分支时才创建新分支——否则继续使用现有分支（用户可能已设置好或正在恢复工作）：

bash

current_branch="$(git rev-parse --abbrev-ref HEAD)"
if [ "$current_branch" = "main" ] || [ "$current_branch" = "master" ]; then
  slug="$(echo "${CLI_NAME:-cli}" | tr '[:upper:] ' '[:lower:]-' | tr -cd 'a-z0-9-')"
  ts="$(date +%Y%m%d-%H%M%S)"
  git checkout -b "feat/cli-${slug}-${ts}"
fi

Mandatory 5-Step Workflow (approval-gated)

强制5步工作流（需审批）

Step 1: Analyze

步骤1：分析

Understand the project before proposing anything.

Auto-detect language by checking for manifest files:

```
package.json
```
/
```
tsconfig.json
```
-> JavaScript/TypeScript

pyproject.toml

setup.py

setup.cfg

requirements.txt

-> Python

```
go.mod
```
-> Go
```
Cargo.toml
```
-> Rust
```
pom.xml
```
/
```
build.gradle
```
/
```
build.gradle.kts
```
-> Java/Kotlin
```
Gemfile
```
/
```
*.gemspec
```
-> Ruby

Identify existing CLI/entry points: check for

bin

fields,

__main__.py

main.go

fn main()

, existing arg parsing code, or

scripts

in package.json.

Understand module structure: public API, core functions, data types, dependencies.

Ask clarifying questions (only what cannot be inferred):

Primary use case (automation, developer tool, data processing, admin)
Target audience (developers, ops, end users)
Single command or multi-command (subcommand tree)
Output formats needed (text, JSON, table, CSV)
Distribution method (pip/npm/go install, standalone binary, source)

Present findings and wait for approval before proceeding.

在提出方案前先了解项目。

自动检测语言：通过检查清单文件判断：

```
package.json
```
/
```
tsconfig.json
```
-> JavaScript/TypeScript

pyproject.toml

setup.py

setup.cfg

requirements.txt

-> Python

```
go.mod
```
-> Go
```
Cargo.toml
```
-> Rust
```
pom.xml
```
/
```
build.gradle
```
/
```
build.gradle.kts
```
-> Java/Kotlin
```
Gemfile
```
/
```
*.gemspec
```
-> Ruby

识别现有CLI/入口点：检查

bin

字段、

__main__.py

、

main.go

、

fn main()

、现有参数解析代码或

package.json

中的

scripts

。

了解模块结构：公共API、核心功能、数据类型、依赖项。

提出澄清问题（仅针对无法推断的内容）：

主要用例（自动化、开发者工具、数据处理、管理）
目标受众（开发者、运维人员、终端用户）
单命令还是多命令（子命令树）
需要的输出格式（文本、JSON、表格、CSV）
分发方式（pip/npm/go install、独立二进制文件、源码）

呈现分析结果，等待审批后再继续。

Step 2: Design

步骤2：设计

Present a structured CLI design document:

Tool name and binary/entry point name
Command tree (visual hierarchy for multi-command tools)
Arguments and options per command (name, type, required/optional, default, help text)
Global options (verbose, quiet, output format, config file, no-color)
I/O behavior (stdin support, stdout/stderr separation, piping)
Config strategy (CLI args > env vars > config file > defaults)
Example invocations (at least 3 realistic examples showing common use cases)

Iterate until user approves:

Ask for feedback
Adjust design
Repeat until explicit approval

No implementation before design approval.

提交结构化的CLI设计文档：

工具名称和二进制/入口点名称
命令树（多命令工具的可视化层级）
每个命令的参数和选项（名称、类型、必填/可选、默认值、帮助文本）
全局选项（详细日志、静默模式、输出格式、配置文件、无颜色）
I/O行为（支持标准输入、标准输出/错误输出分离、管道）
配置策略（CLI参数 > 环境变量 > 配置文件 > 默认值）
示例调用（至少3个展示常见用例的真实示例）

反复迭代直到用户审批：

征求反馈
调整设计
重复直到获得明确审批

未获得设计审批前不得开始实现。

Step 3: Plan

步骤3：规划

Break implementation into three phases, each with granular tasks.

Phase 1 — Foundation (get a working CLI skeleton):

Entry point and arg parsing setup
One core command (the most important one)
Help text and version flag
Basic tests (help output, version, one command)

Phase 2 — Complete (full feature set):

All remaining commands
Input validation and error handling
Output formatting (text, JSON, table as designed)
Comprehensive tests

Phase 3 — Polish (optional, confirm with user):

Config file support
Environment variable overrides
Shell completions (bash, zsh, fish)
Distribution/packaging setup (setup.py, package.json bin, goreleaser, etc.)

Each task includes:

Goal: one sentence
Files: create or modify
Expected behavior: what the user can do after this task
Test: how to verify
Effort: S / M / L

Iterate the plan with user until approved.

No execution before plan approval.

将实现分为三个阶段，每个阶段包含细化任务。

阶段1 — 基础搭建（搭建可运行的CLI骨架）：

入口点和参数解析设置
一个核心命令（最重要的命令）
帮助文本和版本标识
基础测试（帮助输出、版本、单个命令）

阶段2 — 功能完善（完整功能集）：

所有剩余命令
输入验证和错误处理
输出格式化（按设计实现文本、JSON、表格格式）
全面测试

阶段3 — 优化打磨（可选，需与用户确认）：

配置文件支持
环境变量覆盖
Shell补全（bash、zsh、fish）
分发/打包设置（setup.py、package.json bin、goreleaser等）

每个任务包含：

目标：一句话描述
文件：需创建或修改的文件
预期行为：完成该任务后用户可执行的操作
测试：验证方式
工作量：S / M / L

与用户迭代规划直到获得审批。

未获得规划审批前不得开始执行。

Step 4: Execute

步骤4：执行

Implement the approved plan task by task:

Implement one task
Run tests after each task
Demo between phases (show example commands and output)
Commit per phase with descriptive message

If tests fail, fix before moving to the next task. If a design issue is discovered during implementation, pause and discuss with user.

按审批后的规划逐步实现：

实现单个任务
每个任务完成后运行测试
阶段间进行演示（展示示例命令和输出）
按阶段提交并添加描述性信息

如果测试失败，修复后再进行下一个任务。如果在实现过程中发现设计问题，暂停并与用户讨论。

Step 5: Summarize

步骤5：总结

Deliver a final summary:

Design summary: tool name, command tree, key options
Implementation summary: files created/modified, libraries used, patterns applied
Test results: pass/fail counts, coverage if available
Usage quick-start: install command, 3-5 example invocations
Next steps: suggested improvements, missing features, distribution TODO

提交最终总结：

设计总结：工具名称、命令树、关键选项
实现总结：创建/修改的文件、使用的库、应用的模式
测试结果：通过/失败数量，若有则包含覆盖率
快速入门指南：安装命令、3-5个使用示例
后续步骤：建议的改进、缺失的功能、分发待办事项

Expected Output

预期输出

After running this skill on a Python module called

mylib

, the final deliverable looks like:

feat/cli-mylib-20260419-143200 branch created

Files created:
  cli/main.py          — entry point with argparse/click/typer wiring
  cli/commands/run.py  — "mylib run" subcommand
  cli/commands/info.py — "mylib info" subcommand
  tests/test_cli.py    — CLI smoke tests (help, version, run)
  pyproject.toml       — updated with [project.scripts] entry point

Usage quick-start:
  pip install -e .
  mylib --help
  mylib run --input data.csv --output results.json
  mylib info --format json

Step Completion Report (Steps 4-5):

◆ Execute + Summarize (step 4-5 of 5 — mylib CLI)
··································································
  Implementation:        √ pass (3 commands, 2 files)
  Test coverage:         √ pass (8/8 tests passing)
  Phase demos completed: √ pass (help, version, run verified)
  Summary delivered:     √ pass
  Criteria:              √ 4/4 met
  ____________________________
  Result:                PASS

将此技能应用于名为

mylib

的Python模块后，最终交付成果如下：

feat/cli-mylib-20260419-143200 分支已创建

创建的文件：
  cli/main.py          — 带有argparse/click/typer配置的入口点
  cli/commands/run.py  — "mylib run"子命令
  cli/commands/info.py — "mylib info"子命令
  tests/test_cli.py    — CLI冒烟测试（帮助、版本、运行）
  pyproject.toml       — 更新了[project.scripts]入口点

快速入门指南：
  pip install -e .
  mylib --help
  mylib run --input data.csv --output results.json
  mylib info --format json

步骤完成报告（步骤4-5）：

◆ 执行 + 总结（第4-5步，共5步 — mylib CLI）
··································································
  实现情况：        √ 通过（3个命令，2个文件）
  测试覆盖率：         √ 通过（8/8测试通过）
  阶段演示完成： √ 通过（帮助、版本、运行已验证）
  总结已交付：     √ 通过
  验收标准：              √ 4/4已满足
  ____________________________
  结果：                通过

Edge Cases

边缘情况

No clear module to wrap: Ask the user what functions/features the CLI should expose before proceeding with analysis.
Multiple languages detected: Present a choice; recommend the language with the most existing CLI-related code.
Existing CLI found: Offer to extend or refactor rather than rebuild; audit what already exists first.
Monorepo with many packages: Ask which package/service should get the CLI; scope the analysis to that subtree.
No test framework present: Add a minimal test setup (pytest, jest, go test) as part of Phase 1 foundation tasks.
Binary output required (standalone .exe / compiled): Note distribution method during Design phase and add build step (PyInstaller, pkg, goreleaser) to Phase 3 polish.
User approves design but rejects implementation: Return to Design phase; do not silently proceed with the rejected approach.

无明确可封装的模块：在开始分析前，询问用户CLI应暴露哪些功能/特性。
检测到多种语言：提供选择；推荐已有CLI相关代码最多的语言。
发现现有CLI：提供扩展或重构选项而非重新构建；先审核现有CLI。
包含多个包的单体仓库：询问应为哪个包/服务添加CLI；将分析范围限定到该子目录。
无测试框架：在阶段1基础任务中添加最小化测试设置（pytest、jest、go test）。
需要二进制输出（独立.exe/编译文件）：在设计阶段注明分发方式，并在阶段3优化中添加构建步骤（PyInstaller、pkg、goreleaser）。
用户批准设计但拒绝实现方案：返回设计阶段；不得擅自继续使用被拒绝的方案。

Acceptance Criteria

验收标准

Language is auto-detected from manifest files before asking clarifying questions
CLI design document is presented and explicitly approved before any implementation begins
Implementation plan is presented and explicitly approved before execution starts
```
--help
```
works at every command level and
```
--version
```
is implemented
Exit codes follow POSIX convention (0 = success, 1 = runtime error, 2 = usage error)
Error messages go to stderr; clean output goes to stdout (pipeable)
```
NO_COLOR
```
env var or
```
--no-color
```
flag is respected
Tests are written and pass before moving to the next phase
Final summary includes install command and at least 3 usage examples

在提出澄清问题前，已通过清单文件自动检测语言
在开始任何实现前，已提交CLI设计文档并获得明确审批
在开始执行前，已提交实现规划并获得明确审批
```
--help
```
在每个命令层级都可用，且已实现
```
--version
```
标识
退出码遵循POSIX规范（0 = 成功，1 = 运行时错误，2 = 使用错误）
错误信息输出到stderr；干净的输出输出到stdout（支持管道）
尊重
```
NO_COLOR
```
环境变量或
```
--no-color
```
标识
在进入下一阶段前已编写并通过测试
最终总结包含安装命令和至少3个使用示例

Step Completion Reports

步骤完成报告

After completing each major step, output a status report in this format:

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

Adapt the check names to match what the step actually validates. Use

√

for pass,

×

for fail, and

—

to add brief context. The "Criteria" line summarizes how many acceptance criteria were met. The "Result" line gives the overall verdict.

完成每个主要步骤后，按以下格式输出状态报告：

◆ [步骤名称]（第N步，共M步 — [上下文]）
··································································
  [检查项1]:          √ 通过
  [检查项2]:          √ 通过（如有相关说明请注明）
  [检查项3]:          × 未通过 — [原因]
  [检查项4]:          √ 通过
  验收标准：         √ N/M已满足
  ____________________________
  结果：             通过 | 未通过 | 部分通过

根据步骤实际验证内容调整检查项名称。使用

√

表示通过，

×

表示未通过，

—

添加简要上下文。“验收标准”行总结已满足的验收标准数量。“结果”行给出整体结论。

Skill-specific checks per phase

各阶段的技能专属检查项

Phase: Analyze (Step 1) — checks:

Project analysis

Language detected

Entry points identified

Clarifying questions asked

Phase: Design (Step 2) — checks:

Design approval

Command tree defined

I/O behavior specified

Example invocations provided

Phase: Plan (Step 3) — checks:

Plan approval

Phases broken down

Tasks have goals and tests

Effort estimated

Phase: Execute + Summarize (Steps 4–5) — checks:

Implementation

Test coverage

Phase demos completed

Summary delivered

阶段：分析（步骤1） — 检查项：

项目分析

、

语言检测

、

入口点识别

、

澄清问题提出

阶段：设计（步骤2） — 检查项：

设计审批

、

命令树定义

、

I/O行为指定

、

示例调用提供

阶段：规划（步骤3） — 检查项：

规划审批

、

阶段拆分

、

任务包含目标和测试

、

工作量预估

阶段：执行 + 总结（步骤4–5） — 检查项：

实现情况

、

测试覆盖率

、

阶段演示完成

、

总结交付

Error Handling

错误处理

Situation	Action
No clear module to wrap	Ask user what functionality the CLI should expose
Multiple languages detected	Ask user which language to use, recommend the one with more CLI code
Existing CLI found	Offer to extend/refactor rather than rebuild; audit existing CLI first
Unknown framework requested	Research the framework, ask user for docs link if needed
Tests fail after implementation	Fix before proceeding; never skip broken tests

场景	操作
无明确可封装的模块	询问用户CLI应暴露哪些功能
检测到多种语言	询问用户使用哪种语言，推荐CLI代码更多的语言
发现现有CLI	提供扩展/重构选项而非重新构建；先审核现有CLI
请求使用未知框架	研究该框架，如需请向用户索要文档链接
实现后测试失败	修复后再继续；绝不跳过失败的测试

Quality Guardrails

质量保障规则

Every CLI built with this skill must include:

Help text: every command and option has a description (
```
--help
```
works at every level)
Error messages: written to stderr, include what went wrong and how to fix it
Exit codes: 0 = success, 1 = runtime error, 2 = usage error (follow POSIX convention)
POSIX conventions:
```
--long-flag
```
,
```
-s
```
short flag,
```
--
```
to end options
Pipeable I/O: support stdin when it makes sense, clean stdout for piping
No-color support: respect
```
NO_COLOR
```
env var or
```
--no-color
```
flag
Version flag:
```
--version
```
prints version and exits

使用此技能构建的每个CLI必须包含：

帮助文本：每个命令和选项都有描述（
```
--help
```
在每个层级都可用）
错误信息：输出到stderr，包含问题原因和解决方法
退出码：0 = 成功，1 = 运行时错误，2 = 使用错误（遵循POSIX规范）
POSIX规范：
```
--long-flag
```
、
```
-s
```
短标识、
```
--
```
结束选项
可管道化I/O：合理情况下支持标准输入，干净的标准输出用于管道
无颜色支持：尊重
```
NO_COLOR
```
环境变量或
```
--no-color
```
标识
版本标识：
```
--version
```
打印版本并退出