# CLI Reference

Complete command reference for `inkreach-teable`. Global options apply to all commands.

## Global Options

| Option | Description |
|--------|-------------|
| `--endpoint <url>` | Backend URL (default `http://localhost:3003`) |
| `--token <pat>` | Personal Access Token |
| `--base-id <id>` | Default base id |
| `--json` | Output raw JSON (for agent parsing) |
| `--debug` | Print HTTP requests/responses to stderr |
| `-v, --version` | Show version |

Config precedence: global flag > env (`INKREACH_TEABLE_ENDPOINT`/`INKREACH_TEABLE_TOKEN`/`INKREACH_TEABLE_BASE_ID`) > `~/.inkreach-teable/config.json`.

## auth

```bash
inkreach-teable auth status                              # verify token + show user
inkreach-teable auth login --endpoint <url> --token <PAT> [--base-id <id>]
inkreach-teable auth token list
inkreach-teable auth token create --name <n> [--scopes <csv>] [--base-ids <csv>] [--full-access] [--expires <date>]
inkreach-teable auth token delete <id>
```

- `auth token create` returns the full token **only once**. Default scopes: `automation|read,automation|create,automation|update,automation|delete,table|read,record|read,record|create,record|update`.

## base / table / field / record / view

These resources use the official-teable-compatible API. Full guide: [tables-fields.md](tables-fields.md).

```bash
# base
inkreach-teable base list
inkreach-teable base get <baseId>

# table
inkreach-teable table list [--base-id <id>]
inkreach-teable table get <tableId>
inkreach-teable table create --name <n> [--base-id <id>] [--fields '<json>']
inkreach-teable table update <tableId> --name <n>
inkreach-teable table delete <tableId>

# field  (get/update/visible-choices take <tableId> <fieldIdOrName> — id or display name, auto-resolved)
inkreach-teable field list <tableId> [--with-options]
#   --with-options: OPTIONS summary column + per-choice visibility conditions for select fields
inkreach-teable field get <tableId> <fieldIdOrName>
#   human mode renders select choices with their visibilityFilter conditions; --json for raw
inkreach-teable field create --table-id <tid> --name <n> [--type <t|alias>] [--options '<json>'] \
  [--description <d>] [--lookup-options '<json>'] [--is-lookup]
#   --type optional: inferred from --options shape / --name when omitted
inkreach-teable field update <tableId> <fieldIdOrName> [--name <n>] [--options '<json>']   # --options goes via convert API
inkreach-teable field visible-choices <tableId> <recordId> <fieldIdOrName>                 # evaluate select-choice visibilityFilter
inkreach-teable field delete <tableId> <fieldId>

# record
inkreach-teable record get --table-id <tid> [--filter '<json>'] [--projection '<json>'] [--page-size <n>] [--page <n>] [--search <kw>]
inkreach-teable record get-one <recordId>
inkreach-teable record create --table-id <tid> --fields '<json>'            # single
inkreach-teable record create --table-id <tid> --records '<json>'           # batch
inkreach-teable record update --table-id <tid> --records '<json>'
inkreach-teable record delete --table-id <tid> --record-ids <csv>

# view
inkreach-teable view list <tableId>
inkreach-teable view get <viewId>
inkreach-teable view create --table-id <tid> --name <n> [--type <t>]
inkreach-teable view update <viewId> [--name <n>]
inkreach-teable view delete <viewId>

# view presets (view-scoped shared named filter/sort bundles, applied via toolbar)
inkreach-teable preset list <tableId> [--view-id <vid>]
inkreach-teable preset create --table-id <tid> --view-id <vid> --name <n> [--description <d>] \
  [--filter '<json>'] [--sort '<json>'] [--group '<json>'] [--options '<json>'] [--column-meta '<json>']
inkreach-teable preset update <presetId> --table-id <tid> [--name <n>] [--description <d>] [--filter '<json>' ...]
inkreach-teable preset delete <presetId> --table-id <tid>
```

## workflow

```bash
inkreach-teable workflow list [--base-id <id>]
inkreach-teable workflow get <workflowId> [--base-id <id>]
inkreach-teable workflow create --name <n> [--description <d>] [--base-id <id>]
inkreach-teable workflow update <workflowId> [--name <n>] [--description <d>] [--base-id <id>]
inkreach-teable workflow delete <workflowId> [--base-id <id>]
inkreach-teable workflow activate <workflowId> [--base-id <id>]
inkreach-teable workflow deactivate <workflowId> [--base-id <id>]
inkreach-teable workflow test <workflowId> [--base-id <id>]
```

Full automation flow: [automation-guide.md](automation-guide.md).

## trigger

```bash
inkreach-teable trigger set <workflowId> --type <T> [options] [--base-id <id>]
```

| `--type` | Required options |
|----------|------------------|
| `recordCreated` | `--table-id` |
| `recordUpdated` | `--table-id`, `--field-ids '<json>'` |
| `recordCondition` | `--table-id`, `--conditions '<json>'` |
| `recordCreatedOrUpdated` | `--table-id` |
| `formSubmitted` | `--table-id`, `--form-ids <csv>` |
| `scheduledTime` | `--schedule '{"timing":{"type":"minutes","interval":5}}'` |
| `buttonClick` | `--table-id`, `--field-ids '<json>'` |
| `webhook` | (none) |

Common optional: `--batch '<json>'` (record triggers only).

Details: [trigger-types.md](../api-reference/trigger-types.md).

