api2cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

api2cli

Turn any REST API into a standardized, agent-ready CLI.

Always use

npx api2cli

to run commands (no install needed).

将任意REST API转换为标准化的、支持Agent的CLI。

始终使用

npx api2cli

运行命令（无需安装）。

Prerequisites

前置条件

Before anything else, check if

bun

is installed. It is required to build the generated CLIs.

bash

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

Always run this check first - do not skip it.

开始操作前，请先检查是否安装了

bun

。构建生成的CLI需要用到它。

bash

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

请务必先执行此项检查，不要跳过。

Workflow

工作流

Step 1: Discover the API

步骤1：探索API

Before creating anything, gather API information:

Find the API docs URL or OpenAPI spec (use web search if needed)
Identify: base URL, auth type (bearer/api-key/basic/custom), auth header name
List all resources and their endpoints (GET/POST/PATCH/DELETE)
Note any pagination, rate limiting, or special headers

开始创建前，先收集API相关信息：

找到API文档地址或OpenAPI规范（必要时可使用网页搜索）
确认：基础URL、认证类型（bearer/api-key/basic/custom）、认证头名称
列出所有资源及其对应的端点（GET/POST/PATCH/DELETE）
记录所有分页、速率限制或特殊头信息

Step 2: Create the scaffold

步骤2：创建脚手架

bash

npx api2cli create <app> \
  --base-url https://api.example.com \
  --auth-type bearer \
  --auth-header Authorization

See references/commands.md for all

api2cli

commands and flags.

This creates

~/.cli/<app>-cli/

with: HTTP client (retry/backoff), auth module, multi-format output, example resource.

bash

npx api2cli create <app> \
  --base-url https://api.example.com \
  --auth-type bearer \
  --auth-header Authorization

查看references/commands.md了解所有

api2cli

命令和参数。

该命令会创建

~/.cli/<app>-cli/

目录，包含：HTTP客户端（支持重试/退避）、认证模块、多格式输出、示例资源。

Step 3: Implement resources

步骤3：实现资源

For each API resource, create

~/.cli/<app>-cli/src/resources/<resource>.ts

See references/resource-patterns.md for the full CRUD template and conventions.

Key rules:

One file per resource (drafts.ts, links.ts, accounts.ts)
CRUD commands: list, get, create, update, delete
Every command has
```
--json
```
flag and help examples
Use
```
client.get/post/patch/delete()
```
for HTTP
Use
```
output()
```
for formatted response
Use
```
handleError()
```
for errors

~/.cli/<app>-cli/src/index.ts

typescript

import { draftsResource } from "./resources/drafts.js";
program.addCommand(draftsResource);

针对每个API资源，创建

~/.cli/<app>-cli/src/resources/<resource>.ts

文件。

查看references/resource-patterns.md获取完整的CRUD模板和开发规范。

核心规则：

每个资源对应一个文件（如drafts.ts、links.ts、accounts.ts）
CRUD命令：list、get、create、update、delete
每个命令都支持
```
--json
```
参数和帮助示例
使用
```
client.get/post/patch/delete()
```
发起HTTP请求
使用
```
output()
```
处理格式化响应
使用
```
handleError()
```
处理错误

在

~/.cli/<app>-cli/src/index.ts

中注册每个资源：

typescript

import { draftsResource } from "./resources/drafts.js";
program.addCommand(draftsResource);

Step 4: Build, link, and test

步骤4：构建、链接与测试

bash

npx api2cli bundle <app>
npx api2cli link <app>
export PATH="$HOME/.local/bin:$PATH"
<app>-cli --help
<app>-cli <resource> list --json

api2cli link

prints the export command to run. Always run

export PATH="$HOME/.local/bin:$PATH"

right after linking so

<app>-cli

works directly. Do NOT use

source ~/.zshrc

bash

npx api2cli bundle <app>
npx api2cli link <app>
export PATH="$HOME/.local/bin:$PATH"
<app>-cli --help
<app>-cli <resource> list --json

api2cli link

会输出需要执行的export命令。链接完成后请务必立即执行

export PATH="$HOME/.local/bin:$PATH"

，这样才能直接使用

<app>-cli

命令。不要使用

source ~/.zshrc

。

Step 5: Update the AgentSkill and README

步骤5：更新AgentSkill和README

The scaffold already includes

skills/<app>-cli/SKILL.md

and

README.md

with placeholder sections.

After implementing resources, update these files:

Edit

~/.cli/<app>-cli/skills/<app>-cli/SKILL.md

- fill in

{{RESOURCES_LIST}}

and

{{RESOURCES_HELP}}

with actual resource names and commands

Edit

~/.cli/<app>-cli/README.md

- fill in

{{RESOURCES_HELP}}

and

{{GITHUB_REPO}}

See references/skill-generation.md for the template and rules.

The skill lives inside the repo so when pushed to GitHub, anyone can install it:

bash

npx skills add <github-user>/<app>-cli

脚手架默认已包含带占位符的

skills/<app>-cli/SKILL.md

和

README.md

文件。

实现资源后，请更新这些文件：

编辑

~/.cli/<app>-cli/skills/<app>-cli/SKILL.md

- 用实际的资源名称和命令填充

{{RESOURCES_LIST}}

和

{{RESOURCES_HELP}}

占位符

编辑

~/.cli/<app>-cli/README.md

- 填充

{{RESOURCES_HELP}}

和

{{GITHUB_REPO}}

占位符

查看references/skill-generation.md获取模板和规则说明。

Skill文件存放在仓库中，推送到GitHub后，任何人都可以安装使用：

bash

npx skills add <github-user>/<app>-cli

Generated CLI Conventions

生成CLI的规范

All generated CLIs follow these exact patterns:

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

Always use
--json
when calling CLI commands programmatically. The table output is for humans only - it wraps and is unreadable by AI.

--json

returns structured data:

json

{ "ok": true, "data": [...], "meta": { "total": 42 } }

Other flags:

--format <text|json|csv|yaml>

--verbose

--no-color

--no-header

Exit codes: 0 = success, 1 = API error, 2 = usage error

Tokens:

~/.config/tokens/<app>-cli.txt

(chmod 600)

所有生成的CLI都严格遵循以下模式：

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

以编程方式调用CLI命令时请始终使用
--json
参数。表格输出仅面向人类阅读，会自动换行，AI无法解析。

--json

会返回结构化数据：

json

{ "ok": true, "data": [...], "meta": { "total": 42 } }

其他参数：

--format <text|json|csv|yaml>

、

--verbose

、

--no-color

、

--no-header

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

Token存储路径：

~/.config/tokens/<app>-cli.txt

（权限为chmod 600）