@teable/cli

CLI wrapper for @teable/ai-tools-ee.

This package is organized around a one-tool-one-command architecture.

A Teable Project is the API base, with a bse-prefixed ID. API fields such as baseId, URLs, permissions, and CLI syntax such as teable base and --base-id keep their existing names.

Media generation

Media tasks run in a persistent backend queue. One task holds at most MEDIA_TASK_MAX_ITEMS images (a backend setting, 5 by default); split larger jobs into several tasks. Every image is queued when the task is submitted, and media generate waits until all of them have succeeded, failed or been cancelled, reporting finished images as they arrive and preserving partial results.

teable media generate --prompt "A mountain landscape" --base-id bseXXXX
teable media generate --prompt "An illustration" --reference ./reference.png --output ./image.png
teable media generate --prompt "A poster" --model aiGateway@openai/gpt-image-2@teable
teable media generate --input ./images.json --output-dir ./images
teable media get --id mgtXXXXXXXXXXXXXXXX --wait --output-dir ./recovered
teable media cancel --id mgtXXXXXXXXXXXXXXXX

--input accepts a JSON array or { "items": [...] }; --input - reads stdin. Each item contains description, prompt, and optional aspectRatio, quality, and inputImages. References can be local paths, { "filePath": "./reference.png" }, or previously uploaded { "token": "..." }. Local references reuse the standard ChatFile upload flow. Only image generation is currently supported.

{
  "items": [
    { "description": "Mountain morning", "prompt": "Mountain landscape in morning light" },
    { "description": "Mountain evening", "prompt": "Mountain landscape in evening light" }
  ]
}

Without output options, results remain in ChatFile and include download URLs. -o, --output <file> downloads one image; --output-dir <dir> downloads each finished image immediately, with stable sequence/item filenames. These options are mutually exclusive. Existing files are never overwritten and partially downloaded files are never published as finished files. A local download error does not change the backend generation status; retrieve it again using media get and a new target path.

While a command waits, progress is JSON on stderr; the final JSON on stdout contains task, optional downloads, and any command error. Partial generation or download failures exit nonzero while retaining successful results; items cancelled by the user do not affect the exit code. There is no overall CLI waiting timeout: execution timeouts belong to individual backend jobs; network requests and transfers have bounded timeouts. Transient status-read failures (connection errors, 429, 5xx) are retried with backoff for up to 90 seconds before the command gives up and prints the last accepted snapshot. Ctrl+C stops waiting without cancelling the backend task. Recover with media get --id ...; reuse --request-id if the submission response was lost. Replaying local reference images may allocate new upload tokens. The backend compares their existing attachment hash, size and MIME metadata, so the same image request returns its original task; changed inputs require a new request ID. The hash follows the configured storage adapter's existing semantics (local file hash or object-storage ETag).

Internal Agent tools use --events and --sandbox-output-dir when submitting. The backend validates Agent identity, writes directly to the managed Sandbox directory, and returns real file paths; there is no ChatFile fallback. --events emits JSON Lines { "type": "progress" | "result", "task": ... }; the accepted plan is emitted before polling. media get prints the current snapshot once; with --wait, --output or --output-dir it waits until the task has finished. The CLI never regenerates failed images; submit a new task for them once the user decides. media cancel stops every unfinished image and keeps the completed ones. Inside Teable-managed agent sandboxes the backend refuses ChatFile output: images are produced with the generate_image tool, which drives the CLI itself.

Configure auth

Two authentication methods are supported: OAuth login (recommended) and Personal Access Token (PAT).

OAuth login (recommended)

teable auth login

Opens a browser for Teable login using OAuth Authorization Code + PKCE. After authorization, tokens are saved automatically. Access tokens auto-refresh before expiry — no manual token management needed.

# custom endpoint
teable auth login --endpoint https://my-teable.example.com

# custom OAuth client ID
teable auth login --client-id my-client-id

# request specific scopes (comma-separated)
teable auth login --scopes "table|read,record|read,record|create"

Where no local callback port is reachable

In a cloud IDE, over SSH or inside a container, the browser runs on a different machine than the CLI: binding the callback port succeeds, but the browser resolves 127.0.0.1 to its own machine, so the callback never arrives and the login just waits. Use the device authorization grant there — the code travels from the terminal to the browser, so nothing has to come back into a session that may not even be on your machine:

teable auth login --device-code

The CLI prints a URL and a one-time code, you sign in on any device, type the code, and the CLI picks up the tokens from its next poll.

The built-in CLI app supports this out of the box. If you pass a custom --client-id, that app must first turn on Enable device flow in its OAuth app settings — the grant is per-app opt-in.

The printed link assumes the web app is served on the same origin as the API endpoint you configured, which is true for every Teable deployment today.

Personal Access Token (PAT)

teable auth --token teable_pat_xxx

Non-interactive — writes a PAT-based auth config. Tokens can also be provided via TEABLE_TOKEN or TEABLE_PAT environment variables.

# overwrite existing file
teable auth --force

# project-local config — writes ./.teable/cli/config.json under the given directory
teable auth --path .

# explicit endpoint
teable auth --token teable_pat_xxx --endpoint https://app.teable.ai

