inkreach-teable-cli/.agents/skills/inkreach-teable/SKILL.md

---
name: inkreach-teable
description: >-
  Operate a deployed inkreach-teable instance (a Teable fork with a self-built
  automation engine). Configure tables, fields, records, views, and automations
  (8 triggers incl. recordCreated/Updated/Condition, formSubmitted, scheduledTime,
  buttonClick, webhook; 7 actions: script, sendEmail, httpRequest, createRecord,
  updateRecord, getRecords, sendNotification), plus secrets, execution history, and dynamic plugins
  (install/uninstall, base-level mount nodes, developer whitelist, CSP apiOrigins).
  Trigger when the user wants to manage tables/fields/records/views, build or
  configure automations/workflows, set up button-field triggers, schedule jobs,
  create webhooks, inspect run history, install or configure plugins, allow
  developers to upload plugins, or troubleshoot a deployed inkreach-teable
  instance - even without saying "inkreach-teable" but referencing Teable-style
  IDs (bseXXX, tblXXX, fldXXX, recXXX, viwXXX, wflXXX) or ask to configure
  tables/automation/plugins on the local/deployed instance. Also covers dev/deploy
  tasks (build, restart systemd services). Uses the inkreach-teable CLI, which
  targets the project's OWN automation contract (NOT the official teable CLI).
---

# inkreach-teable operations

This skill operates a deployed inkreach-teable instance via the `inkreach-teable` CLI.
Respond in the user's language. Keep answers concise and action-oriented.

