cli-creator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CLI Creator

CLI创建器

Create a real CLI that future Codex threads can run by command name from any working directory.

This skill is for durable tools, not one-off scripts. If a short script in the current repo solves the task, write the script there instead.

创建可在任意工作目录下通过命令名运行、供未来Codex线程调用的正式CLI。

本skill用于构建持久化工具，而非一次性脚本。如果当前代码库中的短脚本即可解决需求，请直接编写脚本即可。

Start

开始

Name the target tool, its source, and the first real jobs it should do:

Source: API docs, OpenAPI JSON, SDK docs, curl examples, browser app, existing internal script, article, or working shell history.

Jobs: literal reads/writes such as

list drafts

download failed job logs

search messages

upload media

read queue schedule

Install name: a short binary name such as
```
ci-logs
```
,
```
slack-cli
```
,
```
sentry-cli
```
, or
```
buildkite-logs
```
.

Prefer a new folder under

~/code/clis/<tool-name>

when the user wants a personal tool and has not named a repo.

Before scaffolding, check whether the proposed command already exists:

bash

command -v <tool-name> || true

If it exists, choose a clearer install name or ask the user.

指定目标工具名称、来源以及它需要完成的首批实际任务：

来源：API文档、OpenAPI JSON、SDK文档、curl示例、浏览器应用、现有内部脚本、文章或可用的shell历史记录。

任务：明确的读写操作，例如

list drafts

、

download failed job logs

、

search messages

、

upload media

、

read queue schedule

。

安装名称：简短的二进制文件名，例如
```
ci-logs
```
、
```
slack-cli
```
、
```
sentry-cli
```
或
```
buildkite-logs
```
。

当用户需要个人工具且未指定代码库时，优先在

~/code/clis/<tool-name>

路径下新建文件夹。

搭建框架前，请检查提议的命令是否已存在：

bash

command -v <tool-name> || true

如果已存在，请选择更清晰的安装名称或询问用户。

Choose the Runtime

选择运行时

Before choosing, inspect the user's machine and source material:

bash

command -v cargo rustc node pnpm npm python3 uv || true

Then choose the least surprising toolchain:

Default to Rust for a durable CLI Codex should run from any repo: one fast binary, strong argument parsing, good JSON handling, easy copy/install into
```
~/.local/bin
```
.
Use TypeScript/Node when the official SDK, auth helper, browser automation library, or existing repo tooling is the reason the CLI can be better.
Use Python when the source is data science, local file transforms, notebooks, SQLite/CSV/JSON analysis, or Python-heavy admin tooling that can still be installed as a durable command.

Do not pick a language that adds setup friction unless it materially improves the CLI. If the best language is not installed, either install the missing toolchain with the user's approval or choose the next-best installed option.

State the choice in one sentence before scaffolding, including the reason and the installed toolchain you found.

选择前，请检查用户的机器环境和源材料：

bash

command -v cargo rustc node pnpm npm python3 uv || true

然后选择最符合用户预期的工具链：

默认选择Rust构建Codex可在任意代码库运行的持久化CLI：单文件高速二进制、强大的参数解析能力、优秀的JSON处理能力、可轻松复制/安装到
```
~/.local/bin
```
。
当官方SDK、身份验证助手、浏览器自动化库或现有代码库工具能让CLI功能更完善时，使用TypeScript/Node。
当来源是数据科学、本地文件转换、notebook、SQLite/CSV/JSON分析或以Python为主的管理工具时，使用Python，仍可将其安装为持久化命令。

除非能显著提升CLI的功能，否则不要选择会增加配置复杂度的语言。如果最优语言未安装，要么经用户同意安装缺失的工具链，要么选择次优的已安装选项。

搭建框架前用一句话说明你的选择，包括选择原因和你发现的已安装工具链。

Command Contract

命令约定

Sketch the command surface in chat before coding. Include the binary name, discovery commands, resolve or ID-lookup commands, read commands, write commands, raw escape hatch, auth/config choice, and PATH/install command.

When designing the command surface, read references/agent-cli-patterns.md for the expected composable CLI shape.

Build toward this surface:

```
tool-name --help
```
shows every major capability.
```
tool-name --json doctor
```
verifies config, auth, version, endpoint reachability, and missing setup.
```
tool-name init ...
```
stores local config when env-only auth is painful.
Discovery commands find accounts, projects, workspaces, teams, queues, channels, repos, dashboards, or other top-level containers.
Resolve commands turn names, URLs, slugs, permalinks, customer input, or build links into stable IDs so future commands do not repeat broad searches.
Read commands fetch exact objects and list/search collections. Paginated lists support a bounded
```
--limit
```
, cursor, offset, or clearly documented default.
Write commands do one named action each: create, update, delete, upload, schedule, retry, comment, draft. They accept the narrowest stable resource ID, support
```
--dry-run
```
,
```
draft
```
, or
```
preview
```
first when the service allows it, and do not hide writes inside broad commands such as
```
fix
```
,
```
debug
```
, or
```
auto
```
.
```
--json
```
returns stable machine-readable output.
A raw escape hatch exists:
```
request
```
,
```
tool-call
```
,
```
api
```
, or the nearest honest name.

