The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
---
title: CLI
description: Sign in to a workspace, explore its data and build apps from your terminal with the twenty CLI.
---
import { PageBanner } from "/snippets/page-banner.mdx"
## 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](/developers/extend/apps/getting-started/quick-start#before-you-start).
Run any command through `npx`, without a global installation:
```bash filename="Terminal"
npx twenty@latest --version
```
Or install it once globally and call `twenty` directly:
```bash filename="Terminal"
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
Sign in with your browser. `--use` makes this connection the default one:
```bash filename="Terminal"
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](/developers/extend/apps/getting-started/local-server), `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:
```bash filename="Terminal"
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:
```bash filename="Terminal"
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:
1. An explicit `--remote <name>`, which overrides the target environment variables.
2. `TWENTY_REMOTE`, or the pair `TWENTY_API_URL` and `TWENTY_API_KEY`. Do not combine these two methods.
3. 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
```bash filename="Terminal"
# 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
```bash filename="Terminal"
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](/developers/extend/apps/operations/sync-and-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.
```bash filename="Terminal"
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:
```bash filename="Terminal"
twenty app logs
twenty app logs --name create-new-post-card
```
It only shows new executions, not past ones.
## Uninstalling an app
```bash filename="Terminal"
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
```bash filename="Terminal"
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](https://github.com/twentyhq/twenty/blob/main/packages/twenty-cli/docs/commands.md) covers every flag, permission, output format and exit code.
<PageBanner illustration="card-page-cli" />