cli-creation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CLI Creation

CLI创建

Overview

概述

Create runnable DreamCLI starter CLIs and extend them with typed command patterns. Use this skill for user-facing app code, not DreamCLI framework internals.

创建可运行的DreamCLI启动脚手架命令行工具，并使用类型化命令模式对其进行扩展。本技能适用于面向用户的应用代码，而非DreamCLI框架的内部开发。

Quick Start

快速开始

Choose a starter mode:
- ```
single
```
  : one root command (
```
cli(name).default(command)
```
  ).
- ```
multi
```
  : grouped command surface (
```
group('...').command(...)
```
  ).
Generate starter files:
- ```
python scripts/scaffold_cli.py --name mycli --mode single --out .
```
- Tests are generated by default; add
```
--no-test
```
  only when explicitly requested.
- Test template is auto-detected: Bun without Vitest uses
```
bun:test
```
  ; otherwise a Vitest template is generated.
Run and validate generated files:
- Use the printed path from the scaffolder output, for example
```
bun ./mycli.ts --help
```
  .
- Run the generated test unless
```
--no-test
```
  was used.

Extend behavior with references:

```
references/consumer-workflow.md
```
```
references/pattern-cookbook.md
```
```
references/runtime-notes.md
```

选择启动模式：
- ```
single
```
  ：单根命令模式（
```
cli(name).default(command)
```
  ）。
- ```
multi
```
  ：命令分组模式（
```
group('...').command(...)
```
  ）。
生成启动文件：
- ```
python scripts/scaffold_cli.py --name mycli --mode single --out .
```
- 测试文件默认生成；仅当用户明确要求时才添加
```
--no-test
```
  参数。
- 测试模板会自动检测：未搭配Vitest的Bun环境使用
```
bun:test
```
  ；其他情况生成Vitest模板。
运行并验证生成的文件：
- 使用脚手架输出中打印的路径，例如
```
bun ./mycli.ts --help
```
  。
- 除非使用了
```
--no-test
```
  参数，否则运行生成的测试用例。

参考文档扩展功能：

```
references/consumer-workflow.md
```
```
references/pattern-cookbook.md
```
```
references/runtime-notes.md
```

Grounding Sources

参考资源

Use
```
examples/standalone/basic.ts
```
for single-command defaults.
Use
```
examples/standalone/multi-command.ts
```
for grouped-command defaults.

Use

examples/standalone/testing.ts

for

runCommand()

patterns.

Use
```
apps/docs/guide/getting-started.md
```
for baseline consumer narrative.
Use
```
apps/docs/guide/walkthrough.md
```
for richer end-to-end CLI composition.

单命令默认配置参考
```
examples/standalone/basic.ts
```
分组命令默认配置参考
```
examples/standalone/multi-command.ts
```

runCommand()

使用模式参考

examples/standalone/testing.ts

基础用户使用说明参考
```
apps/docs/guide/getting-started.md
```
更丰富的端到端CLI搭建教程参考
```
apps/docs/guide/walkthrough.md
```

Workflow Decision Tree

工作流决策树

User asks for a simple one-command utility:
- Use
```
--mode single
```
  .
User asks for nested command groups (git/gh style):
- Use
```
--mode multi
```
  .
User asks for tests from the start:
- Do nothing; tests are scaffolded by default.
User explicitly asks for no tests:
- Add
```
--no-test
```
  .
User asks for npm/tsx or Deno instructions:
- Keep generated code unchanged and provide runtime command alternatives from
```
references/runtime-notes.md
```
  .

用户需要简单的单命令工具：
- 使用
```
--mode single
```
  。
用户需要嵌套命令组（git/gh风格）：
- 使用
```
--mode multi
```
  。
用户要求从一开始就包含测试：
- 无需额外操作，测试默认已搭建。
用户明确要求不生成测试：
- 添加
```
--no-test
```
  。
用户需要npm/tsx或Deno运行说明：
- 保持生成的代码不变，参考
```
references/runtime-notes.md
```
  提供其他运行时命令选项。

Extend the Starter

扩展脚手架功能

Add typed args with

arg.string()

arg.number()

arg.enum(...)

, and

arg.custom(...)

For repeated positionals, use
```
.variadic()
```
on an arg definition.
Add typed flags with defaults and aliases via
```
flag.*()
```
.
Add env/config/prompt sources on each flag before action logic.
Branch on
```
out.jsonMode
```
for machine-readable responses.
Use
```
runCommand()
```
from
```
@kjanat/dreamcli/testkit
```
for in-process tests.
Keep output assertions explicit, including trailing newlines.

使用

arg.string()

、

arg.number()

、

arg.enum(...)

和

arg.custom(...)

添加类型化参数。

对于重复的位置参数，在参数定义上使用
```
.variadic()
```
。
通过
```
flag.*()
```
添加带默认值和别名的类型化标志。
在执行逻辑之前，为每个标志配置环境变量/配置文件/交互提示等取值来源。
根据
```
out.jsonMode
```
分支返回机器可读的响应。
使用
```
@kjanat/dreamcli/testkit
```
提供的
```
runCommand()
```
进行进程内测试。
保持输出断言显式明确，包括末尾换行符的校验。

Resource Map

资源映射

```
scripts/scaffold_cli.py
```
- Generate Bun-first starter files and optional tests.
```
assets/templates/*.tpl
```
- Source templates used by the scaffold script.
```
references/consumer-workflow.md
```
- End-to-end flow from request to validated CLI.
```
references/pattern-cookbook.md
```
- Copy-ready snippets for common DreamCLI features.
```
references/runtime-notes.md
```
- Runtime and package-manager execution guidance.

```
scripts/scaffold_cli.py
```
- 生成Bun优先的启动文件和可选测试。
```
assets/templates/*.tpl
```
- 脚手架脚本使用的源模板。
```
references/consumer-workflow.md
```
- 从需求到验证可用CLI的端到端流程。
```
references/pattern-cookbook.md
```
- 常用DreamCLI功能的可直接复制的代码片段。
```
references/runtime-notes.md
```
- 运行时和包管理器执行指南。

Guardrails

使用限制

Do not modify DreamCLI core internals for consumer-app requests.

Keep generated imports on

@kjanat/dreamcli

and

@kjanat/dreamcli/testkit

Preserve typed resolution flow: argv -> env -> config -> prompt -> default.
Prefer Bun commands first; include npm/tsx and Deno alternatives when requested.

处理用户应用需求时不要修改DreamCLI核心内部代码。

保持对

@kjanat/dreamcli

和

@kjanat/dreamcli/testkit

的导入语句不变。

保留类型化取值优先级流程：命令行参数 -> 环境变量 -> 配置文件 -> 交互提示 -> 默认值。
优先使用Bun命令；当用户要求时提供npm/tsx和Deno的替代运行方案。