Skip to content
cli-creator logo

CLI Creator

cli-creator

创建高质量 Node.js CLI 工具的完整指南。当用户需要构建命令行工具时使用:(1)创建新的 CLI 项目,(2)选择合适的框架和依赖,(3)实现 CLI 功能,(4)配置测试和打包,(5)应用 CLI 最佳实践

SKILL.md

Full skill instructions

CLI Creator

创建高质量、现代化的 Node.js CLI 工具。

概述

本技能提供从零开始创建专业级 CLI 工具的完整工作流,包括框架选择、项目初始化、功能实现、测试配置和打包分发。

快速开始 (5分钟创建最小化CLI)

# 使用本技能的初始化脚本
npx ts-node skills/​cli-creator/​scripts/​init_cli.ts my-cli

# 进入项目目录
cd my-cli

# 运行 CLI
npx . --help
npx . --version

工作流程决策树

用户请求创建 CLI
│
├─ 步骤 1: 框架选择
│  ├─ 评估项目复杂度 (命令数量、交互需求、插件需求)
│  ├─ 参考 references/​framework_comparison.md
│  └─ 推荐: Commander.js (默认) / oclif / Ink
│
├─ 步骤 2: 项目初始化
│  ├─ 运行 scripts/​init_cli.ts 生成项目结构
│  ├─ 选择模板级别 (minimal/​standard/​advanced)
│  └─ 配置项目元数据 (名称、描述、版本)
│
├─ 步骤 3: 开发指导
│  ├─ 实现命令逻辑 (src/​commands/)
│  ├─ 配置 UI 增强 (chalk, ora)
│  ├─ 添加配置管理 (cosmiconfig + zod)
│  └─ 参考 references/​best_practices.md
│
├─ 步骤 4: 测试和打包
│  ├─ 配置测试 (vitest)
│  ├─ 运行 scripts/​validate_cli.ts 验证
│  ├─ 参考 references/​testing_strategies.md
│  └─ 参考 references/​packaging_guide.md
│
└─ 步骤 5: 发布分发
   ├─ npm publish (推荐)
   ├─ npx 一键运行
   └─ 可选: Node.js SEA 单文件打包

核心脚本

scripts/​init_cli.ts

CLI 项目初始化主脚本。

用法:

npx ts-node skills/​cli-creator/​scripts/​init_cli.ts <cli-name> [options]

选项:

  • --framework <name>: 指定框架 (commander/​oclif/​yargs/​ink/​citty/​cac)
  • --template <type>: 模板级别 (minimal/​standard/​advanced)
  • --ui: 包含 UI 库 (chalk + ora)
  • --config: 包含配置管理 (cosmiconfig + zod)
  • --testing: 包含测试配置 (vitest)

示例:

# 最小化 CLI (Commander.js)
npx ts-node skills/​cli-creator/​scripts/​init_cli.ts my-tool

# 标准配置,包含 UI 和测试
npx ts-node skills/​cli-creator/​scripts/​init_cli.ts my-tool --template standard --ui --testing

# 高级配置,oclif 框架
npx ts-node skills/​cli-creator/​scripts/​init_cli.ts my-tool --framework oclif --template advanced

# React UI CLI (Ink)
npx ts-node skills/​cli-creator/​scripts/​init_cli.ts my-tool --framework ink

scripts/​generate_project.ts

基于配置生成完整项目结构。

自动调用: 由 init_cli.ts 内部调用

scripts/​install_dependencies.ts

根据配置安装精确的依赖版本。

自动调用: 由 init_cli.ts 内部调用

scripts/​validate_cli.ts

验证生成的 CLI 项目完整性。

用法:

npx ts-node skills/​cli-creator/​scripts/​validate_cli.ts <project-path>

验证检查:

  • ✓ package.json 格式正确
  • ✓ bin/​run.js 可执行文件存在
  • ✓ tsconfig.json 配置正确
  • ✓ 依赖安装完整
  • ✓ 可以运行 --help
  • ✓ 可以运行 --version
  • ✓ 测试可以运行

参考文档导航

框架选择

何时读取: 用户询问"哪个框架最好?"或需要框架对比时

# 搜索关键词
grep -r "framework comparison" skills/​cli-creator/​references/
grep -r "Commander.js vs oclif" skills/​cli-creator/​references/

文件: references/​framework_comparison.md

  • 框架选择决策树
  • 详细对比表格 (学习曲线、包体积、TypeScript 支持)
  • 推荐场景说明
  • 每个框架的优缺点分析

最佳实践

何时读取: 实现 CLI 功能或改进用户体验时

# 搜索关键词
grep -r "UX principles" skills/​cli-creator/​references/
grep -r "POSIX" skills/​cli-creator/​references/
grep -r "error handling" skills/​cli-creator/​references/