Do not expose only a generic

request

command. Give Codex high-level verbs for the repeated jobs.

Document the JSON policy in the CLI README or equivalent: API pass-through versus CLI envelope, success shape, error shape, and one example for each command family. Under

--json

, errors must be machine-readable and must not contain credentials.

编码前先在聊天中勾勒命令边界，包括二进制文件名、发现命令、解析或ID查找命令、读取命令、写入命令、原始逃逸接口、身份验证/配置选择以及PATH/安装命令。

设计命令边界时，请阅读references/agent-cli-patterns.md了解预期的可组合CLI结构。

朝着以下结构构建：

```
tool-name --help
```
展示所有核心功能。
```
tool-name --json doctor
```
验证配置、身份验证、版本、端点可达性和缺失的配置项。
```
tool-name init ...
```
在仅用环境变量进行身份验证过于繁琐时存储本地配置。
发现命令用于查找账户、项目、工作空间、团队、队列、频道、代码库、仪表盘或其他顶层容器。
解析命令将名称、URL、slug、永久链接、客户输入或构建链接转换为稳定ID，避免未来命令重复执行大范围搜索。
读取命令获取精确对象并列出/搜索集合。分页列表支持有限的
```
--limit
```
、游标、偏移量或明确记录的默认值。
写入命令每个仅执行一个指定操作：创建、更新、删除、上传、调度、重试、评论、草稿。它们接收最精简的稳定资源ID，服务允许时优先支持
```
--dry-run
```
、
```
draft
```
或
```
preview
```
，不要将写入操作隐藏在
```
fix
```
、
```
debug
```
或
```
auto
```
这类宽泛命令中。
```
--json
```
返回稳定的机器可读输出。
提供原始逃逸接口：
```
request
```
、
```
tool-call
```
、
```
api
```
或其他最贴切的名称。

不要仅对外暴露通用的

request

命令，要为Codex提供重复任务的高阶动词。

在CLI README或等效文档中记录JSON规则：API透传与CLI封装、成功返回结构、错误返回结构，以及每个命令系列的一个示例。使用

--json

时，错误必须是机器可读的，且不得包含凭证信息。

Auth and Config

身份验证与配置

Support the boring paths first, in this precedence order:

Environment variable using the service's standard name, such as
```
GITHUB_TOKEN
```
.
User config under
```
~/.<tool-name>/config.toml
```
or another simple documented path.
```
--api-key
```
or a tool-specific token flag only for explicit one-off tests. Prefer env/config for normal use because flags can leak into shell history or process listings.

Never print full tokens.

doctor --json

should say whether a token is available, the auth source category (

flag

env

config

, provider default, or missing), and what setup step is missing.

If the CLI can run without network or auth, make that explicit in

doctor --json

: report fixture/offline mode, whether fixture data was found, and whether auth is not required for that mode.

For internal web apps sourced from DevTools curls, create sanitized endpoint notes before implementing: resource name, method/path, required headers, auth mechanism, CSRF behavior, request body, response ID fields, pagination, errors, and one redacted sample response. Never commit copied cookies, bearer tokens, customer secrets, or full production payloads.

Use screenshots to infer workflow, UI vocabulary, fields, and confirmation points. Do not treat screenshots as API evidence unless they are paired with a network request, export, docs page, or fixture.

优先支持通用路径，按以下优先级排序：

使用服务标准名称的环境变量，例如
```
GITHUB_TOKEN
```
。
存储在
```
~/.<tool-name>/config.toml
```
或其他简单文档化路径下的用户配置。
仅用于明确的一次性测试的
```
--api-key
```
或工具专属的token标志。常规使用优先选择环境变量/配置，因为标志可能会泄露到shell历史或进程列表中。

永远不要打印完整token。

doctor --json

应说明token是否可用、身份验证来源类别（

flag

、

env

、

config

、提供商默认值或缺失），以及缺少的配置步骤。

如果CLI无需网络或身份验证即可运行，请在

doctor --json

中明确说明：报告fixture/离线模式、是否找到fixture数据，以及该模式是否不需要身份验证。

对于源自DevTools curl请求的内部Web应用，实现前先创建清理后的端点说明：资源名称、方法/路径、必填头、身份验证机制、CSRF行为、请求体、响应ID字段、分页、错误，以及一个脱敏的示例响应。永远不要提交复制的Cookie、Bearer token、客户机密或完整的生产负载。

