Teable App Builder (local workspace)

A Teable app is a Next.js project that reads and writes a Teable project (base) through the Teable SDK, hosted and published by Teable. Normally Teable's own agent (Cuppy) builds it in a sandbox. This skill does the same work on the user's machine: you are the agent, the

teable

CLI materializes everything the sandbox would have provided, and

teable app push

saves versions back to Teable.

You run on the user's machine, not in that sandbox. There is no in-app chat around you: no credential cards, no sandbox paths, no Teable-side preview you control. Where the sandbox would show a card, ask the user in your own conversation; the

AGENTS.md

a checkout gets is already the local variant.

Data questions (query records, change rows) go through the Teable MCP tools when they are available; everything that produces files, touches git or needs the app checkout goes through the CLI. Do not mix the two for the same job.

This skill covers only the local checkout. Two neighbouring jobs belong to the

teable-assistant-ops

skill: having Teable's own builder write or change the app from a prompt (

teable app create|update --prompt

, no checkout involved), and work on the project itself (creating tables, fields and views, imports, automations). Use it for the tables a new app needs.

Prerequisites

Node.js 22+, git and pnpm on PATH.
The CLI: use
```
teable
```
when it is on PATH; otherwise run every command as
```
npx -y @teable/cli@latest <command>
```
(no install step). The app checkout commands need a CLI whose
```
teable app --help
```
lists
```
init
```
.
Sign-in happens once and you do it, not the user: when a command answers
```
Authorization is required
```
, run
```
teable auth login
```
— it opens the browser, the user approves, done.
```
teable auth status
```
shows the account and endpoint. Self-hosted Teable:
```
--endpoint <url>
```
or
```
TEABLE_ENDPOINT
```
.
The deployment has a git registry for app code (teable.ai does). Without it the CLI says so; then the app is built in the in-app App Builder and
```
teable app get-code
```
gives a read-only copy.

1. Resolve the project (base) first

Every app belongs to one project. First read what the user is asking for:

Building on data they already have ("an app for my inventory table", a pasted URL, a project name) → find that project (below).
A new system from scratch ("make me a CRM", "build a booking app") with nothing pointing at existing data → usually a new project:
```
teable base create --space-id spc… --name "<name>"
```
, then create the tables the app needs and
```
teable link <baseId>
```
. A request like this is not a reason to drop tables into some unrelated project the user happens to have.
Unclear → ask once, offering the close existing projects and "a new project" side by side.

Finding an existing project, most specific first:

Explicit: a Teable URL (take the
```
bse…
```
id from it), an id, or a name →
```
teable base list --search "<name>"
```
. One hit: use it. Several: ask the user which.
Directory binding: the current directory (or a parent) holds
```
.teable/app.json
```
(an app checkout) or
```
.teable/cli/config.json
```
(
```
teable link
```
). Commands run there need no
```
--base-id
```
.
Ask:
```
teable link
```
without arguments lists the projects the account can use. Show the candidates and ask once; then
```
teable link <baseId>
```
.

Creating a project is visible to everyone in that space, so say where it goes before or as you do it ("creating project CRM in space Sales"). The space: the one the user named; else the only one they have (spaces show up in

teable base list

); else the obvious one from context; otherwise ask, together with any other open question rather than as a separate round. Don't stop to ask about anything you can reasonably decide and mention instead.

Tables need no choosing: the checkout receives

