LinkAI CLI

# Apps / Models / Account / Credits / Auth

## Apps — scope `app:read`

| Command | Notes |
|---|---|
| `linkai app list [--key <kw>] [--page <n>] [--page-size <n>] [--json]` | search + paginate |
| `linkai app detail <app_code> [--json]` | full info for one app |

## Models — uses default auth

```
linkai model list [--type LLM|EMBEDDING] [--supplier <name>] [--json]
```

## Account — scope `user:read`

```
linkai account info [--json]
```

Returns `{ name, credits, plan_version, ... }`.

## Credits

| Command | Scope | Agent notes |
|---|---|---|
| `linkai account credits [--json]` | `score:read` | available credit packages |
| `linkai account recharge --product <id> --pay wechat\|alipay --agent [--json]` | `score:buy` | **always pass `--agent`** — returns `qr_file` (a local PNG path), not an ASCII QR |
| `linkai account order <order_no> [--json]` | `score:read` | poll order status by order number |
| `linkai account orders [--page <n>] [--page-size <n>] [--json]` | `score:read` | purchase history |

`recharge --agent` writes the payment QR to a local PNG and returns its path as
`qr_file` (plus `code_url`, the raw pay URL). Show the image to the user; once
they pay, poll `account order <order_no>` until `status` becomes `PAID`.

## Auth — agent rules

| Command | Agent action |
|---|---|
| `linkai auth status [--json]` | run before the first call; expect `valid` |
| `linkai auth login` | **never run from agent** — needs a browser; tell the user to run it themselves with the right `--scope` |
| `linkai auth logout` | only on explicit user request |

## Default scopes granted at login

```
app:read chat:send user:read workflow:read workflow:run knowledge:read db:read image:gen video:gen audio:gen plugin:read plugin:run score:read score:buy
```

Sensitive scopes **not** in defaults — require explicit user re-login: `db:write`, `knowledge:create`, `knowledge:delete`.

# Auth (agent flow)

Login uses OAuth Device Flow: the user opens a URL and authorizes in a browser. After you send the link, do NOT stop and wait for the user to reply in chat — go straight to your next tool call and poll, repeating until authorization completes.

## Check status first

```bash
linkai auth status --json
```

`status` is `valid`, `needs_refresh`, or `expired` (or the user is not logged in). Auto-refresh is handled by the CLI on `needs_refresh`, so a login is only needed on `expired` / not logged in.

## Get the authorization URL

```bash
linkai auth login --no-wait --json
```

Returns immediately:

```json
{
  "verification_url": "https://...",
  "device_code": "xxx",
  "next_action": { "command": "...", "instruction": "..." }
}
```

Tell the user to open `verification_url` and authorize. Then **make your next tool call the poll below** — do NOT stop to wait for the user to say "done".

## Poll until complete (next tool call, keep going)

Run `next_action.command` (a bounded poll that blocks up to 60s):

```bash
linkai auth login --device-code <code> --wait 60 --json
```

It returns one of:

| `event` | Meaning | Action |
|---|---|---|
| `authorization_pending` | User hasn't finished yet | **Re-run the same command as your next tool call** (loop) |
| `authorization_complete` | Logged in | Proceed to the user's original request |
| `authorization_failed` | Code expired or denied | Restart from "Get the authorization URL" |

Keep re-running the poll on `pending` (each call blocks ~60s, so looping is not busy-spinning) until you get `complete` or `failed`. The device code expires after ~5 minutes; if the user is away that long, it is fine to stop and let them re-trigger.

## Requesting extra scopes

Default login scopes exclude `db:write`, `knowledge:create`, `knowledge:delete`. To grant them, add `--scope`:

```bash
linkai auth login --scope "<existing scopes> <missing scope>" --no-wait --json
```

Then run the same two-step flow. Only do this when a command has failed with a scope error (exit 3) and the user has agreed.

# chat

Talk to a LinkAI application, or call an LLM directly. Required scope: `chat:send` (in default scopes).

## Command

```
linkai chat "<message>" [--app <app_code>] [--model <model_code>] [--session <id>] [--no-stream] [--json] [--dry-run]
```

## Required

