api2cli

api2cli

将任意 REST API 转换为标准化、可供 Agent 使用的 CLI。

始终使用 npx api2cli 运行命令。以编程方式调用生成的 CLI 时，始终使用 --json。

前提条件

bun --version || curl -fsSL https://bun.sh/install | bash

工作流

请按顺序完成所有步骤，不要跳过任何步骤。

1. 先搜索注册表

生成 CLI 前，先检查是否已有可用的 CLI：

npx api2cli search <query>

如果注册表中已有你需要的 CLI，请直接安装，不要重新构建：

npx api2cli install <name>

有关 --type、--category 和 --json 等筛选条件，请参阅 references/commands.md。

2. 发现 API

查找 API 文档或 OpenAPI 规范。确认：基础 URL、身份验证类型、身份验证标头，以及所有资源和端点。

3. 创建脚手架

npx api2cli create <app> --base-url <url> --auth-type bearer

有关所有标志和生成内容，请参阅 references/create.md。

4. 实现资源

为每个 API 资源创建 ~/.cli/<app>-cli/src/resources/<resource>.ts。在 src/index.ts 中注册。

有关 CRUD 模板和库 API，请参阅 references/resource-patterns.md。

5. 构建、链接并测试

npx api2cli bundle <app>
npx api2cli link <app>
<app>-cli --help
<app>-cli <resource> list --json

api2cli link 会自动将 ~/.local/bin 添加到 PATH。无需 export PATH。

它还会通过以下两个步骤配置 skill：

1. 规范路径：~/.agents/skills/<app>-cli → ~/.cli/<app>-cli/skills/<app>-cli
2. 各 Agent 路径：每个现有的 Agent 文件夹（~/.claude/skills、~/.cursor/skills、~/.openclaw/workspace/skills）都会将 <app>-cli 符号链接到规范路径。

可通过标志覆盖任一端：

# Custom canonical folder
npx api2cli link <app> -f ~/.agents/skills

# Custom destinations (replaces auto-detected ones)
npx api2cli link <app> -d ~/.claude/skills ~/.cursor/skills

# Combine both
npx api2cli link <app> -f ~/.agents/skills -d ~/.claude/skills

6. 完善 skill 和 README

此步骤为必做项。 该 skill 必须成为另一位 Agent 可用的实际操作指南，而不只是命令列表——不得包含占位符或 TODO。

1. 检查 CLI：运行 <app>-cli --help，然后对每个资源和操作运行 <resource> --help 和 <resource> <action> --help
2. 更新描述：列出所有资源名称，并添加特定领域的触发短语
3. 设置类别：将 {{CATEGORY}} 替换为正确的值（例如 social-media、email、devtools）
4. 撰写以任务为导向的章节：将 {{WHEN_TO_USE_HELP}}、{{CAPABILITIES_HELP}} 和 {{USE_CASES_HELP}} 替换为特定领域的指导内容
5. 构建资源表格：为每个资源创建命令表格，列出所有操作及其实际标志（来自 --help 输出）
6. 添加 Quick Reference + Output Format：包含 --help 命令，并说明 JSON 封装格式
7. 移除所有占位符：不得残留任何 {{...}} 或 ``
8. 验证：至少运行一条命令，确认 skill 中的示例准确无误

有关完整的检查流程、格式、质量检查清单和符号链接说明，请参阅 references/skill-generation.md。

如果存在 ~/.openclaw/，系统会自动检测 OpenClaw。若要强制包含它（或其他任意文件夹），请使用：

npx api2cli link <app> -d ~/.openclaw/workspace/skills

有关单提示词设置、ClawHub 发布和 API 密钥自动检测，请参阅 references/openclaw.md。

也可从 ClawHub 安装：npx clawhub install api2cli

7. 发布（用户提出要求时）

发布到任何目标之前，先执行以下发布前检查：

1. 确认 gh CLI 已完成身份验证：运行 gh auth status。如果尚未登录，请让用户先运行 gh auth login。停止并等待。
2. 检查 CLI 是否已在 GitHub 上：在 CLI 目录中运行 git remote get-url origin。
   • 如果不存在远程仓库 → CLI 尚未发布到 GitHub。继续发布到 npm 或注册表之前，自动先执行 GitHub 发布流程（见下文）。
   • 如果存在远程仓库 → 已发布到 GitHub，继续操作。

发布到 GitHub

将 CLI 推送到公开的 GitHub 仓库。

有关发布前检查、创建仓库和推送工作流，请参阅 references/publish-to-github.md。

发布到 npm

要求先将 CLI 发布到 GitHub（以填写 package.json 中的 repository 字段）。如果尚未发布到 GitHub，请先按照上文的 GitHub 发布流程操作。

将 CLI 发布到 npm 注册表，方便用户使用 npm i -g <name> 或 npx <name>。

有关身份验证、package.json 验证、构建、验证和发布工作流，请参阅 references/publish-to-npm.md。有关 package.json 各字段的参考说明，请参阅 references/package-checklist.md。

发布到 ClawHub

将生成的技能发布到 ClawHub，方便 OpenClaw 用户发现并安装。

1. 身份验证：运行 npx clawhub login。如果尚未通过身份验证，请让用户先完成登录。停止并等待。
2. 推送技能：运行 npx clawhub publish <cli-dir>/skills/<app>-cli --slug <app>-cli
3. 发布后，用户可以通过以下方式安装：

   npx clawhub install <app>-cli
   

有关完整的 OpenClaw 设置工作流，请参阅 references/openclaw.md。

发布到 Sundial Hub

将生成的技能发布到 Sundial Hub，方便任何 Agent（Claude Code、Cursor、Codex 等）安装。

1. 身份验证：运行 npx sundial-hub auth status。如果尚未通过身份验证，请让用户先运行 npx sundial-hub auth login。停止并等待。
2. 推送技能：运行 npx sundial-hub push <cli-dir>/skills/<app>-cli --visibility public --categories coding
3. 发布后，用户可以通过以下方式安装：

   npx sundial-hub add <sundial-username>/<app>-cli
   

发布到 api2cli.dev 注册表

要求先将 CLI 发布到 GitHub。如果尚未发布到 GitHub，请先按照上文的 GitHub 发布流程操作。

在 api2cli.dev 上注册，方便其他人使用 npx api2cli install <name> 安装。

有关注册表发布工作流，请参阅 references/publish.md。

约定

<app>-cli <resource> <action> [flags]
<app>-cli auth set|show|remove|test

--json 返回：{ "ok": true, "data": [...], "meta": { "total": 42 } }

其他标志：--format <text|json|csv|yaml>、--verbose、--no-color、--no-header

退出代码：0 = 成功，1 = API 错误，2 = 用法错误

令牌：~/.config/tokens/<app>-cli.txt（chmod 600）