文件: references/​best_practices.md

  • 用户体验原则 (渐进式披露、POSIX 兼容、彩色输出)
  • 代码组织模式
  • 命令设计模式
  • 配置管理最佳实践
  • 性能优化建议

依赖配置

何时读取: 选择和配置依赖时

# 搜索关键词
grep -r "chalk" skills/​cli-creator/​references/
grep -r "vitest" skills/​cli-creator/​references/
grep -r "dependencies" skills/​cli-creator/​references/

文件: references/​dependency_guide.md

  • 最小化依赖方案
  • 完整功能方案
  • 框架特定配置
  • 依赖版本选择建议
  • 安全性考虑

测试策略

何时读取: 配置测试或调试测试问题时

# 搜索关键词
grep -r "vitest" skills/​cli-creator/​references/
grep -r "test" skills/​cli-creator/​references/
grep -r "coverage" skills/​cli-creator/​references/

文件: references/​testing_strategies.md

  • 测试框架选择 (Vitest 推荐)
  • 测试模式 (命令输出测试、单元测试、集成测试)
  • 代码示例
  • 覆盖率配置

打包分发

何时读取: 准备发布 CLI 时

# 搜索关键词
grep -r "npm publish" skills/​cli-creator/​references/
grep -r "SEA" skills/​cli-creator/​references/
grep -r "npx" skills/​cli-creator/​references/

文件: references/​packaging_guide.md

  • 分发方式对比 (npm、npx、Node.js SEA、nexe、Docker)
  • 推荐方案: npm + npx
  • package.json 配置
  • 发布流程
  • 高级: Node.js SEA 单文件

完整技术栈参考

何时读取: 需要深入技术细节或查阅完整库列表时

# 搜索关键词
grep -r "execa" skills/​cli-creator/​references/
grep -r "zod" skills/​cli-creator/​references/
grep -r "cosmiconfig" skills/​cli-creator/​references/

文件: references/​original_reference.md

  • 完整的 node-cli-skill.md 原始内容
  • 所有技术栈和库的详细文档
  • 优秀 CLI 项目参考
  • 设计思路与最佳实践 (完整版)

框架支持策略

支持的框架

框架默认特点推荐场景
Commander.js✅简单、流行、社区成熟中小型 CLI,快速开发
oclif-企业级、插件系统、自动文档大型 CLI、插件化需求
Yargs-功能丰富、中间件支持复杂参数验证
Ink-React 组件化、富交互现代 UI、交互式 CLI
citty-轻量、现代 ESMUnJS 生态
cac-极简、零依赖超轻量级工具

框架选择决策树

项目复杂度评估:
├── 1-3 个简单命令 → Commander.js / cac
├── 3-10 个命令,中等复杂 → Commander.js / Yargs
├── 10+ 个命令,需要插件 → oclif
├── 富 UI/交互式 → Ink
└── 极简/零依赖追求 → cac / citty

模板级别

Minimal

特点: ~5 文件,快速开始 适用: 学习、原型、简单脚本 内容:

  • package.json (最小依赖)
  • tsconfig.json
  • src/​index.ts (简单命令)
  • bin/​run.js

Standard (推荐)

特点: ~15 文件,标准开发流程 适用: 大多数 CLI 项目 内容:

  • package.json (包含测试、lint)
  • tsconfig.json
  • vitest.config.ts
  • biome.json
  • src/​commands/​init.ts
  • src/​lib/​config.ts
  • src/​lib/​logger.ts
  • test/​basic.test.ts
  • bin/​run.js

Advanced

特点: ~25 文件,企业级质量 适用: 大型项目、团队协作 内容:

  • 完整的配置系统 (cosmiconfig + zod)
  • 错误处理体系
  • 多命令组织
  • 完整测试套件
  • 构建和打包配置

常见使用场景

场景 1: 创建新的 CLI 工具

用户: "帮我创建一个 CLI 工具,叫 file-organizer"
Claude:
  1. 收集配置信息 (名称、描述、功能)
  2. 推荐框架 (默认 Commander.js)
  3. 运行 init_cli.ts
  4. 生成项目结构
  5. 安装依赖
  6. 提供使用指南

场景 2: 框架选择建议

用户: "Commander.js 和 oclif 哪个更好?"
Claude:
  1. 加载 framework_comparison.md
  2. 提供对比分析
  3. 根据用户需求推荐

场景 3: CLI 开发问题

用户: "我的 CLI 测试失败了"
Claude:
  1. 加载 testing_strategies.md
  2. 诊断问题
  3. 提供解决方案

场景 4: 添加功能到现有 CLI

