api2cli
Turn any REST API into a standardized, agent-ready CLI.
Always use npx api2cli to run commands. Always use --json when calling generated CLIs programmatically.
Prerequisites
CODEBLOCK0
Workflow
Follow all steps in order — do not skip any.
1. Search the registry first
Before generating anything, check if a CLI already exists:
CODEBLOCK1
If the registry already has the CLI you need, install it instead of rebuilding it:
CODEBLOCK2
See references/commands.md for filters like --type, --category, and --json.
2. Discover the API
Find the API docs or OpenAPI spec. Identify: base URL, auth type, auth header, all resources and endpoints.
3. Create the scaffold
CODEBLOCK3
See references/create.md for all flags and what gets generated.
4. Implement resources
Create ~/.cli/<app>-cli/src/resources/<resource>.ts for each API resource. Register in src/index.ts.
See references/resource-patterns.md for the CRUD template and library API.
5. Build, link, and test
CODEBLOCK4
INLINECODE7 adds ~/.local/bin to PATH automatically. No export PATH needed.
6. Finalize skill and README
This step is mandatory. The skill must become a real operating guide for another agent, not just a command list — no placeholders, no TODOs.
- 1. Introspect the CLI: run
<app>-cli --help, then <resource> --help and <resource> <action> --help for every resource and action - Update the description: list all resource names and add domain-specific trigger phrases
- Set the category: replace
{{CATEGORY}} with the correct value (e.g. social-media, email, devtools) - Write the task-oriented sections: replace
{{WHEN_TO_USE_HELP}}, {{CAPABILITIES_HELP}}, and {{USE_CASES_HELP}} with domain-specific guidance - Build resource tables: for each resource, create a command table with every action and its real flags (from
--help output) - Add Quick Reference + Output Format: include
--help commands and document the JSON envelope - Remove all placeholders: no
{{...}} or <!-- TODO --> should remain - Validate: run at least one command to confirm the skill's examples are accurate
See references/skill-generation.md for the full introspection workflow, format, quality checklist, and symlink instructions.
To also link skills for OpenClaw:
CODEBLOCK5
See references/openclaw.md for the one-prompt setup, ClawHub publishing, API key auto-detection, and custom --skills-path usage.
Also available on ClawHub: INLINECODE25
7. Publish (when user asks)
Before any publish target, run these pre-flight checks:
- 1. Verify
gh CLI is authenticated: run gh auth status. If not logged in, ask the user to run gh auth login first. Stop and wait. - Check if the CLI is already on GitHub: run
git remote get-url origin in the CLI directory.
- If no remote exists → the CLI is not on GitHub yet.
Automatically run the GitHub publish flow first (see below) before proceeding to npm or registry publish.
- If a remote exists → already on GitHub, continue.
To GitHub
Push the CLI to a public GitHub repo.
See references/publish-to-github.md for pre-flight checks, repo creation, and push workflow.
To npm
Requires the CLI to be on GitHub first (for repository field in package.json). If not on GitHub, run the GitHub publish flow above first.
Publish the CLI to the npm registry so users can npm i -g <name> or npx <name>.
See references/publish-to-npm.md for auth, package.json validation, build, verify, and publish workflow. Also see references/package-checklist.md for the field-by-field package.json reference.
To ClawHub
Publish the generated skill to ClawHub so OpenClaw users can discover and install it.
- 1. Auth: run
npx clawhub login. If not authenticated, ask the user to complete login first. Stop and wait. - Push the skill: run INLINECODE34
- After publish, users can install with:
CODEBLOCK6
See references/openclaw.md for the full OpenClaw setup workflow.
To Sundial Hub
Publish the generated skill to the Sundial Hub so any agent (Claude Code, Cursor, Codex, etc.) can install it.
- 1. Auth: run
npx sundial-hub auth status. If not authenticated, ask the user to run npx sundial-hub auth login first. Stop and wait. - Push the skill: run INLINECODE37
- After publish, users can install with:
CODEBLOCK7
To api2cli.dev registry
Requires the CLI to be on GitHub first. If not on GitHub, run the GitHub publish flow above first.
Register on api2cli.dev so others can install with npx api2cli install <name>.
See references/publish.md for the registry publish workflow.
Conventions
CODEBLOCK8
INLINECODE39 returns: INLINECODE40
Other flags: --format <text|json|csv|yaml>, --verbose, --no-color, INLINECODE44
Exit codes: 0 = success, 1 = API error, 2 = usage error
Tokens: ~/.config/tokens/<app>-cli.txt (chmod 600)
api2cli
将任意REST API转化为标准化、面向代理的命令行工具。
始终使用 npx api2cli 来运行命令。当以编程方式调用生成的CLI时，始终使用 --json 参数。
前置条件
bash
bun --version || curl -fsSL https://bun.sh/install | bash
工作流程
按顺序执行所有步骤——不要跳过任何一步。
1. 优先搜索注册表
在生成任何内容之前，先检查CLI是否已存在：
bash
npx api2cli search
如果注册表中已有你需要的CLI，直接安装而无需重新构建：
bash
npx api2cli install
关于 --type、--category 和 --json 等筛选条件，请参见 references/commands.md。
2. 发现API
查找API文档或OpenAPI规范。确定：基础URL、认证类型、认证头、所有资源和端点。
3. 创建脚手架
bash
npx api2cli create --base-url --auth-type bearer
关于所有标志和生成的内容，请参见 references/create.md。
4. 实现资源
为每个API资源创建 ~/.cli/-cli/src/resources/.ts。在 src/index.ts 中注册。
关于CRUD模板和库API，请参见 references/resource-patterns.md。
5. 构建、链接和测试
bash
npx api2cli bundle
npx api2cli link
-cli --help
-cli list --json
api2cli link 会自动将 ~/.local/bin 添加到PATH中。无需 export PATH。
6. 完善技能和README
此步骤为强制要求。 技能必须成为另一个代理的真实操作指南，而不仅仅是命令列表——不能有占位符，不能有TODO。
- 1. 内省CLI：运行 -cli --help，然后对每个资源和操作运行 --help 和 --help
- 更新描述：列出所有资源名称并添加领域特定的触发短语
- 设置类别：将 {{CATEGORY}} 替换为正确的值（例如 social-media、email、devtools）
- 编写面向任务的章节：将 {{WHENTOUSEHELP}}、{{CAPABILITIESHELP}} 和 {{USECASESHELP}} 替换为领域特定的指导
- 构建资源表格：为每个资源创建一个命令表格，包含每个操作及其实际标志（来自 --help 输出）
- 添加快速参考 + 输出格式：包含 --help 命令并记录JSON信封格式
- 移除所有占位符：不应保留任何 {{...}} 或
- 验证：至少运行一个命令以确认技能示例的准确性
关于完整的内省工作流程、格式、质量检查清单和符号链接说明，请参见 references/skill-generation.md。
要为OpenClaw链接技能：
bash
npx api2cli link --openclaw
关于一键设置、ClawHub发布、API密钥自动检测和自定义 --skills-path 用法，请参见 references/openclaw.md。
也可在ClawHub上获取：npx clawhub install api2cli
7. 发布（当用户要求时）
在任何发布目标之前，运行以下预检检查：
- 1. 验证 gh CLI已认证：运行 gh auth status。如果未登录，请让用户先运行 gh auth login。停止并等待。
- 检查CLI是否已在GitHub上：在CLI目录中运行 git remote get-url origin。
- 如果没有远程仓库 → CLI尚未在GitHub上。
先自动运行GitHub发布流程（见下文），然后再进行npm或注册表发布。
- 如果存在远程仓库 → 已在GitHub上，继续。
发布到GitHub
将CLI推送到公共GitHub仓库。
关于预检检查、仓库创建和推送工作流程，请参见 references/publish-to-github.md。
发布到npm
要求CLI首先在GitHub上（用于package.json中的 repository 字段）。如果不在GitHub上，先运行上述GitHub发布流程。
将CLI发布到npm注册表，以便用户可以使用 npm i -g 或 npx 。
关于认证、package.json验证、构建、验证和发布工作流程，请参见 references/publish-to-npm.md。关于package.json的逐字段参考，请参见 references/package-checklist.md。
发布到ClawHub
将生成的技能发布到ClawHub，以便OpenClaw用户可以发现并安装它。
- 1. 认证：运行 npx clawhub login。如果未认证，请让用户先完成登录。停止并等待。
- 推送技能：运行 npx clawhub publish /skills/-cli --slug -cli
- 发布后，用户可以通过以下方式安装：
bash
npx clawhub install
-cli
关于完整的OpenClaw设置工作流程，请参见 references/openclaw.md。
发布到Sundial Hub
将生成的技能发布到Sundial Hub，以便任何代理（Claude Code、Cursor、Codex等）都可以安装它。
- 1. 认证：运行 npx sundial-hub auth status。如果未认证，请让用户先运行 npx sundial-hub auth login。停止并等待。
- 推送技能：运行 npx sundial-hub push /skills/-cli --visibility public --categories coding
- 发布后，用户可以通过以下方式安装：
bash
npx sundial-hub add /-cli
发布到api2cli.dev注册表
要求CLI首先在GitHub上。如果不在GitHub上，先运行上述GitHub发布流程。
在api2cli.dev上注册，以便其他人可以使用 npx api2cli install 安装。
关于注册表发布工作流程，请参见 references/publish.md。
约定
-cli [flags]
-cli auth set|show|remove|test
--json 返回：{ ok: true, data: [...], meta: { total: 42 } }
其他标志：--format 、--verbose、--no-color、--no-header
退出码：0 = 成功，1 = API错误，2 = 使用错误
令牌：~/.config/tokens/-cli.txt（权限600）