- `<message>` — positional, the user's message. Validate it has no control chars before passing.

## App vs model (both optional)

- `--app <app_code>` — chat with a configured application. Get the code from `linkai app list --json`.
- `--model <model_code>` — call an LLM directly. Get the code from `linkai model list --json` (use an entry whose type is `LLM`).
- Both given → `--model` overrides the app's configured model.
- Neither given → the platform default model is used.

## Agent recommendation

Always pass `--no-stream --json` for a single, parseable JSON reply (streaming is only for humans at a terminal).

## Multi-turn

Pass the same `--session <id>` across calls; any non-empty string works. Server keeps context keyed by session id.

## JSON output

```json
{
  "session_id": "...",
  "answer": "...",
  "usage": { "...": "..." }
}
```

## Resolving the app code

```
linkai app list --json --key "<keyword>"
```

Returns `[{ code, name, ... }]`. Match by `name`, pass `code` as `--app`.

# Image / Video / Audio generation

All three are in default scopes.

## Image — scope `image:gen`

```
linkai image gen "<prompt>" [--model <m>] [--size <s>] [--aspect-ratio <r>] [--quality <q>] [--image <url>]... [--json] [--dry-run]
```

- **Do not hardcode model names.** Omit `--model` to use the account default, or discover available image models with `linkai model list --type IMAGE` and pass a returned code to `--model`.
- `--size` / `--aspect-ratio` / `--quality` are model-specific (e.g. `2K`, `16:9`, `hd`); leave unset to use the model default. Unsupported fields are ignored by the server, not rejected.
- Image-to-image: pass one or more reference image URLs via `--image` (repeatable). Support is model-dependent.

JSON output: `{ "url": "...", ... }`

## Video — scope `video:gen`

```
linkai video gen "<prompt>" [--model <m>] [--duration <sec>] [--aspect-ratio <r>] [--size <s>] [--mode std|pro] [--image <url>]... [--image-mode <m>] [--json] [--dry-run]
```

- **Do not hardcode model names.** Omit `--model` to use the account default, or discover available video models with `linkai model list --type VIDEO` and pass a returned code to `--model`.
- All sizing options (`--duration`, `--aspect-ratio`, `--size`, `--mode`) are model-specific; leave unset to use the model default. `--mode` only applies to kling models.
- Image-to-video: pass reference image URL(s) via `--image` (repeatable); `--image-mode` chooses `reference` or `first_last_frame` (model-dependent).
- The CLI polls until the task completes (typically 30s–3min). **Do not add your own polling.** Just wait for the command to return.

JSON output: `{ "video_url": "...", "task_id": "...", ... }`

## Audio TTS — scope `audio:gen`

```
linkai audio speech "<text>" [--model tts-1|tts-1-hd] [--voice <id>] [--output <path.mp3>] [--json] [--dry-run]
```

- Without `--output`: returns `{ "url": "..." }` (CDN URL, time-limited).
- With `--output <path>`: downloads to disk; the local path is reported.
- `--model` defaults to `tts-1`; use `tts-1-hd` for higher quality.

# database

## Scopes

- `db:read` — `list` / `tables` / `describe` / `SELECT` via `exec` (in default scopes)
- `db:write` — `create`, and `INSERT/UPDATE/DELETE` via `exec` (**not** in default scopes; `exec` is classified server-side from the SQL)

## Commands

| Command | Purpose |
|---|---|
| `linkai database list [--page <n>] [--page-size <n>] [--json]` | list databases |
| `linkai database create --name <name> [--description <text>] [--json] [--dry-run]` | create a builtin (platform-hosted) database |
| `linkai database create-table <db_code> --name <table> --field name:type[:comment] ... [--json] [--dry-run]` | create a table in a builtin database |
| `linkai database tables <db_code> [--json]` | list tables in a database |
| `linkai database describe <db_code> <table> [--json]` | columns + types |
| `linkai database exec <db_code> "<sql>" [--json] [--dry-run]` | run SQL |

`create` / `create-table` only work on **builtin** (platform-hosted) databases — no external connection. Both need `db:write` (not in defaults); on scope failure see [errors.md](errors.md).

