CLI

Running the CLI

The twenty CLI connects to Twenty workspaces from your terminal. Use it to inspect metadata, read records, send API requests, and create, sync and debug apps. The CLI itself requires Node.js 24.5+. App development also needs a Node version supported by the installed SDK, see Quick Start. Run any command through npx, without a global installation:

npx twenty@latest --version

Or install it once globally and call twenty directly:

npm install -g twenty
twenty --version

The examples below use twenty. Replace twenty with npx twenty@latest if you did not install it globally. Run twenty commands for the full command list and twenty <command> --help for the options of one command.

Command	What it does
`auth`	Sign in, check and remove credentials
`remote`	List, select, rename and remove saved workspace connections
`metadata`	Inspect objects and fields
`data`	List and read records
`api`	Send raw REST or GraphQL requests
`open`	Open the workspace in your browser
`app`	Create, build, sync, debug and uninstall apps
`local`	Start, inspect, stop, upgrade and reset a local development environment
`doctor`	Diagnose the CLI, app SDK and workspace connection

Every command that talks to a workspace accepts --remote <name> to target a saved connection other than the default one, and --json for structured output.

Connecting to a workspace

twenty auth login --url https://acme.twenty.com --use
twenty auth status

Use your workspace’s address, or the server’s address for a local setup: http://localhost:2020 for the local development environment, http://localhost:3000 for a source checkout. You can copy the exact command from Settings > Developers > CLI. Browser sign-in needs Twenty 2.42 or later. Keep several connections by naming them:

twenty auth login --url http://localhost:2020 --name local
twenty remote list
twenty remote use local

In CI or scripts, pipe an API key instead of signing in with the browser:

printf '%s' "$TWENTY_API_KEY" | twenty auth login --with-token --url https://acme.twenty.com --name ci

You can also set TWENTY_API_URL and TWENTY_API_KEY for a single run without saving anything. Saved connections live in ~/.twenty/config.json. Commands select a workspace in this order:

An explicit --remote <name>, which overrides the target environment variables.
TWENTY_REMOTE, or the pair TWENTY_API_URL and TWENTY_API_KEY. Do not combine these two methods.
The saved default remote.

auth login --name <name> saves a connection but keeps an existing default. Add --use, or run twenty remote use <name>, to change the default.

Exploring your data

# Objects and fields
twenty metadata object list
twenty metadata field list companies

# Records
twenty data list companies --limit 5
twenty data list companies --filter 'employees[gte]:5000' --order-by 'employees[DescNullsLast]'
twenty data get people <id>

# Raw API requests
twenty api rest '/rest/companies?limit=5'
twenty api graphql --query '{ companies(first: 2) { edges { node { name } } } }'

# Open the workspace, or a page inside it
twenty open
twenty open settings/developers

Object names are exact API names, singular or plural (company or companies). Raw API writes run without a confirmation step, and your permissions in the workspace still apply.

Building an app

npx twenty@latest app init my-app
cd my-app
yarn install
npx twenty@latest app apply --create
npx twenty@latest app dev

app init writes a new project from the template. It does not install dependencies or contact a workspace.
app apply --create builds the app, registers it in the workspace, installs it and syncs its metadata.
app dev watches your source and syncs every successful build.

Other app commands:

Command	What it does
`app add`	Scaffold an object, field, logic function or other entity
`app build` / `app typecheck`	Build or typecheck the app locally
`app plan`	Preview the metadata changes an apply would make
`app apply`	Build, upload and sync the app
`app generate-client`	Regenerate the typed API client without syncing
`app pull`	Restore metadata, translations and stored dependencies
`app translations extract`	Extract translatable strings into `locales/` catalogs
`app publish`	Publish the app to npm or to a private Twenty registry
`app install`	Install an already registered app package in the workspace
`app uninstall`	Remove the app and everything it owns from the workspace

Definitions missing from your source are deleted from the workspace by default. Pass --no-prune to keep them. The workspace Custom application keeps them unless you pass --prune. Deleting objects or fields also deletes their data, so it requires confirmation. See Syncing & recovery for details.

Executing functions

Run a deployed logic function without triggering it through a route, a cron or a database event. Sync your local changes with app apply or app dev first.

twenty app exec --name create-new-post-card
twenty app exec --name create-new-post-card --payload '{"name": "Hello"}'

# Install and uninstall hooks
twenty app exec --post-install
twenty app exec --pre-install
twenty app exec --uninstall-hook

Executing functions requires a browser sign-in. API keys cannot execute them.

Watching function logs

Stream the output of your app’s logic functions as executions finish:

twenty app logs
twenty app logs --name create-new-post-card

It only shows new executions, not past ones.

Uninstalling an app

twenty app uninstall
twenty app uninstall --yes

This runs the app’s uninstall hook and deletes everything it owns, including its objects, fields and their data. The app stays registered, so twenty app apply can install it again.

Diagnosing problems

twenty doctor
twenty doctor --offline

doctor checks your Node version, which twenty binary is on your PATH, your saved connections and the app SDK, then reports what to fix.

Scripts and tests

Build output belongs to the CLI. Do not read .twenty/output/manifest.json or import internal build code; read data.manifest from twenty app build --json.

Full reference

The command reference covers every flag, permission, output format and exit code.

Developers

Apps

API

Self-Host

Contribute

UI Library

Running the CLI

Connecting to a workspace

Exploring your data

Building an app

Executing functions

Watching function logs

Uninstalling an app

Diagnosing problems

Scripts and tests

Full reference

​Running the CLI

​Connecting to a workspace

​Exploring your data

​Building an app

​Executing functions

​Watching function logs

​Uninstalling an app

​Diagnosing problems

​Scripts and tests

​Full reference

Running the CLI

Connecting to a workspace

Exploring your data

Building an app

Executing functions

Watching function logs

Uninstalling an app

Diagnosing problems

Scripts and tests

Full reference