Auth management

# show current auth status (auth type, token expiry, scopes, etc.)
teable auth status

# clear saved credentials (OAuth tokens and PAT)
teable auth logout

Auth config is saved to ~/.teable/cli/config.json by default.

Usage examples

# Manage projects (create / get / list / update / delete)
teable base list                          # all accessible projects
teable base list --space-id spcXXXX       # projects in one space
teable base create --space-id spcXXXX --name "My Project" --icon 📊
teable base get --base-id bseXXXX
teable base update --base-id bseXXXX --name "Renamed Project"
teable base delete --base-id bseXXXX

# SQL query
# `dbTableName` from `teable table get` is one dotted value (e.g. bseXXXX.tbl_users);
# split it on the dot into two quoted identifiers: "bseXXXX"."tbl_users"
teable sql-query \
  --base-id bseXXXX \
  --sql "SELECT * FROM \"bseXXXX\".\"tbl_users\" LIMIT 10"

# List available tools for current project permission
teable tools list --base-id bseXXXX

# Search tools by keyword
teable tools list --base-id bseXXXX --search sql

# Get records with projection
teable record get \
  --base-id bseXXXX \
  --table-id tblXXXX \
  --take 10 \
  --projection '["fldName","fldAmount"]'

# Call API with path params (object/array fields use JSON string)
teable call-api \
  --base-id bseXXXX \
  --method POST \
  --url '/table/{tableId}/record/{recordId}/duplicate' \
  --params '{"tableId":"tblXXXX","recordId":"recXXXX"}'

Auth resolution priority

1. --token CLI flag
2. TEABLE_TOKEN / TEABLE_PAT environment variable
3. OAuth tokens from config (with auto-refresh)
4. PAT from config

Endpoint: --endpoint flag or TEABLE_ENDPOINT env (default: https://app.teable.ai).

Config

Config loading order:

1. User-level config: ~/.teable/cli/config.json
2. Project-level override (optional):
   • .teable/cli/config.json in project root

PAT config:

{
  "token": "teable_pat_xxx",
  "endpoint": "https://app.teable.ai"
}

OAuth config (written automatically by auth login):

{
  "endpoint": "https://app.teable.ai",
  "token": "...",
  "oauth": {
    "accessToken": "...",
    "refreshToken": "...",
    "expiresAt": 1709654400000,
    "refreshExpiresAt": 1712246400000,
    "clientId": "teable-cli",
    "scopes": ["table|read", "record|read"]
  }
}

Fields:

• token — PAT or OAuth access token
• endpoint — Teable API endpoint
• oauth — OAuth token state (managed automatically)
• disabledCommands — commands to turn off (see below)

timeZone and permissionLevel are resolved dynamically by tool middleware and cached in ~/.teable/cli/runtime-cache.json for 5 minutes, keyed by baseId.

Disabling commands

Commands can be turned off — useful for environments where, for example, projects are provisioned by setup code and base CRUD should not be exposed.

Set disabledCommands in the config file, and/or the TEABLE_CLI_DISABLED_COMMANDS env var (comma-separated); the two are merged. Each entry targets a command:

• a resource group — base (disables the whole group)
• a group:verb — base:create (disables one sub-command)
• a standalone command — sql-query

{
  "disabledCommands": ["base", "scrape"]
}

TEABLE_CLI_DISABLED_COMMANDS=base:create,base:delete teable base --help

Disabled commands are not registered at all — running one yields an "unknown command" error. Any command can be disabled, including auth and config; Teable-managed agent sandboxes use this to disable base:create, base:update, base:delete, auth, config, integration:connect, secret:grant, and secret:revoke.

Directory structure

src/
  cli.ts                         # commander bootstrap + command registration
  auth/
    constants.ts                 # OAuth constants (client ID, timeouts, poll intervals)
    pkce.ts                      # PKCE crypto utilities (verifier, challenge, state)
    callback-server.ts           # Temporary HTTP server for OAuth redirect
    oauth-client.ts              # Token exchange & refresh HTTP calls
    browser.ts                   # Browser open + terminal refocus (macOS)
    device-login.ts              # Device authorization grant (RFC 8628), for --device-code
    oauth-login.ts               # Orchestrator: ties all auth modules together
  commands/
    index.ts                     # command registration entry
    auth.command.ts              # auth, auth login, auth logout, auth status
    tools/
      *.command.ts               # one file per tool command
      list.command.ts            # list tools filtered by permission
      sql-query.command.ts       # specialized sql-query command
      tool-metas.ts              # tool command metadata + creators
      tool-commands.generated.ts # generated bundles for tool defs
      shared/
        shared-options.ts        # common tool command options
        tool-guards.ts           # tool definition guard helpers
        tool-command-factory.ts  # shared command factory
  bootstrap/
    config.ts                    # resolve token/endpoint (PAT + OAuth)
    openapi.ts                   # openapi axios setup + auto-refresh interceptor
  runtime/
    context.ts                   # experimental_context builder
    cache.ts                     # runtime context cache
    tool-runtime.ts              # shared tool command context/runtime helpers
  types.ts