# API Skill CLI

[English](https://unpkg.com/apiskill@latest/docs/cli.md) / [中文](https://unpkg.com/apiskill@latest/docs/cli.zh.md) / [한국어](https://unpkg.com/apiskill@latest/docs/cli.ko.md) / [日本語](https://unpkg.com/apiskill@latest/docs/cli.ja.md)

CLI 主要为 AI 编码 Agent 和自动化任务提供稳定、可脚本化的接口。需要人工浏览和维护文档时，建议使用 Web 端。

## 安装和运行

从 npm 安装后可以直接使用 `apiskill`：

```bash
npm install -g apiskill
apiskill --help
apiskill run web
```

`apiskill run web`、其他 CLI 命令和 MCP 默认统一使用 `~/.apiskill/cache`。`--cwd` 只改变 Web 工作目录，不会改变共享缓存。需要按项目隔离时，必须为 Web、CLI 和 MCP 设置相同的绝对路径 `APISKILL_CACHE_DIR`：

```bash
apiskill run web --port 8890
APISKILL_CACHE_DIR=/path/to/project/.apiskill-cache apiskill run web --cwd /path/to/project
APISKILL_CACHE_DIR=/path/to/project/.apiskill-cache apiskill check --json
```

在源码项目根目录运行：

```bash
npm install
npm run cli -- --help
```

也可以直接运行：

```bash
node scripts/apiskill-cli.mjs --help
```

## 缓存设置

Web、CLI 和 MCP 共用保存在 `~/.apiskill/config.json` 中的默认缓存地址：

```bash
apiskill cache show
apiskill cache show --json
apiskill cache set /absolute/path/to/apiskill-cache
apiskill cache reset
```

修改默认地址不会移动或删除已有缓存文件。后续 CLI、MCP 进程会直接使用新地址，Web 需要重启；也可以在 Web 版本管理中选择“更新缓存地址”，将需要的版本复制到新目录。`APISKILL_CACHE_DIR` 环境变量优先于保存的默认设置。

## 导入文档

先检查当前是否有可用缓存：

```bash
apiskill check
apiskill check --json
```

如果没有可用缓存，`check` 会输出导入文档的示例。

```bash
apiskill import https://example.com/openapi.json
apiskill crawl https://example.com/swagger
apiskill import-file ./openapi.yaml
apiskill import-curl --file ./request.curl
```

如果文档地址需要 basic auth，`import` 和 `crawl` 可以加 `--auth username:password`。

## 从零创建文档

如果还没有上游 OpenAPI 文档，可以先创建一份本地空白文档版本：

```bash
apiskill document create --title "My API" --doc-version 1.0.0
apiskill document create --title "My API" --doc-version 1.0.0 --description "Internal service contract" --json
```

创建后的文档会保存为最新缓存版本。从 JSON 结果读取 `meta.versionId`，后续写操作都显式传入这个值。`api create` 省略 `--version` 时会默认写入最新版本，但显式版本 ID 能让 Agent 的操作目标保持确定。

## 查询版本和接口

```bash
apiskill versions
apiskill versions --json
apiskill query /admin/api/v1/user/list --method GET
apiskill query user --method POST --limit 10
apiskill api list --query user --method post
apiskill api query GET /api/v1/user --format cli
```

`query` 和 MCP 的 `apiskill_query_api` 行为一致：精确单条匹配时返回一个接口配置，多条匹配时返回候选列表。

`api query` 默认输出 JSON，不支持 `--json`。需要可修改并传给 `api edit` 的标准配置时使用 `--format cli`。

## 启动 MOCK 服务

已有 API 文档缓存后，可以启动本地 MOCK API 服务：

```bash
apiskill mock
apiskill mock --port 4010
apiskill mock --version <versionId>
```

MOCK 服务会根据当前 OpenAPI 文档里的接口路径、HTTP 方法和响应 schema 自动生成本地 API。访问对应接口时会返回随机 JSON 数据；如果还没有导入、爬取或创建 API 文档，会提示先准备文档数据。

## 创建、编辑、删除手动接口

```bash
APISKILL_VERSION_ID="value-from-meta.versionId"
apiskill api create --version "$APISKILL_VERSION_ID" --file ./api-config.yaml --json
apiskill api edit GET /api/v1/user --version "$APISKILL_VERSION_ID" --file ./api-config.json --json
apiskill api delete GET /api/v1/user --version "$APISKILL_VERSION_ID" --json
```

`api edit` 后面的 method 和 path 用于定位旧接口，替换文件可以包含不同的 method 或 path。路径中包含 `{id}` 等 shell 特殊字符时应加引号。

批量新增多个接口时，每条命令必须复用同一个版本 ID。为了兼容旧版本，Agent 应串行执行写命令，并在结束后运行 `apiskill api list --version "$APISKILL_VERSION_ID" --json`，核对所有预期的 method/path。当前 CLI 也使用跨进程缓存写锁，意外并行的命令会被串行处理，不再互相覆盖。

OpenAPI 使用 method/path 组合唯一标识接口；再次创建相同组合会替换原接口。`meta.paths` 是不同路径的数量，校验接口操作总数时应以 `api list` 为准。

CLI 配置可以是 JSON 或 YAML，根字段支持 `api`、`config` 或 `operation`。

最小 JSON 示例：

```json
{
  "api": {
    "method": "post",
    "path": "/api/v1/example",
    "summary": "创建示例",
    "responses": [
      {
        "status": "200",
        "description": "Success"
      }
    ]
  }
}
```