## action

```bash
inkreach-teable action add <workflowId> --type <T> [options] [--base-id <id>]
inkreach-teable action update <workflowId> <nodeId> [--config '<json>'] [--code <js>] [--code-file <path>] [--name <n>]
inkreach-teable action delete <workflowId> <nodeId> [--base-id <id>]
```

Per-type options:

| `--type` | Options |
|----------|---------|
| `script` | `--code <js>` / `--code-file <path>`, `--timeout <ms>` |
| `sendEmail` | `--to <email>`, `--subject <s>`, `--body <html>` |
| `httpRequest` | `--url <u>`, `--method <m>`, `--headers <json>`, `--req-body <json>` |
| `createRecord` | `--target-table <id>`, `--records <json>` |
| `updateRecord` | `--target-table <id>`, `--records <json>` |
| `getRecords` | `--target-table <id>`, `--query <json>` |
| `sendNotification` | `--to-user <usrId>`, `--title <s>`, `--message <s>`, `--severity <s>`, `--path <s>` |

Details: [action-types.md](../api-reference/action-types.md).

## secret

```bash
inkreach-teable secret list <workflowId> [--base-id <id>]
inkreach-teable secret set <workflowId> --name <n> --value <v> [--description <d>] [--base-id <id>]
inkreach-teable secret update <workflowId> <secretId> [--name <n>] [--value <v>] [--description <d>] [--base-id <id>]
inkreach-teable secret delete <workflowId> <secretId> [--base-id <id>]
```

Values are write-only — `list` never returns them. Scripts read via `process.env.<NAME>`.

## runs

```bash
inkreach-teable runs list <workflowId> [--status failed|succeeded|running] [--base-id <id>]
inkreach-teable runs get <workflowId> <executionId> [--base-id <id>]
inkreach-teable runs rerun <workflowId> <executionId> [--base-id <id>]
```

`rerun` only works on `failed` executions (backend validates).

## fire

```bash
inkreach-teable fire button-click <tableId> <recordId> <fieldId>
inkreach-teable fire webhook <baseId> <workflowId> [--body '<json>'] [--method <m>]
```

Manually trigger for testing. Webhook needs no auth (backend is `@Public`).

## subscription

```bash
inkreach-teable subscription list
inkreach-teable subscription get <subscriptionId>
inkreach-teable subscription create --name <n> --table-id <tid> [options]
inkreach-teable subscription update <subscriptionId> [options]
inkreach-teable subscription delete <subscriptionId>
inkreach-teable subscription events <subscriptionId>
inkreach-teable subscription send <subscriptionId>
```

Record digest/instant email subscriptions. Options (`--filter`, `--send-mode`,
`--schedule-*`, `--trigger-on-enter`, …) and semantics: [subscription.md](subscription.md).

## sql

```bash
inkreach-teable sql '<SELECT ...>' [--base-id <id>]
```

Read-only. Must use `dbTableName`/`dbFieldName` (from `table get`/`field get`), double-quote identifiers, add `LIMIT 100`.

```bash
inkreach-teable sql 'SELECT "name" FROM "bseXXX"."tbl_abc" LIMIT 10'
```

## plugin

Manage plugins and developer whitelist.

```bash
# List plugins registered in the base
inkreach-teable plugin list

# Register a URL-served plugin (runtimeType=url; status published immediately)
# positions: "base"|"panel"|"view"|"dashboard"|"contextMenu"
inkreach-teable plugin register --url <url> --name <name> [--positions '["panel"]'] [--logo <url>] [--description <d>]
# Bundle (upload) plugins use a different flow — see skill guides/tables-fields.md
# or api docs: create kebab-id plugin (developer whitelist) → upload → admin publish.

# Developer whitelist (admin only)
inkreach-teable plugin dev list
inkreach-teable plugin dev allow <userIdOrEmail>   # add (userId or email)
inkreach-teable plugin dev revoke <userIdOrEmail>  # remove

# Install / uninstall (creates a base-level mount node)
inkreach-teable plugin install --plugin <pluginId> --name "My Plugin" --position base
#   ⚠️ For view/dashboard-position plugins, run `plugin config enable` BEFORE
#   install, or the install API returns 403 RESTRICTED_RESOURCE
#   'Plugin is not enabled for this base'.
inkreach-teable plugin installs        # list installs in current base
inkreach-teable plugin uninstall --install <installId>

# Enable/disable plugins
inkreach-teable plugin config enable --plugin <pluginId>
inkreach-teable plugin config disable --plugin <pluginId>

# CSP apiOrigins (external origins plugins may fetch)
inkreach-teable plugin csp list
inkreach-teable plugin csp set <pluginId> --origins '["http://192.168.x.x:8001"]'
```

Developer whitelist is admin-only (requires `user.isAdmin=true`). Routes:
`/api/plugin-developers` (GET/POST/DELETE).

## Output Modes

- **Human (default)**: tables / key-values, colored where supported.
- **`--json`**: compact raw JSON on stdout. Errors in JSON mode:
  ```json
  { "error": { "status": 404, "code": "NOT_FOUND", "message": "..." } }
  ```
  (exit code 1)

## Error Troubleshooting

1. `inkreach-teable auth status` — token valid? endpoint reachable?
2. Verify IDs: `table get`, `field get`, `workflow get` (typo'd IDs → 404).
3. Check permissions: token scopes + base role. `403` → role too low.
4. `--debug` to see the raw HTTP request/response.