> ## Documentation Index
> Fetch the complete documentation index at: https://docs.upshiftcloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Sign in to a workspace, explore its data and build apps from your terminal with the twenty CLI.

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:

```bash filename="Terminal" theme={null}
npx twenty@latest --version
```

Or install it once globally and call `twenty` directly:

```bash filename="Terminal" theme={null}
npm install -g twenty
twenty --version
```

> [!WARNING]
>
> 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

Sign in with your browser. `--use` makes this connection the default one:

```bash filename="Terminal" theme={null}
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](https://docs.upshiftcloud.com/en/developers/extend/apps/getting-started/local-server.md), `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:

```bash filename="Terminal" theme={null}
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" theme={null}
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

```bash filename="Terminal" theme={null}
# 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" theme={null}
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](https://docs.upshiftcloud.com/en/developers/extend/apps/operations/sync-and-recovery.md) 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" theme={null}
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" theme={null}
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" theme={null}
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" theme={null}
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](https://github.com/exceev-technology/upshift/blob/main/packages/twenty-cli/docs/commands.md) covers every flag, permission, output format and exit code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.