Full builtin flow from the CLI: `create` a database → `create-table` to define columns → `exec` INSERT/SELECT to read/write rows. (Table structure cannot be created via `exec` — `CREATE TABLE` and other DDL are blocked; use `create-table`.)

`create-table` column types: `text`, `text1024`, `longtext`, `number`, `decimal`, `datetime`. An auto-increment `id` primary key is added automatically. Define columns with repeated `--field name:type[:comment]`, or (agent-preferred) `--fields-json '[{"name":"...","type":"..."}]'`. Table name must not contain spaces.

## Safety rules — agent must follow

- **Default to `SELECT`.** Only run mutating SQL when the user explicitly asks.
- **Always include `LIMIT`** on exploratory selects (e.g. `LIMIT 100`).
- DDL (`DROP`, `TRUNCATE`, `ALTER`) is blocked client-side. Do not attempt; surface the rejection to the user.
- Mutating SQL needs `db:write` (not in defaults). On scope failure see [errors.md](errors.md).

## Discovery flow

1. `linkai database list --json` → pick `code`.
2. `linkai database tables <code> --json` → pick table.
3. `linkai database describe <code> <table> --json` → understand columns.
4. `linkai database exec <code> "SELECT ... LIMIT N" --json`.

# Errors and recovery

## Exit codes

| Code | Meaning | Agent action |
|---|---|---|
| 0 | success | continue |
| 1 | general | report to user |
| 2 | validation (bad input/flags) | inspect args, fix and retry once |
| 3 | auth (not logged in / expired / scope denied) | see below — don't retry |
| 4 | network (5xx, connection) | the CLI already retried internally; report |

## Scope errors (exit 3, message mentions scope)

The default-login scopes do **not** include: `db:write`, `knowledge:create`, `knowledge:delete`.

When a command fails because of a missing scope:

1. **Stop. Do not retry the same command.**
2. `linkai auth status --json` to read the current `scope` field.
3. Tell the user verbatim:

   > This action needs scope `<missing>`, which isn't in your current grant. Please run:
   > `linkai auth login --scope "<existing scopes> <missing>"`
   > then re-run the original request.

4. Only run `auth login` after the user agrees — it needs them to authorize in a browser. Use the two-step flow in [auth.md](auth.md).

## Not logged in / expired

`auth status` returns `valid` / `needs_refresh` / `expired` (or "not logged in"). On `expired` or absent token, run the two-step login in [auth.md](auth.md). Auto-refresh is handled by the CLI when status is `needs_refresh`, so you usually won't see that case.

## Resource not found

If a command fails with "not found" on `app_code` / `kb_code` / `db_code` / `plugin_code`:

- List the resource (`linkai app list --json`, etc.) and either pick by name or surface the list to the user.
- Don't guess codes from names.

## Dangerous SQL blocked

`database exec` rejects `DROP`, `TRUNCATE`, `ALTER` client-side. Surface the rejection to the user; don't attempt workarounds.

## Non-JSON gateway errors

Occasionally the upstream returns HTML (e.g. CDN/gateway maintenance page). The CLI detects this and exits with code 4 and a body snippet. Treat as a transient network issue and report.

# Install & configure the LinkAI CLI

This guide is for an agent that needs to get the `linkai` binary working from
scratch. Try the methods top to bottom — stop at the first one that succeeds.
Verify with `linkai --version` after each attempt.

All commands are non-interactive; none of them wait for user input.

## 1. Install the CLI

### Method A — npm (best when Node.js is available)

npm's global bin directory is already on PATH, so nothing else is needed:

```bash
npm i -g linkai-cli
```

### Method B — install script (macOS / Linux, no Node.js required)

`LINKAI_NO_SKILL=1` installs the binary only (skip if you also want the script
to drop the skill into detected agent homes):

```bash
curl -fsSL https://cdn.link-ai.tech/cli/install.sh | LINKAI_NO_SKILL=1 sh
```

Windows — run in **PowerShell** (not `cmd.exe`):

```powershell
$env:LINKAI_NO_SKILL='1'; irm https://cdn.link-ai.tech/cli/install.ps1 | iex
```

