A CLI and SDK to develop, build, and publish applications that extend [Twenty CRM](https://twenty.com).
- 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](https://www.npmjs.com/package/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
```bash
npm install twenty-sdk
# or
yarn add twenty-sdk
```
## Usage
```
Usage: twenty [options] [command]
CLI for Twenty application development
Options:
--workspace 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 `: 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 `: API key for authentication.
- `--api-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).
- `twenty auth:list` — List all configured workspaces.
- Behavior: Displays all available workspaces with their authentication status and API URLs. Shows which workspace is the current default.
- `twenty auth:switch [workspace]` — Switch the default workspace for authentication.
- Arguments:
- `workspace` (optional): Name of the workspace to switch to. If omitted, shows an interactive selection.
- Behavior: Sets the specified workspace as the default, so subsequent commands use it without needing `--workspace`.
Examples:
```bash
# 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
# List all configured workspaces
twenty auth:list
# Switch default workspace interactively
twenty auth:switch
# Switch to a specific workspace
twenty auth:switch production
```
### 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 `: 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 `: 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 function:logs [appPath]` — Stream application function logs.
- Options:
- `-u, --functionUniversalIdentifier `: Only show logs for a specific function universal ID.
- `-n, --functionName `: Only show logs for a specific function name.
- `twenty function:execute [appPath]` — Execute a serverless function with a JSON payload.
- Options:
- `-n, --functionName `: Name of the function to execute (required if `-u` not provided).
- `-u, --functionUniversalIdentifier `: Universal ID of the function to execute (required if `-n` not provided).
- `-p, --payload `: JSON payload to send to the function (default: `{}`).
Examples:
```bash
# 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 function:logs
# Watch logs for a specific function by name
twenty function:logs -n my-function
# Execute a function by name (with empty payload)
twenty function:execute -n my-function
# Execute a function with a JSON payload
twenty function:execute -n my-function -p '{"name": "test"}'
# Execute a function by universal identifier
twenty function:execute -u e56d363b-0bdc-4d8a-a393-6f0d1c75bdcf -p '{"key": "value"}'
```
## 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 ` or by the `defaultWorkspace` setting.
Example configuration file:
```json
{
"defaultWorkspace": "prod",
"profiles": {
"default": {
"apiUrl": "http://localhost:3000",
"apiKey": ""
},
"prod": {
"apiUrl": "https://api.twenty.com",
"apiKey": ""
}
}
}
```
Notes:
- If a profile is missing, `apiUrl` defaults to `http://localhost:3000` until set.
- `twenty auth:login` writes the `apiUrl` and `apiKey` for the active workspace profile.
- `twenty auth:login --workspace custom-workspace` writes the `apiUrl` and `apiKey` for a custom `custom-workspace` profile.
- `twenty auth:switch` sets the `defaultWorkspace` field, which is used when `--workspace` is not specified.
- `twenty auth:list` shows all configured workspaces and their authentication status.
## 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:
```bash
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:
```bash
npx nx run twenty-sdk:dev
```
This will watch for changes and rebuild the `dist` folder automatically.
### Production Build
Build the SDK for production:
```bash
npx nx run twenty-sdk:build
```
### Running the CLI Locally
After building, you can run the CLI directly:
```bash
npx nx run twenty-sdk:start --
# Example: npx nx run twenty-sdk:start -- auth:status
```
Or run the built CLI directly:
```bash
node packages/twenty-sdk/dist/cli.cjs
```
### Resources
- See our [GitHub](https://github.com/twentyhq/twenty)
- Join our [Discord](https://discord.gg/cx5n4Jzs57)
