The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
docs(cli): describe installing the twenty package from npm (#27492)
Weikob651595dd3bc
diff --git a/packages/twenty-cli/README.md b/packages/twenty-cli/README.mdindex 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```bashtwenty doctor --offline-twenty auth login --url https://acme.twenty.com+twenty auth login --url https://acme.twenty.com --usetwenty metadata object listtwenty data list companies --limit 5twenty 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:+```bashtwenty app init my-appcd my-appyarn installtwenty 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 theyalso 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 installedSDK authoring exports and TypeScript compiler. Configuration and project-referenceerrors 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, permissionsand 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` fordiff --git a/packages/twenty-cli/docs/commands.md b/packages/twenty-cli/docs/commands.mdindex 0bf8e0671f1..2b3d5d8036c 100644--- a/packages/twenty-cli/docs/commands.md+++ b/packages/twenty-cli/docs/commands.md@@ -39,8 +39,6 @@ twenty remote use devA remote is a named workspace connection. Browser login requires an interactiveterminal 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. RESTuses GET by default. `--body` accepts JSON inline, `@file.json`, or `-` for stdinand requires an explicit `--method`.@@ -100,8 +98,8 @@ twenty api graphql --query @query.graphql --variables @variables.jsonGraphQL 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.