### Method C — manual download (when npm and the scripts both fail)

Releases are versioned archives, not bare binaries — download, extract, then put
the binary on PATH.

1. **Find the latest version.** `latest.txt` holds a bare version like `0.1.0`:

   ```bash
   curl -fsSL https://cdn.link-ai.tech/cli/latest.txt
   ```

2. **Pick your platform.** Archive name pattern (`<os>` = `darwin`|`linux`|`windows`,
   `<arch>` = `amd64`|`arm64`):

   - macOS / Linux: `linkai-cli_<version>_<os>_<arch>.tar.gz`
   - Windows: `linkai-cli_<version>_windows_<arch>.zip`

3. **Download** from CDN (primary) or GitHub Releases (fallback):

   - CDN: `https://cdn.link-ai.tech/cli/<version>/<archive>`
   - GitHub: `https://github.com/MinimalFuture/linkai-cli/releases/download/v<version>/<archive>`

   Example (macOS arm64, version 0.1.0):

   ```bash
   V=$(curl -fsSL https://cdn.link-ai.tech/cli/latest.txt)
   curl -fsSL -o linkai.tar.gz \
     "https://cdn.link-ai.tech/cli/$V/linkai-cli_${V}_darwin_arm64.tar.gz"
   ```

4. **Extract and install onto PATH.**

   macOS / Linux:

   ```bash
   tar -xzf linkai.tar.gz linkai
   install -m 0755 linkai /usr/local/bin/linkai   # or: mv linkai ~/.local/bin/
   ```

   Windows (PowerShell) — extract, then add the folder to PATH:

   ```powershell
   Expand-Archive linkai.zip -DestinationPath $HOME\linkai-cli
   $env:Path += ";$HOME\linkai-cli"   # session only
   # Persist: [Environment]::SetEnvironmentVariable('Path', "$env:Path", 'User')
   ```

   If `~/.local/bin` (or the Windows folder) is not already on PATH, add it, then
   open a new shell so `linkai` resolves.

## 2. Install the agent skill

Download the skill archive and install it into your own skills directory (e.g.
`~/.claude/skills`, `~/.cursor/skills`, `~/cow/skills`), so this guide and the per-command
references stay available in later sessions:

```
https://cdn.link-ai.tech/cli/linkai-cli-skill.zip
```

## 3. Use it (in brief)

```bash
linkai --version          # confirm the install
linkai auth status --json # check login; if not valid, log in
```

## 4. Update an existing install

`linkai update` upgrades in place (auto-detects npm / Homebrew / go / script).

```bash
linkai update --check --json   # report only: current_version, latest_version, update_available
linkai update --json           # perform the upgrade
```

A stale CLI is the usual cause of `unknown flag` / missing commands — if you see
an "update available" notice on stderr, run `linkai update`.

Login needs a browser authorization step. For the full usage guide — login flow,
per-command flags, JSON output fields — read `linkai-cli/SKILL.md` from the skill
archive you installed in step 2.

# knowledge

| Command | Scope | In default scopes? |
|---|---|---|
| `linkai knowledge list [--json]` | `knowledge:read` | yes |
| `linkai knowledge files <kb_code> [--name <kw>] [--page <n>] [--page-size <n>] [--json]` | `knowledge:read` | yes |
| `linkai knowledge search <kb_code> "<query>" [--k <n>] [--json] [--dry-run]` | `knowledge:read` | yes |
| `linkai knowledge create --name <name> [--desc <txt>] [--json] [--dry-run]` | `knowledge:create` | **no** |
| `linkai knowledge update <kb_code> [--name <name>] [--desc <txt>] [--json] [--dry-run]` | `knowledge:update` | **no** |
| `linkai knowledge add <kb_code> (--text <txt> \| --question <q> --answer <a>) [--file-id <id>] [--json] [--dry-run]` | `knowledge:create` | **no** |
| `linkai knowledge import <kb_code> --file <path> [--type doc\|qa\|table] [--json] [--dry-run]` | `knowledge:create` | **no** |
| `linkai knowledge file delete <kb_code> --file-id <id> --force [--dry-run]` | `knowledge:delete` | **no** |
| `linkai knowledge data delete <kb_code> --file-id <id> --id <data_id> --force [--dry-run]` | `knowledge:delete` | **no** |
| `linkai knowledge delete <kb_code> --force [--dry-run]` | `knowledge:delete` | **no** |