> **Critical**: inkreach-teable's automation engine is **self-built and differs from
> official teable**. The official `teable` CLI does NOT work for automations here.
> Always use the `inkreach-teable` CLI. See [Key Constraints](#3-key-constraints) for the
> exact key-name differences.

## 1. Prerequisites & Constraints

- All operations use the `inkreach-teable` CLI. Install via `bash scripts/install.sh` (relative to this skill dir) if `inkreach-teable` is not found.
- **Endpoint + token**: configure once with `inkreach-teable auth login --endpoint <url> --token <PAT>`. Default endpoint is `http://localhost:3003`. Verify with `inkreach-teable auth status`.
- **Getting a PAT**: `inkreach-teable auth token create --name my-cli` (returns the full token **only once**). Scopes default to automation+table+record read/write. Or create via the web UI (Settings → Personal Access Tokens).
- **`--base-id`**: omit if a default was set via `auth login`; CLI uses it automatically. Ask user only if a command fails with MISSING_BASE_ID.
- **`--json` mode**: add `--json` to any command for raw JSON output (for agent parsing).
- **Unfamiliar commands**: `inkreach-teable <cmd> --help` as a fallback.
- **Read the relevant guide before acting**: after entering a module, read the doc(s) marked "Required" in the module map.

## 2. Module & Command Navigation

### 2.1 Module Map

| Module | What it solves | Entry commands | Guide to read |
|--------|---------------|----------------|---------------|
| Tables & Fields | Create/modify table structure | `table create`, `field create` | [tables-fields.md](guides/tables-fields.md), [field-types.md](api-reference/field-types.md) |
| Records | Read/write row data | `record get`, `record create/update/delete` | [cli-reference.md § record](guides/cli-reference.md#base--table--field--record--view) |
| Views | Persistent filtered/sorted perspectives | `view create/update` | [cli-reference.md § view](guides/cli-reference.md#base--table--field--record--view) |
| Automation | Event-driven workflows | `workflow *`, `trigger set`, `action add` | [automation-guide.md](guides/automation-guide.md), [trigger-types.md](api-reference/trigger-types.md), [action-types.md](api-reference/action-types.md) |
| Secrets | Store API keys for script actions | `secret set/list/delete` | [automation-guide.md § Secrets](guides/automation-guide.md#secrets) |
| Execution History | Inspect run results / rerun failures | `runs list/get/rerun` | [cli-reference.md § runs](guides/cli-reference.md#runs) |
| Manual Trigger | Test by firing button-click/webhook | `fire button-click`, `fire webhook` | [automation-guide.md § Testing](guides/automation-guide.md#testing--triggering) |
| SQL | Read-only analytics, JOINs, aggregation | `sql <sql>` | [cli-reference.md § sql](guides/cli-reference.md#sql) |
| Plugins | Install/manage dynamic plugins, developer whitelist, CSP | `plugin list/install/uninstall`, `plugin dev allow/revoke` | [cli-reference.md § plugin](guides/cli-reference.md#plugin) |
| Dev/Deploy | Build, restart services, known gotchas | (systemd / pnpm build) | [development.md](guides/development.md) |

### 2.2 Routing Rules

> **Before executing**: read the documents marked "Required" in the guide for the module.

| User intent | Correct module | Do NOT do this |
|-------------|---------------|----------------|
| Configure an automation | Automation: `workflow create` → `trigger set` → `action add` → `activate` | Manually editing DB rows |
| React to new records | Trigger `recordCreated` | Polling loop in a script |
| React to field changes | Trigger `recordUpdated` with `--field-ids` | `recordCondition` (ignores fields) |
| React to a condition matching | Trigger `recordCondition` (NOT recordMatchesConditions) | Official-teable key names |
| Button click starts a workflow | Trigger `buttonClick` + a Button-type field | Any other trigger type |
| Receive external HTTP | Trigger `webhook`; fire via `fire webhook` | Expecting auth (backend ignores it) |
| Schedule recurring job | Trigger `scheduledTime` (only type+interval work) | Passing triggerTime/weekdays (backend ignores) |
| Per-row AI / transformation | Action `script` reading `triggerInput` | Manual row-by-row via record API |
| Send notification | Action `sendNotification` (system in-app) | `sendEmail` (needs SMTP) unless email is truly required |
| Add a custom UI / view / panel | Plugins: `plugin install --position base` | Manually editing DB rows |
| Allow a user to upload plugins | Plugins: `plugin dev allow <userIdOrEmail>` (admin only) | — |
| Plugin needs external API access | Plugins: declare `apiOrigins` in `plugin.json` manifest | Editing CSP in next.config.js (global) |
| Read records for later writes | `record get` (returns record IDs) | `sql` (no record IDs returned) |
| Analytics / aggregation / JOIN | `sql` with GROUP BY | Fetch all records + compute in code |
| Store an API key for a script | `secret set` → read in script via `process.env.NAME` | Hardcoding in script code |
| Inspect why a workflow didn't run | `runs list --status failed` → `runs get` | Guessing; re-activating blindly |

### 2.3 Quick Syntax

```bash
# Configure access (once)
inkreach-teable auth login --endpoint http://localhost:3003 --token <PAT>

# Create a table
inkreach-teable table create --name "Tasks" --base-id bseXXX \
  --fields '[{"name":"Title","type":"singleLineText"},{"name":"Status","type":"singleSelect","options":{"choices":["Todo","Done"]}}]'

# Create a workflow + set buttonClick trigger + add a script action + activate
inkreach-teable workflow create --name "On Go click" --base-id bseXXX
inkreach-teable trigger set wflXXX --type buttonClick --table-id tblXXX --field-ids '["fldXXX"]'
inkreach-teable action add wflXXX --type script --code 'return triggerInput.record.fields'
inkreach-teable workflow activate wflXXX

# Test by firing the button
inkreach-teable fire button-click tblXXX recXXX fldXXX
inkreach-teable runs list wflXXX
```

For complete syntax and all options, read [cli-reference.md](guides/cli-reference.md).

## 3. Key Constraints

These differ from official teable and from the (stale) `docs/automation/triggers.md`. **Use these exact values:**

1. **Filter key is `conditions`** (NOT `filter`). Pass via `trigger set --conditions '<json>'`. The JSON shape is `{conjunction:"and"|"or", filterSet:[{fieldId, operator, value}]}`.
2. **Watch-fields key is `fieldIds`** (NOT `watchFieldIds`). For `recordUpdated`/`buttonClick`. `[]` means watch all fields.
3. **Trigger category is `recordCondition`** (NOT `recordMatchesConditions`). It triggers on create+update when the record matches conditions.
4. **`scheduledTime` backend honors only `timing.type` + `timing.interval`**. `triggerTime`, `weekdays`, `daysOfMonth`, `starting`, `ending`, `tz` are all IGNORED by the backend. `weeks` type is hardcoded to every Sunday. Don't configure fields the backend won't use.
5. **Webhook real route is `/api/webhook/{baseId}/{workflowId}`** (no `/base/` or `/workflow/` path segments), and `authorization` config is UI-only — **backend does NOT validate it**. Fire via `inkreach-teable fire webhook <baseId> <wfId>`.
6. **Node updates use whole-graph replacement** (`PUT /node`). CLI commands (`trigger set`, `action add/update/delete`) handle GET→modify→PUT internally — always use them, never hand-edit partial graphs.
7. **`activate` creates a snapshot**: changes to nodes only take effect after re-activating. `hasDraft: true` means unactivated changes exist.
8. **`workflow delete` is a SOFT delete** (cascades to base_node, auto-token, trigger unregister). Test workflows should be `deactivate`d, not deleted.
9. **Secrets values are write-only** — `secret list` never returns the value. Scripts read them via `process.env.<NAME>`.
10. **PAT format is `teable_{id}_{encryptedSign}`** — create via `auth token create`, the full string is returned **once**.
11. **Script sandbox has NO `fs`/`eval`/`Function`**, but has `triggerInput`, `console`, `fetch`, `process.env` (= secrets + `AUTOMATION_TOKEN` + `PUBLIC_ORIGIN`), and a controlled `require`. Use `triggerInput._accessToken` + `triggerInput._apiBaseUrl` to call back into the instance API. **npm deps supported**: declare via `action add/update --dependencies '[{"name":"axios","version":"1.6.0"}]'` (or shorthand `axios@1.6.0,dayjs`), then `require('axios')` works in-sandbox. **Requires** `npm` on the backend service PATH (see [action-types.md](api-reference/action-types.md) §script + [deployment/systemd.md](../../../../deployment/systemd.md) Troubleshooting) — missing it → `spawn npm ENOENT`.

## 4. Execution Rules

### 4.1 Standard Order

1. **Confirm context** — identify target base/table/workflow (`--base-id`, IDs in user's message).
2. **Read before write** — `table get` / `field list` / `workflow get` to confirm current state.
3. **Execute changes** — create/update via CLI commands.
4. **Verify** — re-read; for automations, `activate` then `runs list` after a test fire.

### 4.2 Critical Rules (with reasoning)

1. **Use `inkreach-teable` CLI, never `teable` CLI for automations** — official CLI uses incompatible contract (filter/watchFieldIds/recordMatchesConditions) and will 404 or corrupt config.
2. **Read [trigger-types.md](api-reference/trigger-types.md) before configuring a trigger** — contains exact config keys per trigger; guessing leads to silent misfires.
3. **Build the full chain then activate** — `workflow create` → `trigger set` → `action add` → `activate`. Editing nodes after activation requires re-`activate` to snapshot.
4. **For `buttonClick`, ensure the field is a Button field bound to this workflow** — create via `field create --type button` with `options.workflow.id` (the `workflow` value is an **object** `{id, name?}`, NOT a bare `workflowId` string — matching the DB shape), or the field won't render/click. Note: field `options` captures a stale `isActive` snapshot at creation; the API validates the DB `isActive` at click time instead, so a deactivated workflow returns 400.
5. **Read [action-types.md](api-reference/action-types.md) before writing scripts** — covers sandbox globals, variable references `{{nodeIndex.path}}`, and the `_accessToken`/`_apiBaseUrl` back-channel.

## 5. Common Errors & Recovery

| Symptom | Cause | Fix |
|---------|-------|-----|
| `MISSING_BASE_ID` | No base id resolved | Pass `--base-id`, or `auth login --base-id <id>` |
| `401` / "access denied" | Token invalid/expired or lacks scope | `auth status`; recreate PAT with needed scopes |
| `403` | Base role lacks permission | User must grant role (owner/creator) in web UI |
| Workflow never fires | Not activated, or trigger misconfigured | `workflow get` → check `isActive`; verify trigger type + tableId/fieldIds |
| `scheduledTime` fires at wrong time | Backend ignores most timing fields | Only `timing.type`+`interval` work; use cron-friendly intervals |
| button-click returns 400 "not active" | Workflow deactivated since field created | `workflow activate <id>`, or field options are stale |
| `runs list` shows `failed` | Action error | `runs get <wfId> <execId>` → read `nodeResults[].error` |
| Secret not readable in script | Wrong env var name | Scripts use `process.env.<NAME>` where NAME = secret name |

## 6. API Reference Index

Files in `api-reference/`, read when you need exact config formats:

- **[trigger-types.md](api-reference/trigger-types.md)** — all 8 triggers: type string, config keys, output variables.
- **[action-types.md](api-reference/action-types.md)** — all 7 actions: config keys, sandbox globals, variable references.
- **[field-types.md](api-reference/field-types.md)** — Teable field types, aliases, and option shapes (incl. Button field with `workflowId`).

## 7. Instance Access

Endpoint, service status, and credential-acquisition steps: see [instance-access.md](guides/instance-access.md).
For dev/deploy (build, restart systemd, known gotchas): see [development.md](guides/development.md).