# 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)

The CLI is primarily a predictable, scriptable interface for AI coding agents and automation. Human users can use the Web app for document browsing and maintenance.

## Install And Run

After installing from npm, use the `apiskill` executable directly:

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

`apiskill run web`, CLI commands, and MCP all use `~/.apiskill/cache` by default. `--cwd` changes only the Web working directory and does not change the shared cache. For project isolation, set the same absolute `APISKILL_CACHE_DIR` for every Web, CLI, and MCP process:

```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
```

From the source project root:

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

You can also run the executable directly:

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

## Cache Settings

Web, CLI, and MCP share the saved default in `~/.apiskill/config.json`:

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

Changing the default never moves or deletes existing files. Future CLI and MCP processes use the new location immediately; restart Web or use Update Cache Location in version management to copy selected versions. `APISKILL_CACHE_DIR` has priority over the saved setting.

## Import Documents

Check whether a usable cache is available:

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

If no cache exists, `check` prints import examples.

```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
```

Use `--auth username:password` with `import` or `crawl` when the document endpoint requires basic auth.

## Create A Document From Scratch

When there is no upstream OpenAPI document yet, create a blank local document version:

```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
```

The created document is saved as the latest cached version. Read `meta.versionId` from the JSON response and pass it explicitly to later writes. `api create` defaults to the latest version when `--version` is omitted, but explicit version IDs keep agent workflows deterministic.

## Query Versions And APIs

```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` behaves like the MCP `apiskill_query_api` tool: exact single matches return one API config, while multiple matches return candidates.

`api query` defaults to JSON and does not accept `--json`. Use `--format cli` to get a normalized config that can be edited and sent back to `api edit`.

## Start A MOCK Server

After an API document is cached, start a local MOCK API server:

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

The MOCK server generates local API routes from the current OpenAPI paths, HTTP methods, and response schemas. Calling a matching API returns random JSON data. If no API document has been imported, crawled, or created yet, the command prints a friendly setup prompt.

## Create, Edit, And Delete Manual APIs

```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
```

The method and path passed to `api edit` identify the original operation. The replacement file may contain a different method or path. Quote paths that contain `{id}` or other shell-sensitive characters.

When adding several APIs, reuse the exact same version ID for every command. Agents should run writes sequentially for compatibility with older releases and finish with `apiskill api list --version "$APISKILL_VERSION_ID" --json` to verify every expected method/path. The current CLI also uses a cross-process cache write lock, so accidentally parallel commands are serialized instead of overwriting one another.

An OpenAPI operation is unique by method/path. Creating the same pair again replaces that operation. `meta.paths` is the number of distinct paths, so use `api list` when validating the total operation count.

CLI config can be JSON or YAML with root key `api`, `config`, or `operation`.

Minimal JSON example:

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