## Agent rules

- **Always use `--force` on delete** — never run interactively.
- `search --k` defaults to 5; cap at ~20.
- `add`: provide either `--text` (raw chunk) or `--question` + `--answer` (QA). `--file-id` is optional — omit it to auto-create a file; the returned `file_id` can be reused on subsequent `add` calls to append to the same file.
- `import`: upload a whole local file (same as the platform's file import). `--type doc` (default) for unstructured docs (pdf/txt/word/md/...), `--type qa` for a two-column question/answer csv/excel, `--type table` for multi-column tabular excel/csv. Use `import` for files; use `add` for a single text chunk or QA pair typed inline. Embedding is **async** — the command returns once accepted; poll `knowledge files <kb_code>` to confirm it appears.
- **Deleting** — three levels:
  - `file delete --file-id <id>` removes a **whole file** and all its entries. Get `file-id` from `knowledge files <kb_code>` (the `fileId` field). This is what you want to drop one uploaded/imported file.
  - `data delete --file-id <id> --id <data_id>` removes a **single entry** (chunk/QA) inside a file — only use when you truly need to drop one entry.
  - `knowledge delete <kb_code>` removes the **whole base**.
- `create` / `update` / `add` / `delete` need sensitive scopes; on scope error see [errors.md](errors.md) — do not retry, ask the user to re-login with the missing scope.

## Resolving `kb_code`

```
linkai knowledge list --json
```

Array of `{ code, name, description, ... }`. Match by `name`, use `code`.

## search JSON shape

```json
{
  "results": [
    { "content": "...", "score": 0.83, "file_name": "..." }
  ]
}
```

# plugin

## Scopes

- `plugin:read` — `list` / `detail` (in default scopes)
- `plugin:run` — `exec` (in default scopes)

## Commands

```
linkai plugin list [--category <name>] [--json]
linkai plugin detail <plugin_code> [--json]
linkai plugin exec <plugin_code> --input "<text>" [--arg key=value ...] [--json]
```

## Workflow

1. Have a plugin in mind? Skip to step 3.
2. `linkai plugin list --json` (optionally `--category`) to discover.
3. `linkai plugin detail <code> --json` — read expected `input` and `args` shape.
4. `linkai plugin exec <code> --input "..." --arg k=v --json`.

## Notes

- `--arg` is repeatable; each `key=value` is one argument.
- The shape of the JSON `result` field is plugin-specific — check `detail` first.

# workflow

## Scopes

- `workflow:read` — `list` (in default scopes)
- `workflow:run` — `run` (in default scopes)
- `workflow:create` — `create` (**not** in default scopes)
- `workflow:update` — `update` (**not** in default scopes)
- `workflow:delete` — `delete` (**not** in default scopes)

## Commands

```
linkai workflow list [--json]
linkai workflow run <app_code> --input "<text>" [--arg k=v ...] [--session <id>] [--json]
linkai workflow create --name <name> [--desc <txt>] [--json] [--dry-run]
linkai workflow update <code> [--name <name>] [--desc <txt>] [--json] [--dry-run]
linkai workflow delete <code> --force [--dry-run]
```

## Notes

- `<app_code>` is the workflow's app code; get it from `workflow list --json`.
- `--input` is required for `run`.
- `--arg` is repeatable for extra parameters the workflow expects.
- `--session <id>` enables multi-turn workflow context — pass the same id across calls.
- `create` makes a **blank** workflow shell — the node orchestration is done in the console. The create response includes a `links.console` URL that opens the workflow editor; surface it to the user.
- `create` / `update` / `delete` need sensitive scopes; on scope error do not retry, ask the user to re-login with the missing scope.

## Clickable links

`create` (and `app create` / `app detail` / `knowledge create`) return a `links`
object built by the server (never hard-coded in the CLI). The CLI prints these
under the success line. Forward them to the user so they can click straight into
the console.