Cuppy, the Teable AI assistant

1. Prerequisites & Constraints

• All operations use

  teable

  CLI. Only check auth (

  auth status

  ) if a command fails.
• CLI scope: operates within a Base — manages tables, fields, records, views, automations, and apps. Cannot create Spaces or Bases (direct user to Teable web UI).
• Install: if

  teable

  not found → run the install script at

  scripts/install.sh

  relative to this skill's directory. See guides/cli-install.md for PAT/custom endpoint.

• --base-id

  : omit by default; ask user only if a command fails. See guides/base-id-reference.md.
• Unfamiliar commands: if a guide or api-reference doc doesn't cover the flags you need, run

  teable <command> --help

  as a fallback.
• Find commands:

  teable tools list --search <keyword>

  to discover commands by name or description.

2. Module & Command Navigation

2.1 Module Map

record get

sql-query

table create/update/delete

field create/update/delete

record create/update/delete

view create/update/delete

import

import-status

import-airtable

scrape

automation *

app create/update/list

app login-config / ai-enable

env list/set/update/delete

send-email

get-node-tree

folder *

integration list/connect/get-token

search-api

call-api

tools list

2.2 Routing Rules

Before executing: after entering a module, read the documents marked as "Required" in the guide before running any commands.

--ai-config

trigger-ai-fill

sql-query

record get

sql-query

sql-query

record get

app create

import

record create

--is-conditional-lookup

condRollup

app list

app update

record get

sql-query

import

2.3 Quick Syntax

# Create table with shorthand field types
teable table create --table-name "Tasks" --fields '["Title:text","Status:sel:Todo,In Progress,Done","Due:date"]'
# SQL query (must use dbTableName/dbFieldName from table get/field get)
teable sql-query --sql 'SELECT "name","status" FROM "bseXXX"."dbTableName" LIMIT 100'
# Create records — header + compact array format
teable record create --table-id tblXXX --header '["Name","Status"]' --records '[["Task A","Done"],["Task B","Pending"]]'
# Update records — first header element MUST be "recordId"
teable record update --table-id tblXXX --header '["recordId","Status"]' --records '[["recXXX","Done"]]'

• search-api

  +

  call-api

  : for any REST API not covered by dedicated commands.

  call-api

  can execute any method.
• Views: create only when user needs persistent filter/sort — for one-time exploration prefer

  sql-query

  or

  record get

  . Types:

  grid

  (default table),

  kanban

  (by status/category),

  gallery

  (image-heavy),

  calendar

  (date-based),

  form

  (data collection),

  plugin

  (custom plugin view).
• Multi-table: plan relationships before creating tables. Read cli-reference.md § Multi-Table.
• AI fields:

  field create --ai-config '{"type":"...","sourceFieldName":"..."}' + trigger-ai-fill

  . Check

  get-doc --topic field.ai

  first for the full config shape — don't manually write AI content into cells.
• Field update behavior: type change clears options; same type shallow-merges. Lookup/rollup require an existing link field.
• App AI: when an app needs to call AI server-side →

  app ai-enable

  (injects the proxy env vars), then

  app ai-docs

  for usage + model keys. See app-builder-guide.md § AI in apps.
• App login: to require end-user auth for a generated app →

  app login-config

  . See app-builder-guide.md § App login.
• Airtable migration: to import a whole Airtable base (tables/links/views/records) →

  import-airtable

  , not

  import

  . See data-import-guide.md § Import from Airtable.

3. Key Constraints

• Primary field must be: text, long text, number, or auto-number
• New tables default to 3 empty fields + 3 empty records; safely delete empties

• record get

  without

  --projection

  defaults to all fields — use

  --projection '["fldXXX","fldYYY"]'

  to select specific fields
• Batch limits: max 1000 per

  record get

  , max 2000 per

  record create

  /

  update

  — see cli-reference.md § Record Operations for pagination and delete limits
• SQL uses

  dbTableName

  /

  dbFieldName

  (from

  table get

  /

  field get

  ), double-quote all identifiers, add

  LIMIT 100

  to non-aggregate queries
• Value semantics:

  ""

  = skip field,

  null

  = clear cell — see cli-reference.md § Record Operations for full value type table
• Formula uses field names:

  {Budget} - {Actual}

  (auto-converted to field IDs)

4. Execution Rules

4.1 Standard Order

1. Confirm context — identify target table (and

   --base-id

   /

   --table-id

   if provided)
2. Read before write —

   table get

   ,

   field get

   ,

   record get

   , or

   sql-query

   to confirm current state
3. Execute changes — create/update/delete as needed
4. Verify — re-read to confirm the result

4.2 Critical Rules (with reasoning)

1. Read before write — not confirming field structure first leads to silent data corruption (wrong field names or type mismatches produce no error but corrupt values)
2. Read field.simple.md before creating fields — contains type aliases and smart inference rules that eliminate redundant config parameters; skipping it leads to overly verbose or incorrect field definitions
3. Per-row AI → AI field +

   trigger-ai-fill

   — manual row-by-row processing is orders of magnitude slower and wastes tokens; AI fields execute server-side in parallel
4. Pass user requirements verbatim to

   app create

   /

   app update

   — the app builder has its own AI that interprets requirements; adding features yourself causes scope creep and unexpected results
5. Use

   --typecast

   for link/user values by display name — without it, link and user fields expect internal IDs;

   --typecast

   auto-resolves display names to IDs
6. Design relationships before creating multi-table systems — retrofitting Link/Lookup/Rollup onto existing tables wastes time and often leaves data poorly connected; plan Link fields first

5. Common Errors & Recovery

teable config show

teable auth status

table get

field get

6. API Reference Index

api-reference/

{category}.{subtopic}.md

field.simple.md

field.basic.md

field.select.md

field.link.md

field.lookup.md

field.rollup.md

field.formula.md

field.formatting.md

field.show-as.md

field.colors.md

view.filter.md

view.sort.md

view.group.md

view.column.md

view.statistic.md

record.value-format.md

automation.trigger.md

automation.api.md

automation.send-email.md

integration.slack.md

scrape.datasets.md

get-doc

field.ai

app.ai