twenty/packages/twenty-sdk

Twenty SDK

A CLI and SDK to develop, build, and publish applications that extend Twenty CRM.

• Type‑safe client and workspace entity typings
• Built‑in CLI for auth, generate, dev sync, one‑off sync, and uninstall
• Works great with the scaffolder: create-twenty-app

Prerequisites

• Node.js 24+ (recommended) and Yarn 4
• A Twenty workspace and an API key. Generate one at https://app.twenty.com/settings/api-webhooks

Installation

npm install twenty-sdk
# or
yarn add twenty-sdk

Usage

Usage: twenty [options] [command]

CLI for Twenty application development

Options:
  --workspace <name>   Use a specific workspace configuration (default: "default")
  -V, --version        output the version number
  -h, --help           display help for command

Commands:
  auth                 Authentication commands
  app                  Application development commands
  help [command]       display help for command

Global Options

• --workspace <name>: Use a specific workspace configuration profile. Defaults to default. See Configuration for details.

Commands

Auth

Authenticate the CLI against your Twenty workspace.

• twenty auth:login — Authenticate with Twenty.

  • Options:
    • --api-key <key>: API key for authentication.
    • --api-url <url>: Twenty API URL (defaults to your current profile's value or http://localhost:3000).
  • Behavior: Prompts for any missing values, persists them to the active workspace profile, and validates the credentials.

• twenty auth:logout — Remove authentication credentials for the active workspace profile.

• twenty auth:status — Print the current authentication status (API URL, masked API key, validity).

Examples:

# Login interactively (recommended)
twenty auth:login

# Provide values in flags
twenty auth:login --api-key $TWENTY_API_KEY --api-url https://api.twenty.com

# Login interactively for a specific workspace profile
twenty auth:login --workspace my-custom-workspace

# Check status
twenty auth:status

# Logout current profile
twenty auth:logout

App

Application development commands.

• twenty app:sync [appPath] — One-time sync of the application to your Twenty workspace.

  • Behavior: Compute your application's manifest and send it to your workspace to sync your application

• twenty app:dev [appPath] — Start development mode: sync local application changes.

  • Options:
    • -d, --debounce <ms>: Debounce delay in milliseconds (default: 1000).
  • Behavior: Performs an initial sync, then watches the directory for changes and re-syncs after debounced edits. Press Ctrl+C to stop.

• twenty app:uninstall [appPath] — Uninstall the application from the current workspace.

  • Note: twenty app:delete exists as a hidden alias for backward compatibility.

• twenty entity:add [entityType] — Add a new entity to your application.

  • Arguments:
    • entityType: one of function or object. If omitted, an interactive prompt is shown.
  • Options:
    • --path <path>: The path where the entity file should be created (relative to the current directory).
  • Behavior:
    • object: prompts for singular/plural names and labels, then creates a new object definition file.
    • function: prompts for a name and scaffolds a serverless function file.

• twenty app:generate [appPath] — Generate the typed Twenty client for your application.

• twenty app:logs [appPath] — Stream application function logs.

  • Options:
    • -u, --functionUniversalIdentifier <id>: Only show logs for a specific function universal ID.
    • -n, --functionName <name>: Only show logs for a specific function name.

Examples:

# Start dev mode with default debounce
twenty app:dev

# Start dev mode with custom workspace profile
twenty app:dev --workspace my-custom-workspace

# Dev mode with custom debounce
twenty app:dev --debounce 1500

# One-time sync of the current directory
twenty app:sync

# Add a new object interactively
twenty entity:add

# Generate client types
twenty app:generate

# Watch all function logs
twenty app:logs

# Watch logs for a specific function by name
twenty app:logs -n my-function

Configuration

The CLI stores configuration per user in a JSON file:

• Location: ~/.twenty/config.json
• Structure: Profiles keyed by workspace name. The active profile is selected with --workspace <name>.

Example configuration file:

{
  "profiles": {
    "default": {
      "apiUrl": "http://localhost:3000",
      "apiKey": "<your-api-key>"
    },
    "prod": {
      "apiUrl": "https://api.twenty.com",
      "apiKey": "<your-api-key>"
    }
  }
}

Notes:

• If a profile is missing, apiUrl defaults to http://localhost:3000 until set.
• twenty auth:login writes the apiUrl and apiKey for the default profile.
• twenty auth:login --workspace custom-workspace writes the apiUrl and apiKey for a custom custom-workspace profile.

Troubleshooting

• Auth errors: run twenty auth:login again and ensure the API key has the required permissions.
• Typings out of date: run twenty app:generate to refresh the client and types.
• Not seeing changes in dev: make sure dev mode is running (twenty app:dev).

Contributing

Development Setup

To contribute to the twenty-sdk package, clone the repository and install dependencies:

git clone https://github.com/twentyhq/twenty.git
cd twenty
yarn install

Development Mode

Run the SDK build in watch mode to automatically rebuild on file changes:

npx nx run twenty-sdk:dev

This will watch for changes and rebuild the dist folder automatically.

Production Build

Build the SDK for production:

npx nx run twenty-sdk:build

Running the CLI Locally

After building, you can run the CLI directly:

npx nx run twenty-sdk:start -- <command>
# Example: npx nx run twenty-sdk:start -- auth:status

Or run the built CLI directly:

node packages/twenty-sdk/dist/cli.cjs <command>

Resources

• See our GitHub
• Join our Discord