Skip to content

The open alternative to Salesforce, designed for AI.

docs: align app guides with current CLI behavior (#29502)

Weiko366d41ecc3f9
diff --git a/packages/twenty-docs/developers/extend/apps/getting-started/concepts.mdx b/packages/twenty-docs/developers/extend/apps/getting-started/concepts.mdx
index 5d4e3720d19..b3810102632 100644
--- a/packages/twenty-docs/developers/extend/apps/getting-started/concepts.mdx
+++ b/packages/twenty-docs/developers/extend/apps/getting-started/concepts.mdx
@@ -86,7 +86,7 @@ your-app/
└─────────────────────────────────────────────────────────┘
```
-- **`twenty app dev`** — watches your source files and live-syncs changes to a connected Twenty server. The typed API client is regenerated automatically when the schema changes.
+- **`twenty app dev`** — watches your source files and live-syncs changes to a connected Twenty server. After a successful sync, it regenerates the typed API client when the schema or installed generator package changed, or generated client files are missing or changed. To refresh types after changing the workspace in the UI, run `twenty app generate-client`.
- **`twenty app build`** — compiles TypeScript, bundles logic functions and front components with esbuild, and produces a manifest.
- **Pre/post-install and uninstall hooks** — optional functions that run during installation or right before removal. See [Install Hooks](/developers/extend/apps/config/install-hooks) for details.
diff --git a/packages/twenty-docs/developers/extend/apps/getting-started/local-server.mdx b/packages/twenty-docs/developers/extend/apps/getting-started/local-server.mdx
index f48833e069c..365efc268ed 100644
--- a/packages/twenty-docs/developers/extend/apps/getting-started/local-server.mdx
+++ b/packages/twenty-docs/developers/extend/apps/getting-started/local-server.mdx
@@ -94,7 +94,7 @@ For a Twenty source checkout, the existing development environment also works:
```bash
bash packages/twenty-utils/setup-dev-env.sh
yarn start
-twenty auth login --url http://localhost:3000 --name local
+twenty auth login --url http://localhost:3000 --name local --use
```
Use the actual URL and port of your server. For subdomain workspaces, use the
@@ -103,8 +103,9 @@ workspace's hostname. For production deployment, follow the
## Project dependencies
-Install `twenty-sdk` and `twenty-client-sdk` as project dependencies. Install the
-`twenty` CLI globally, then run `twenty app typecheck`, `twenty app build`, and
-`twenty app apply` from the app directory.
+`twenty app init` declares `twenty-sdk`, `twenty-client-sdk`, and `twenty-ui` in
+`devDependencies`, but does not install them. With the `twenty` CLI installed
+globally, run `yarn install` from the generated app directory before running
+`twenty app typecheck`, `twenty app build`, or `twenty app apply`.
<PageBanner illustration="dev-self-host" />
diff --git a/packages/twenty-docs/developers/extend/apps/getting-started/project-structure.mdx b/packages/twenty-docs/developers/extend/apps/getting-started/project-structure.mdx
index fd7ec042766..5d36934bc6a 100644
--- a/packages/twenty-docs/developers/extend/apps/getting-started/project-structure.mdx
+++ b/packages/twenty-docs/developers/extend/apps/getting-started/project-structure.mdx
@@ -12,6 +12,7 @@ A new app generated by `twenty app init` looks like this:
```text filename="my-twenty-app/"
my-twenty-app/
package.json
+ yarn.lock # Created by app init; used by yarn install
src/
application-config.ts # Required — your app's entry point
default-role.ts # Permissions for logic functions
@@ -28,6 +29,7 @@ my-twenty-app/
__tests__/
application-config.test.ts # Unit test
global-setup.ts # Integration test setup (sync + uninstall)
+ run-twenty.ts # CLI subprocess helper for tests
schema.integration-test.ts # Integration test against a live server
.github/workflows/
ci.yml # Lint, typecheck, unit + integration tests
@@ -67,20 +69,9 @@ my-twenty-app/
## Dependencies
-The Twenty SDK and UI packages belong under `devDependencies`:
+`twenty app init` puts `twenty-sdk`, `twenty-client-sdk`, and `twenty-ui` under `devDependencies`, pinned to the SDK version selected by that CLI release. Keep the generated versions for a new app and keep all three packages in sync when upgrading. The CLI can receive patch releases independently, so its version need not match these packages.
-```json filename="package.json"
-{
- "dependencies": {},
- "devDependencies": {
- "twenty-client-sdk": "2.40.0",
- "twenty-sdk": "2.40.0",
- "twenty-ui": "2.40.0"
- }
-}
-```
-
-`twenty app init` pins `twenty-sdk`, `twenty-client-sdk`, and `twenty-ui` to its own version. Keep all three in sync when upgrading.
+The generated `engines.twenty` sets the minimum server version to that SDK's major and minor release. The generated GitHub Actions workflows pin the CLI separately.
- **`twenty-sdk`** provides app definitions, runtime helpers, and renderer integration. Use the separately installed **`twenty`** package for CLI commands and build/scaffolding tooling.
- **`twenty-client-sdk`** _is_ imported by your app code (`CoreApiClient`, `MetadataApiClient`, `RestApiClient`), but Twenty provides it at runtime — logic functions get it from a generated SDK layer, and front components resolve it from server-served modules. Your installed copy is only used for typechecking and the deploy-time build, so it never needs to ship in the deployed bundle.
diff --git a/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdx b/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdx
index 65d6c729b94..cacd5dbde08 100644
--- a/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdx
+++ b/packages/twenty-docs/developers/extend/apps/getting-started/quick-start.mdx
@@ -8,7 +8,7 @@ import { CardTitle } from "/snippets/card-title.mdx"
## Before you start
-Use Node.js 24.5+ or 26.5+ and Yarn 4 (via Corepack: `corepack enable`; on Node 26, install it first with `npm install -g corepack`). Install the CLI globally; your app keeps its own SDK dependencies.
+Use Node.js 24 (24.5+) or 26 (26.5.1+) and Yarn 4 (via Corepack: `corepack enable`; on Node 26, install it first with `npm install -g corepack`). Install the CLI globally; your app keeps its own SDK dependencies.
<Note>
Building Twenty apps is officially supported on Unix systems (macOS and Linux) only. On Windows, work inside WSL 2.
@@ -30,9 +30,12 @@ yarn install
Use an existing workspace, or start a [local server](/developers/extend/apps/getting-started/local-server), then sign in:
```bash
-twenty auth login --url https://your-workspace.twenty.com --name dev
+twenty auth login --url https://your-workspace.twenty.com --name dev --use
+twenty auth status --remote dev
```
+`--name dev` saves the connection as `dev`; `--use` makes it the default for the commands below. To target it explicitly, append `--remote dev`. Environment variables can override the default, see [workspace selection](/developers/extend/apps/operations/cli#connecting-to-a-workspace).
+
## Sync your changes
For the first sync, explicitly allow registration and installation:
diff --git a/packages/twenty-docs/developers/extend/apps/operations/cli.mdx b/packages/twenty-docs/developers/extend/apps/operations/cli.mdx
index 9456b6866cb..abde284b95f 100644
--- a/packages/twenty-docs/developers/extend/apps/operations/cli.mdx
+++ b/packages/twenty-docs/developers/extend/apps/operations/cli.mdx
@@ -7,9 +7,9 @@ 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. It needs **Node.js 24.5+ or 26.5+**.
+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 installing anything:
+Run any command through `npx`, without a global installation:
```bash filename="Terminal"
npx twenty@latest --version
@@ -22,7 +22,7 @@ npm install -g twenty
twenty --version
```
-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.
+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 |
| ---------- | ----------------------------------------------------------- |
@@ -65,6 +65,14 @@ printf '%s' "$TWENTY_API_KEY" | twenty auth login --with-token --url https://acm
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"
diff --git a/packages/twenty-docs/developers/extend/apps/operations/publishing.mdx b/packages/twenty-docs/developers/extend/apps/operations/publishing.mdx
index b967226b298..c320e67ec91 100644
--- a/packages/twenty-docs/developers/extend/apps/operations/publishing.mdx
+++ b/packages/twenty-docs/developers/extend/apps/operations/publishing.mdx
@@ -61,11 +61,11 @@ twenty auth login --url https://your-twenty-server.com --name production
Build and upload your app to the server in one step:
```bash filename="Terminal"
-twenty app publish --private
-# To deploy to a specific remote:
-# twenty app publish --private --remote production
+twenty app publish --private --remote production
```
+The explicit `--remote production` selects the connection saved above, even if another remote is your default. Saving a named remote does not switch an existing default.
+
### Sharing a deployed app
Tarball apps are not listed in the public marketplace, so other workspaces on the same server won't discover them by browsing. To share a deployed app:
@@ -83,7 +83,7 @@ When updating an already deployed tarball app, the server requires the `version`
To release an update:
1. Bump the `version` field in your `package.json` (e.g. `1.2.3` → `1.2.4`, `1.3.0`, or `2.0.0`)
-2. Run `twenty app publish --private` (or `twenty app publish --private --remote production`)
+2. Run `twenty app publish --private --remote production`
3. Workspaces that have the app installed and enabled auto-upgrade for it (in the app's General tab) are upgraded automatically in the background; the others will see the upgrade available in their settings
<Note>
@@ -389,19 +389,21 @@ Go to the **Settings > Applications** page in Twenty, where both marketplace and
{/* TODO: add screenshot of the UI when the app is registered */}
-You can also install apps from the command line:
+From the app directory, install its published version into the target workspace:
```bash filename="Terminal"
-twenty app install
+twenty app install --remote production
```
+Use the name of the remote for the workspace where you want the app installed. To install without a local project, pass `--universal-identifier <id>`.
+
<Note>
The server enforces semver versioning on install, mirroring the rules on deploy:
- Installing the same version that is already installed in your workspace is rejected with an `APP_ALREADY_INSTALLED` error.
- Installing a lower version than the one currently installed is rejected with a `CANNOT_DOWNGRADE_APPLICATION` error.
-To install a newer version, deploy or publish it first, then re-run `twenty app install`.
+To install a newer version, deploy or publish it first, then re-run `twenty app install --remote production`.
</Note>
diff --git a/packages/twenty-docs/developers/extend/apps/operations/sync-and-recovery.mdx b/packages/twenty-docs/developers/extend/apps/operations/sync-and-recovery.mdx
index aee1ee58693..3ba6db90ad1 100644
--- a/packages/twenty-docs/developers/extend/apps/operations/sync-and-recovery.mdx
+++ b/packages/twenty-docs/developers/extend/apps/operations/sync-and-recovery.mdx
@@ -21,7 +21,7 @@ Local app development revolves around **syncing**: the CLI rebuilds your manifes
| ------------------------------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| Iterate locally with live sync | `twenty app dev` | Watches your files and syncs on every change. |
| Sync once and exit (CI, scripts, hooks) | `twenty app apply` | One build + sync, then exits. Add `--yes` to skip the destructive-change confirmation. |
-| Preview changes **without applying them** | `twenty app plan` | Computes and prints the diff; writes nothing. |
+| Preview changes **without applying them** | `twenty app plan` | Builds locally and prints the diff; does not change the workspace. |
| Sync without deleting anything | `twenty app apply --no-prune` | Creates and updates only: entities that exist in the workspace but not in your source are left alone. Also accepted by `plan` and `dev`. |
| Prune the workspace Custom application | `twenty app apply --prune` | That app keeps entities missing from source unless you pass `--prune`. Also accepted by `plan` and `dev`. |
| Regenerate local source from the workspace | `twenty app pull` | **Experimental.** Restores define files, translations and stored dependencies. See below. |
@@ -88,7 +88,7 @@ Plan: 1 to add, 1 to change, 0 to destroy.
A plan:
-- **Writes nothing** — no metadata migration, no application record update, no default role/tab changes, and no API client generation.
+- **Does not change the workspace**, no metadata migration, application record update, or default role/tab changes. It builds a local snapshot but does not regenerate the API client.
- Returns the **same diff** a real sync would apply, so you can review created/updated/deleted entities up front.
- Is useful before a risky change, when reviewing an AI-generated change, or in a script that should fail if an unexpected change is about to land.
@@ -146,7 +146,7 @@ Each entity goes to the file that already defines it, so a second pull rewrites
**Dependency files.** When the stored `package.json` or `yarn.lock` changes, pull replaces the local file and reports any overwritten local edits. If the remote file has not changed since the previous pull, local edits are kept. A missing remote file does not delete its local counterpart. When the exported package omits `twenty-sdk`, as the workspace Custom application does, pull retains your local SDK dependency so CLI commands can still load the project. Dependency files, metadata and the baseline are written together and rolled back together if a write fails.
-Run `yarn install` after pulling dependency changes. Pull does not install packages, run package scripts or regenerate the typed client.
+Run `yarn install` after pulling dependency changes. Pull installs dependencies only when creating a new project, before restoring the remote files; it does not reinstall them after replacing `package.json` or `yarn.lock`. Pull does not regenerate the typed client. Run `twenty app generate-client` when you need updated workspace types.
**What it does not write:**
@@ -174,12 +174,12 @@ When local metadata looks wrong, escalate in this order and stop as soon as you'
2. **Preview the plan.** Run `twenty app plan` to see exactly what the next sync intends to change, without applying it.
3. **Read the named error.** If a sync fails, note the metadata type and `universalIdentifier` in the message (see above) and locate that entity in your manifest. A conflict usually points to a duplicated or re-used identifier.
4. **Uninstall and reinstall.** `twenty app uninstall`, then sync again (`twenty app dev`). This rebuilds the app's metadata from a clean slate while keeping the rest of your workspace intact.
-5. **Full reset (last resort).** resetting your Docker or repository development database, then re-seed and re-sync.
+5. **Full reset (last resort).** For a CLI-managed local environment, run `twenty local reset`, then `twenty local start` and reconnect before syncing again. For a source checkout, reset and re-seed its development database instead.
<Warning>
- resetting your Docker or repository development database deletes **all** data
- in your local instance — every workspace, record, and app. Only use it once
- the earlier steps have failed.
+ Resetting your local environment or repository development database deletes
+ **all** data in your local instance, every workspace, record, and app. Only
+ use it once the earlier steps have failed.
</Warning>
<Note>
diff --git a/packages/twenty-docs/developers/extend/apps/operations/testing.mdx b/packages/twenty-docs/developers/extend/apps/operations/testing.mdx
index 7fb894fb8be..460e993476d 100644
--- a/packages/twenty-docs/developers/extend/apps/operations/testing.mdx
+++ b/packages/twenty-docs/developers/extend/apps/operations/testing.mdx
@@ -176,7 +176,7 @@ You can also run type checking on your app without running tests:
twenty app typecheck
```
-This runs `tsc --noEmit` against your app's `tsconfig.json` and reports any type errors. Scaffolded apps also ship a `yarn typecheck` script that covers test files too (`tsconfig.spec.json`).
+This checks your app's `tsconfig.json` with its installed TypeScript compiler, without emitting files, and reports any type errors. Scaffolded apps also ship a `yarn typecheck` script that covers test files too (`tsconfig.spec.json`).
## CI with GitHub Actions