inkreach-teable-cli/.agents/skills/inkreach-teable/guides/cli-reference.md

# 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:3000`) |
| `--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
inkreach-teable field list <tableId>
inkreach-teable field get <fieldId>
inkreach-teable field create --table-id <tid> --name <n> --type <t> [--options '<json>']
inkreach-teable field update <fieldId> [--name <n>] [--options '<json>']
inkreach-teable field delete <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>
```

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

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

## 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 plugin (set runtimeType, positions, logo)
inkreach-teable plugin register --name <name> --positions '["base","panel"]'

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

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.