@teable/cli

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

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

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"

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

# custom output path
teable auth --path ./.teablerc.json

# 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

# SQL query
teable sql-query \
  --base-id bseXXXX \
  --sql "SELECT * FROM \"bseXXXX\".\"orders\" LIMIT 10"

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

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

# Get records with projection
teable get-records \
  --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 \
  --api-id 'POST:/table/{tableId}/record/{recordId}/duplicate' \
  --path-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)

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

Directory structure

src/
  cli.ts                         # commander bootstrap + command registration
  auth/
    constants.ts                 # OAuth constants (client ID, timeout)
    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)
    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