用户: "我想在我的 CLI 中添加配置文件支持"
Claude:
  1. 加载 dependency_guide.md
  2. 推荐 cosmiconfig + zod
  3. 提供实现示例

技术栈默认值

核心依赖

{
  "dependencies": {
    "commander": "^12.0.0",
    "chalk": "^5.3.0",
    "ora": "^8.0.0"
  },
  "devDependencies": {
    "typescript": "^5.6.0",
    "tsx": "^4.19.0",
    "vitest": "^2.1.0",
    "@biomejs/​biome": "^1.9.0",
    "@types/​node": "^22.0.0"
  }
}

可选依赖

{
  "dependencies": {
    "cosmiconfig": "^9.0.0",
    "zod": "^3.23.0",
    "execa": "^9.5.0"
  }
}

目录结构示例

my-cli/
├── src/
│   ├── commands/         # 命令实现
│   │   ├── init.ts
│   │   └── build.ts
│   ├── lib/              # 共享库
│   │   ├── config.ts     # 配置管理
│   │   ├── logger.ts     # 日志工具
│   │   └── api.ts        # API客户端
│   ├── utils/            # 工具函数
│   └── index.ts          # 入口
├── test/                 # 测试文件
├── bin/
│   └── run.js            # 可执行文件
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md

开发命令

生成的 CLI 项目包含以下 npm scripts:

{
  "scripts": {
    "dev": "tsx watch src/​index.ts",
    "build": "tsdown src/​index.ts --format cjs,esm",
    "test": "vitest",
    "test:coverage": "vitest run --coverage",
    "lint": "biome check .",
    "format": "biome format . --write",
    "typecheck": "tsc --noEmit"
  }
}

质量检查清单

在发布 CLI 前,确保:

  • 可以运行 --help 显示帮助信息
  • 可以运行 --version 显示版本号
  • 支持 NO_COLOR 环境变量
  • 错误信息清晰有用
  • 测试覆盖率 > 80%
  • TypeScript 编译无错误
  • 通过 lint 检查
  • README.md 包含使用示例
  • package.json 包含正确的 bin 字段

More skills from majiayu000

xiaohongshu logo
majiayu000/claude-arsenal

xiaohongshu

xiaohongshu

286 148
View
agent-task-conductor logo
majiayu000/claude-skill-registry

agent-task-conductor

Conduct multi-agent task orchestration and workflow coordination.

663 1
View
conductor-setup logo
majiayu000/claude-skill-registry

conductor-setup

Initialize project with Conductor artifacts (product definition,

663 1
View
animation-designer logo
majiayu000/claude-skill-registry

animation-designer

Expert in web animations, transitions, and motion design using Framer Motion and CSS

663 1
View
diagramming logo
majiayu000/claude-skill-registry

diagramming

Creates Mermaid and ASCII diagrams for flowcharts, architecture, ERDs, state machines, mindmaps, and more. Use when user mentions diagram, flowchart, mermaid, ASCII diagram, text diagram, terminal diagram, visualize, C4, mindmap, architecture diagram, sequence diagram, ERD, or needs visual docume...

663 1
View
h3-pg logo
majiayu000/claude-skill-registry-data

h3-pg

PostgreSQL bindings for H3 hexagonal grid system. Use when working with H3 cells in Postgres, including spatial indexing, geometry/geography integration, and raster analysis.

23 1
View
conductor-development logo
majiayu000/claude-skill-registry

conductor-development

Context-Driven Development skill for projects using Conductor. Use this skill when you detect a `conductor/` directory in the project, when working on tasks defined in a `plan.md` file, or when the user asks about tracks, specs, or plans. Automatically applies TDD workflow, tracks task completion...

663 1
View
conductor-status logo
majiayu000/claude-skill-registry

conductor-status

Display project status, active tracks, and next actions

663 1
View
dockerization logo
majiayu000/claude-skill-registry

dockerization

Official Stakpak application containerization standard operating procedure, a step-by-step guidline to properly dockerize applications. This is a rule book curated by the Stakpak Team.

663 1
View

Popular AI tools

Kaiber logo
Video

Kaiber

Generate, edit, and beat-sync AI video with leading models in one workspace.

Paid
View
Vimcal logo
Productivity

Vimcal

The world's fastest calendar for remote work

Free
View

Transform Your Design with AI Designer by ImgCreator.ai

Freemium
View
Akool AI logo
Content & writing

Akool AI

Revolutionizing Video Production with AI-Powered Creativity

Paid
View

Extend an image past the frame and let AI fill the new aspect ratio.

Freemium
View
StarByFace logo
Security

StarByFace

Discover your celebrity doppelgänger with StarByFace!

Free
View
C

ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.

Freemium
View
Opus Clip logo
Coding & apps

Opus Clip

Opus.ai: Revolutionize Your Web Experience

Free
View