使用截图推断工作流、UI词汇、字段和确认点。除非截图与网络请求、导出、文档页面或fixture搭配使用，否则不要将截图视为API依据。

Build Workflow

构建工作流

Read the source just enough to inventory resources, auth, pagination, IDs, media/file flows, rate limits, and dangerous write actions. If the docs expose OpenAPI, download or inspect it before naming commands.
Sketch the command list in chat. Keep names short and shell-friendly.
Scaffold the CLI with a README or equivalent repo-facing instructions.
Implement
```
doctor
```
, discovery, resolve, read commands, one narrow draft or dry-run write path if requested, and the raw escape hatch.
Install the CLI on PATH so
```
tool-name ...
```
works outside the source folder.
Smoke test from another repo or
```
/tmp
```
, not only with
```
cargo run
```
or package-manager wrappers. Run
```
command -v <tool-name>
```
,
```
<tool-name> --help
```
, and
```
<tool-name> --json doctor
```
.
Run format, typecheck/build, unit tests for request builders, pagination/request-body builders, no-auth
```
doctor
```
, help output, and at least one fixture, dry-run, or live read-only API call.

If a live write is needed for confidence, ask first and make it reversible or draft-only.

When the source is an existing script or shell history, split the working invocation into real phases: setup, discovery, download/export, transform/index, draft, upload, poll, live write. Preserve the flags, paths, and environment variables the user already relies on, then wrap the repeatable phases with stable IDs, bounded JSON, and file outputs.

For raw escape hatches, support read-only calls first. Do not run raw non-GET/HEAD requests against a live service unless the user asked for that specific write.

For media, artifact, or presigned upload flows, test each phase separately: create upload, transfer bytes, poll/read processing status, then attach or reference the resulting ID.

For fixture-backed prototypes, keep fixtures in a predictable project path and make the CLI locate them after installation. Smoke-test from

/tmp

to catch binaries that only work inside the source folder.

For log-oriented CLIs, keep deterministic snippet extraction separate from model interpretation. Prefer a command that emits filenames, line numbers or byte ranges, matched rules, and short excerpts.

适度阅读源材料，梳理资源、身份验证、分页、ID、媒体/文件流、速率限制和高危写入操作。如果文档提供OpenAPI，命名命令前先下载或检查该规范。
在聊天中勾勒命令列表，保持名称简短且符合shell使用习惯。
搭建CLI框架，提供README或面向代码库的等效说明。
实现
```
doctor
```
、发现、解析、读取命令，如果有需求还可实现一个精简的草稿或试运行写入路径，以及原始逃逸接口。
将CLI安装到PATH中，确保在源文件夹外也能运行
```
tool-name ...
```
。
从另一个代码库或
```
/tmp
```
目录进行冒烟测试，不要仅使用
```
cargo run
```
或包管理器包装器测试。运行
```
command -v <tool-name>
```
、
```
<tool-name> --help
```
和
```
<tool-name> --json doctor
```
。
执行格式化、类型检查/构建、请求构建器单元测试、分页/请求体构建器测试、无身份验证
```
doctor
```
测试、帮助输出测试，以及至少一个fixture、试运行或实时只读API调用测试。

如果需要实时写入来验证功能，请先询问用户，且确保操作可撤销或仅为草稿模式。

当来源是现有脚本或shell历史记录时，将可用的调用拆分为实际阶段：设置、发现、下载/导出、转换/索引、草稿、上传、轮询、实时写入。保留用户已经习惯使用的标志、路径和环境变量，然后用稳定ID、有限JSON和文件输出封装可重复的阶段。

对于原始逃逸接口，优先支持只读调用。除非用户明确要求特定写入操作，否则不要对实时服务运行非GET/HEAD的原始请求。

对于媒体、制品或预签名上传流，分别测试每个阶段：创建上传、传输字节、轮询/读取处理状态，然后附加或引用生成的ID。

对于基于fixture的原型，将fixture存放在可预测的项目路径中，确保CLI安装后可以定位到它们。从

/tmp

目录进行冒烟测试，排查仅能在源文件夹内运行的二进制文件问题。

对于面向日志的CLI，将确定性的片段提取与模型解释分开。优先选择输出文件名、行号或字节范围、匹配规则和简短摘录的命令。

Rust Defaults

Rust默认规范

When building in Rust, use established crates instead of custom parsers:

```
clap
```
for commands and help
```
reqwest
```
for HTTP
```
serde
```
/
```
serde_json
```
for payloads
```
toml
```
for small config files
```
anyhow
```
for CLI-shaped error context

Add a

Makefile

target such as

make install-local

that builds release and installs the binary into

~/.local/bin

使用Rust构建时，使用成熟的crates而非自定义解析器：

