Skip to content

The open alternative to Salesforce, designed for AI.

docs(cli): describe installing the twenty package from npm (#27492)

Weikob651595dd3bc
diff --git a/packages/twenty-cli/README.md b/packages/twenty-cli/README.md
index fa20b6e610b..66f88a83d9c 100644
--- a/packages/twenty-cli/README.md
+++ b/packages/twenty-cli/README.md
@@ -3,43 +3,47 @@
Work with [Twenty](https://twenty.com) from your terminal: connect to workspaces,
inspect metadata and records, send API requests, and develop applications.
-Build this CLI from source using the instructions below. It supports
-development-app deployment. Application publishing is not supported.
+## Install
-## Get started
-
-Use Node.js 24.5 or later within Node 24 and the repository's Yarn setup. From
-the repository root:
+The CLI needs Node.js 24.5 or later.
```bash
-yarn nx build twenty-cli
-node packages/twenty-cli/dist/cli.cjs --help
+npm install -g twenty
+twenty --version
```
-The examples below use `twenty` for the built executable. Run it as
-`node /absolute/path/to/twenty/packages/twenty-cli/dist/cli.cjs`.
+## Get started
```bash
twenty doctor --offline
-twenty auth login --url https://acme.twenty.com
+twenty auth login --url https://acme.twenty.com --use
twenty metadata object list
twenty data list companies --limit 5
twenty open
```
-Replace the example URL with your workspace's address. Workspace commands do
-not require an application project. Use `--remote <name>` to select another
-saved connection and `--json` for a structured result.
+Replace the example URL with your workspace's address. `--use` makes this
+connection the default, even when another saved connection already is one. Use
+`--remote <name>` to select another saved connection and `--json` for a
+structured result. Saved connections live in `~/.twenty/config.json`.
+
+Browser sign-in is supported on Twenty 2.42 and later. On older servers, sign in
+with an [API key](docs/commands.md#connections-and-authentication) instead.
## Develop an application
+App projects pin Yarn 4 in `packageManager`. Run `corepack enable` once so
+`yarn` uses that version; if `corepack` is missing, install it with
+`npm install -g corepack`. These steps use the default connection;
+`twenty auth status` shows which one that is:
+
```bash
twenty app init my-app
cd my-app
yarn install
twenty app build
-twenty app apply --create --remote dev
-twenty app dev --remote dev
+twenty app apply --create
+twenty app dev
```
`app init` writes files without installing dependencies. `app build` checks the
@@ -53,28 +57,30 @@ preserve them. Object and field deletions require confirmation because they
also delete stored data. Pull can overwrite local edits; read its
[reconciliation rules](docs/commands.md#pull-an-app) before using it.
+Apps created with `app init` declare the oldest Twenty version they support in
+`engines.twenty`. `app exec` runs functions as the signed-in user, so it needs a
+browser sign-in and Twenty 2.46 or later. With a browser sign-in, `app uninstall`
+also needs Twenty 2.46 or later; on earlier versions, use an API key for it.
+
## CLI and app dependencies
-The CLI is intended to be installed globally, separately from each app. Apps
-keep `twenty-sdk` as a development dependency for authoring and build-time APIs,
-`typescript` for checks, and
-`twenty-client-sdk` when they use a generated API client. Neither apps nor SDK
-packages need `twenty` in their dependencies or devDependencies. CI can pin its
-CLI installation separately.
+The CLI is installed globally, separately from each app. Apps keep `twenty-sdk`
+as a development dependency for authoring and build-time APIs, `typescript` for
+checks, and `twenty-client-sdk` when they use a generated API client. Neither
+apps nor SDK packages need `twenty` in their dependencies or devDependencies. In
+CI, install a pinned version with `npm install -g twenty@<version>`.
The CLI owns builds and filesystem operations. It uses the app's installed
SDK authoring exports and TypeScript compiler. Configuration and project-reference
errors fail builds. See [build requirements](docs/commands.md#build-and-check-an-app)
for supported SDK exports and compiler configuration.
-Use `twenty doctor --offline` to inspect which package owns the `twenty`
-executable on PATH. A missing project-local CLI is normal.
-
## Documentation
- [Command reference](docs/commands.md), authentication, flags, output, permissions
and recovery for each workflow.
-- [Contributing](CONTRIBUTING.md), package structure, builds, tests and release checks.
+- [Contributing](CONTRIBUTING.md), building from source, package structure, tests
+ and releases.
- [Application tooling](src/app/README.md), module responsibilities and invariants.
Run `twenty commands` for the command inventory or `twenty <command> --help` for
diff --git a/packages/twenty-cli/docs/commands.md b/packages/twenty-cli/docs/commands.md
index 0bf8e0671f1..2b3d5d8036c 100644
--- a/packages/twenty-cli/docs/commands.md
+++ b/packages/twenty-cli/docs/commands.md
@@ -39,8 +39,6 @@ twenty remote use dev
A remote is a named workspace connection. Browser login requires an interactive
terminal and saves a user OAuth session after verifying it with the server.
-Workspace commands do not require an app project or register an application in
-that workspace. Application deployment is a separate operation.
For scripts, pass an API key through standard input:
@@ -87,8 +85,8 @@ twenty api graphql --query '{ companies(first: 2) { edges { node { name } } } }'
twenty api graphql --metadata --query '{ currentWorkspace { displayName } }'
```
-Both commands use the selected connection without an app project. REST paths
-stay inside its API URL; credentials are not sent to an arbitrary host. REST
+Both commands use the selected connection. REST paths stay inside its API URL;
+credentials are not sent to an arbitrary host. REST
uses GET by default. `--body` accepts JSON inline, `@file.json`, or `-` for stdin
and requires an explicit `--method`.
@@ -100,8 +98,8 @@ twenty api graphql --query @query.graphql --variables @variables.json
GraphQL uses the core endpoint by default and the metadata endpoint with
`--metadata`. `--query` accepts a document inline, `@file.graphql` or `-`;
`--variables` accepts a JSON object through the same input forms. Only one option
-can read stdin. Mutations and REST writes execute directly, without the app
-plan/apply confirmation flow. Server permissions still apply.
+can read stdin. Mutations and REST writes execute directly, without a
+confirmation step. Server permissions still apply.
Human output displays the response body. In JSON mode, REST returns status,
selected response headers and body in `data`; GraphQL returns its data there.