schema/*.json

for every table of the project.

2. Create or clone the checkout

bash

teable app init --name "<App name>" --dir ./<dir>        # new app, scaffold as version 1
teable app clone --app-id app… --dir ./<dir>             # existing app (ids from `teable app list`)

Which app: the one the user named or linked. Otherwise run

teable app list

first. Several apps and no name → ask which one. A request for a new app when a similar one already exists → ask once whether to change that one or start a new one; do not pick silently.

Both leave a git checkout whose remote

teable

is the app repository, plus:

File	Purpose
`CLAUDE.md` → `AGENTS.md`	The platform's instructions for this app: stack, scaffold map, locked files, data rules, credential rules. Read it before writing code.
`.env`	Platform variables (API URL, app token, app and project ids, AI gateway). Never edit or commit; `teable app pull` refreshes it.
`teable.md` , `schema/*.json`	SDK usage and the current table schemas. Regenerated by `teable app pull` .
`.teable/app.json`	Workspace marker (app, project, endpoint). Gitignored; do not edit.

Then

cd <dir>

pnpm install

pnpm dev

(port 3000) and build.

AGENTS.md

is authoritative for conventions; this skill only covers the workflow around it.

3. Work, then push

bash

teable app pull                        # start of a session, or when tables/app may have changed
# ... edit, verify with curl -s http://127.0.0.1:3000 ...
teable app push -m "<what changed>"    # commit (if needed), pre-check, push, record a Teable version

push

refuses when platform-owned files changed, when a

.env

file is tracked, when

teable/queries.yaml

is invalid, or when the app repository moved ahead (then

teable app pull

, resolve, push again). On success Teable records the version under the user's name, refreshes a running preview and notes the push in the app chat. A plain

git push

does not create a version.

clone

and

pull

also bring the checkout to what the Teable sandbox would run: they rewrite the platform's own files and apply pending template upgrades to an older app (Next 16

proxy.ts

pnpm-workspace.yaml

, …). On a clean tree that lands as its own commit ("Upgrade app template" or "Sync platform files"), pushed with your next

teable app push

; check

notes

in the output for anything left to do by hand.

pull

reports table-schema changes since the last sync ("field added", "type changed", …) and pending named-query repairs. Adjust code for the changes; review repairs with

teable query repairs

and

teable query repair-apply --repair-id <id>

(details in

references/workflow.md

4. Publish, inspect, roll back

bash

teable app publish --wait              # only when the user asks; streams build steps, prints the URL
teable app versions --app-id app…      # history
teable app rollback --app-id app… --to <n>   # restores as a new version; then `teable app pull`

Rules that keep the checkout valid

Never edit the locked files
```
AGENTS.md
```
lists (
```
lib/teable.ts
```
,
```
lib/credentials.ts
```
,
```
next.config.mjs
```
, reporters, beacon route, …): the platform rewrites them.
Never ask the user to paste a secret into the chat, and never pass
```
--value
```
yourself. The user runs
```
teable secret set --key <KEY> --grant app:<appId> --dev-env
```
in a terminal window of their own (not via
```
!
```
in Claude Code: no TTY there): it prompts for the value without echo, stores it as their personal secret granted to the app, and writes the same key to the checkout's
```
.env.local
```
for
```
pnpm dev
```
.
An app that reads a third-party service (Stripe, HubSpot, Gmail…) gets a connection, not an API key, whenever one exists:
```
teable integration search --query "<task>"
```
finds it,
```
teable integration connect --toolkit <slug> --wait
```
opens the consent screen, then
```
teable secret grant --type connection --id <connectionId> --resource app:<appId> --alias <ALIAS>
```
. A toolkit that takes an API key prompts for it in the terminal, so the user runs that command themselves in a terminal window of their own — not via Claude Code's
```
!
```
prefix, which has no TTY, so the prompt cannot read the value. AGENTS.md has the runtime helpers (
```
getConnectionToken
```
,
```
callConnection
```
); both work under
```
pnpm dev
```
.
Login flows redirect to the Teable preview origin, not localhost: verify them after a push in the app's Preview panel in Teable.
Keep commits user-facing: one commit per completed request, subject under 72 characters, no
```
feat:
```
/
```
fix:
```
prefixes.
Codex: the first
```
git push
```
and CLI network calls need network approval.

See

references/workflow.md

for the end-to-end script and

references/pitfalls.md

for what goes wrong and how to recover.

teable-app-builder

NPX Install

Tags

SKILL.md Content

Teable App Builder (local workspace)

Prerequisites

1. Resolve the project (base) first

2. Create or clone the checkout

3. Work, then push

4. Publish, inspect, roll back

Rules that keep the checkout valid