```
clap
```
用于命令和帮助信息
```
reqwest
```
用于HTTP请求
```
serde
```
/
```
serde_json
```
用于负载处理
```
toml
```
用于小型配置文件
```
anyhow
```
用于CLI风格的错误上下文

添加

make install-local

这类Makefile目标，用于构建发布版本并将二进制文件安装到

~/.local/bin

。

TypeScript/Node Defaults

TypeScript/Node默认规范

When building in TypeScript/Node, keep the CLI installable as a normal command:

```
commander
```
or
```
cac
```
for commands and help
native
```
fetch
```
, the official SDK, or the user's existing HTTP helper for API calls
```
zod
```
only where external payload validation prevents real breakage
```
package.json
```
```
bin
```
entry for the installed command
```
tsup
```
,
```
tsx
```
, or
```
tsc
```
using the repo's existing convention

Add an install path such as

pnpm install

pnpm build

, and

pnpm link --global

, or a

Makefile

target that installs a small wrapper into

~/.local/bin

使用TypeScript/Node构建时，确保CLI可以作为普通命令安装：

```
commander
```
或
```
cac
```
用于命令和帮助信息
原生
```
fetch
```
、官方SDK或用户现有的HTTP助手用于API调用
仅在外部负载验证可以避免实际故障时使用
```
zod
```
```
package.json
```
的
```
bin
```
字段配置安装的命令
遵循代码库现有约定使用
```
tsup
```
、
```
tsx
```
或
```
tsc
```

添加安装路径说明，例如

pnpm install

、

pnpm build

和

pnpm link --global

，或添加Makefile目标将小型包装器安装到

~/.local/bin

。

Python Defaults

Python默认规范

When building in Python, prefer boring standard-library pieces unless the workflow needs more:

```
argparse
```
for commands and help, or
```
typer
```
when subcommands would otherwise get messy
```
urllib.request
```
/
```
urllib.parse
```
,
```
requests
```
, or
```
httpx
```
for HTTP, matching what is already installed or already used nearby
```
json
```
,
```
csv
```
,
```
sqlite3
```
,
```
pathlib
```
, and
```
subprocess
```
for local files, exports, databases, and existing scripts
```
pyproject.toml
```
console script or a small executable wrapper for the installed command
```
uv
```
or a virtualenv only when dependencies are actually needed

Add a

Makefile

target such as

make install-local

that installs the command on PATH and document whether it depends on

uv

, a virtualenv, or only system Python.

使用Python构建时，优先使用通用的标准库组件，除非工作流需要更多功能：

```
argparse
```
用于命令和帮助信息，子命令过于复杂时使用
```
typer
```
```
urllib.request
```
/
```
urllib.parse
```
、
```
requests
```
或
```
httpx
```
用于HTTP请求，匹配已安装或周边已使用的库
```
json
```
、
```
csv
```
、
```
sqlite3
```
、
```
pathlib
```
和
```
subprocess
```
用于本地文件、导出、数据库和现有脚本处理
```
pyproject.toml
```
配置控制台脚本或小型可执行包装器作为安装命令
仅在确实需要依赖时使用
```
uv
```
或virtualenv

添加

make install-local

这类Makefile目标，用于将命令安装到PATH中，并说明它是否依赖

uv

、virtualenv或仅依赖系统Python。

Companion Skill

配套Skill

After the CLI works, create or update a small skill for it. Use

$skill-creator

when it is available. Use

$CODEX_HOME/skills/<tool-name>/SKILL.md

for a personal companion skill unless the user names a repo-local

.codex/skills/...

path or another skill repo.

Write the companion skill in the order a future Codex thread should use the CLI, not as a tour of every feature. Explain:

How to verify the installed command exists.
Which command to run first.
How auth is configured.
Which discovery command finds the common ID.
The safe read path.
The intended draft/write path.
The raw escape hatch.
What not to do without explicit user approval.
Three copy-pasteable command examples.

Keep API reference details in the CLI docs or a skill reference file. Keep the skill focused on ordering, safety, and examples future Codex threads should actually run.

CLI正常运行后，为其创建或更新一个小型skill。如果

$skill-creator

可用请使用它。除非用户指定了代码库本地的

.codex/skills/...

路径或其他skill代码库，否则个人配套skill请存放在

$CODEX_HOME/skills/<tool-name>/SKILL.md

。

按照未来Codex线程使用CLI的顺序编写配套skill，而非罗列所有功能。说明以下内容：

如何验证已安装的命令存在
首先要运行的命令
身份验证的配置方式
哪个发现命令可以查找通用ID
安全的读取路径
预期的草稿/写入路径
原始逃逸接口
未经用户明确批准禁止的操作
三个可直接复制粘贴的命令示例

将API参考细节放在CLI文档或skill参考文件中，让skill聚焦于未来Codex线程实际运行的顺序、安全规则和示例。