Skip to content

The open alternative to Salesforce, designed for AI.

7.8 KB
Raw Blame
---
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" />