CLI - Upshift Documentation

The twenty CLI connects to Upshift workspaces from your terminal. Use it to inspect metadata, read records, send API requests, and create, sync and debug apps. It needs Node.js 24.5 or later.

Running the CLI

Run any command through npx, without installing anything:

npx twenty@latest --version

Or install it once globally and call twenty directly:

npm install -g twenty
twenty --version

Inside an app project, use npx twenty@latest, not npx twenty. Apps depend on twenty-sdk, which still ships an older twenty binary, and npx twenty runs that local binary instead of this CLI.

The examples below use twenty. Prefix them 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
`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://crm.yourcompany.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 Docker server, http://localhost:3000 for a source checkout. You can copy the exact command from Settings > Developers > CLI. Browser sign-in needs Upshift 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://crm.yourcompany.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.

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`	Write the installed app’s metadata back to local source
`app translations extract`	Extract translatable strings into `locales/` catalogs
`app publish`	Publish the app to npm or to a private Upshift 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-delete to keep them. 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.

Full reference

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

​Running the CLI

​Connecting to a workspace

​Exploring your data

​Building an app

​Executing functions

​Watching function logs

​Uninstalling an app

​Diagnosing problems

​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

Full reference