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

name, description

name

description

inkreach-teable

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 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, field-types.md
Records	Read/write row data	record get, record create/update/delete	cli-reference.md § record
Views	Persistent filtered/sorted perspectives	view create/update	cli-reference.md § view
Automation	Event-driven workflows	workflow *, trigger set, action add	automation-guide.md, trigger-types.md, action-types.md
Secrets	Store API keys for script actions	secret set/list/delete	automation-guide.md § Secrets
Execution History	Inspect run results / rerun failures	runs list/get/rerun	cli-reference.md § runs
Manual Trigger	Test by firing button-click/webhook	fire button-click, fire webhook	automation-guide.md § Testing
SQL	Read-only analytics, JOINs, aggregation	sql <sql>	cli-reference.md § sql
Plugins	Install/manage dynamic plugins, developer whitelist, CSP	plugin list/install/uninstall, plugin dev allow/revoke	cli-reference.md § plugin
Dev/Deploy	Build, restart services, known gotchas	(systemd / pnpm build)	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

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

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 deactivated, 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 §script + 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 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 before writing scripts — covers sandbox globals, variable references {{nodeId.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 — all 8 triggers: type string, config keys, output variables.
• action-types.md — all 7 actions: config keys, sandbox globals, variable references.
• 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. For dev/deploy (build, restart systemd, known gotchas): see development.md.