The open alternative to Salesforce, designed for AI.
Command reference
For available commands and flags, run twenty commands or
twenty <command> --help. This reference describes behavior, permissions and
failure recovery. See the README to build and start the CLI.
- Connections and authentication
- Raw API requests
- Network proxies
- Doctor
- Open
- Metadata
- Records
- Local development environment
- App init and add
- Build and typecheck
- Plan, apply and dev
- Pull and uninstall
- Function execution and logs
- Expired browser sessions
- Output and exit codes
Run a local development environment
twenty local start
twenty local status
twenty auth login --url http://localhost:2020 --name local
twenty local logs --no-follow
twenty local stop
local runs the full Twenty development environment, including the web UI,
API, worker and databases. Docker must be installed and running with a local
socket context; remote Docker endpoints are rejected. These commands need
neither an app directory nor a saved workspace connection. They do not sign in,
change remotes or apply an app.
start [version] creates an instance or starts the existing one, and waits up
to five minutes for /healthz. For a new instance, version selection is:
explicit version or image tag, the highest published version matching the nearest
package.json's engines.twenty, then latest when no range exists. A failed
lookup or unmatched range is an error, never a fallback to another version.
Versions such as 2.53 and 2.53.1 select v2.53 and v2.53.1, respectively;
2.53 keeps the floating minor tag. Other image tags are used as given.
New instances pull the selected image before creation, including when the tag
is cached locally. Existing instances keep their image and port; use upgrade to change versions.
Compatibility with engines.twenty uses the existing image's APP_VERSION.
A missing, invalid or incompatible version warns without preventing startup.
A readiness failure leaves the container and data in place for diagnosis.
New instances bind to loopback on port 2020. Use --port <port> when creating
one. --test selects the separate test instance, default port 2021; pass it
to every command intended for that instance. Data and file storage use separate
named volumes for each instance. Existing SDK development containers and their
volumes are reused.
twenty local start 2.53.1 --test
twenty local logs --test --lines 100 --no-follow
twenty local upgrade 2.53.1 --test
twenty local reset --test --yes
status reports not-created, stopped, starting or healthy; unavailable
Docker is an error. logs follows by default; --no-follow prints recent logs
and exits. It supports human or NDJSON output, with a terminal result or error;
other local commands support human or JSON output. Ctrl+C cancels the CLI
operation, without stopping the environment or deleting data.
stop preserves the container and all data. upgrade [version] uses the same
version selection as a new start. It pulls the image before stopping the old
instance, then recreates it with the same ports, named volumes and user-provided
environment overrides. The old container is kept until the replacement is created.
If creation fails or is cancelled, the CLI restores the old container and its
previous running state. If the image digest is unchanged, no restart occurs.
Custom storage layouts are rejected. Data volumes survive a failed upgrade,
but database migrations are not automatically rolled back.
reset removes the selected container and its database, analytics and file
volumes. It requires confirmation, or --yes in scripts. It does not affect
other containers or saved remote credentials. Run start afterward for a fresh
instance. This development environment is not a production deployment tool.
Connections and authentication
twenty auth login --url https://acme.twenty.com
twenty auth status
The connection is named default when neither --name nor --remote is supplied.
Run twenty auth login again to sign in to that saved URL. To keep several
connections, give each a name:
twenty auth login --url https://acme.twenty.com --name dev --use
twenty auth status --remote dev
twenty remote list
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.
For scripts, pass an API key through standard input:
printf '%s' "$TWENTY_API_KEY" | twenty auth login --with-token --url https://acme.twenty.com --name ci
Credentials and remote settings are saved in ~/.twenty/config.json, with
owner-only file permissions. Login validates credentials before saving them.
--use makes the remote the default; the first remote also becomes the default.
Creating the connection named default does not switch an existing default
remote unless you pass --use.
Use twenty auth login --remote dev to sign in again to a saved URL. Changing an
existing remote's URL requires --replace.
Commands select a workspace in this order:
--remote <name>, ignoring environment target settings with a warning.TWENTY_REMOTE, which cannot be combined with either API environment variable.TWENTY_API_URLandTWENTY_API_KEY, which must both be set and are not saved.- The saved default remote.
twenty remote rename dev development
twenty auth logout --remote development
twenty remote remove development
Logout forgets saved credentials but keeps the remote. Removing a remote deletes
both. Neither command revokes the server-side credential. twenty auth token
prints the selected credential for use in another tool; its output is a secret,
including in JSON mode.
--no-input disables prompts and browser opening. JSON/NDJSON output, redirected
stdin and CI also disable interaction. Pass required values and explicit
command-specific approvals, such as app apply --create or --yes, in scripts.
Disabling prompts does not approve an operation.
Raw API requests
twenty api rest '/rest/companies?limit=5'
twenty api graphql --query '{ companies(first: 2) { edges { node { name } } } }'
twenty api graphql --metadata --query '{ currentWorkspace { displayName } }'
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.
twenty api rest /rest/companies --method POST --body '{"name":"Example"}'
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 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.
HTTP and GraphQL errors use the standard error envelope. Responses are bounded
by the transport's 16 MiB limit; raw requests do not paginate automatically.
Network proxies
API requests, browser sign-in requests and app uploads honor HTTP_PROXY,
HTTPS_PROXY and NO_PROXY (also their lowercase equivalents, which take
precedence). HTTP_PROXY also covers HTTPS when HTTPS_PROXY is unset.
Use NO_PROXY=localhost,127.0.0.1 to bypass a proxy for local development,
or NO_PROXY=* to bypass it for all hosts. Proxies must support HTTP CONNECT.
For a corporate certificate authority, set NODE_EXTRA_CA_CERTS before starting
the CLI. TLS certificate verification stays enabled.
Diagnose your setup
twenty doctor
twenty doctor --remote staging --path ./my-app --json
twenty doctor --offline
doctor checks the running CLI and Node version, executable ownership and precedence on PATH, configuration, the selected connection, and an app's installed SDK authoring exports. It works without an app or saved remote; unavailable optional checks are marked skipped. Use --path to require a specific app. PATH inspection does not execute binaries or inspect shell aliases, functions or command caches; package-manager wrappers whose owner cannot be determined are reported as unknown.
By default it sends one read-only request to the selected workspace's metadata endpoint to check access. This does not prove access to every object or app operation. --offline disables network requests. Doctor never imports app or SDK code, builds an app, installs packages, repairs files, or refreshes credentials. An expired OAuth access token skips the network check: it produces a warning when a refresh token is saved (renewal remains unverified), or a failure when there is none. Renew through twenty auth status for the same remote, or sign in again.
Each check has an id, status (pass, warning, fail, or skipped), message, and optional code, hint and details. Failed checks exit 1 with DOCTOR_FAILED; JSON includes the checklist in error.details.checks. Otherwise exit 0, with the same checklist in data.checks, including warnings and skipped checks. Human output includes the full checklist in either case. Ctrl+C exits 130. Output omits credentials, server response bodies and user identity information, but includes local paths and the selected API URL.
Open the workspace
twenty open
twenty open settings/applications
twenty open --remote staging --url-only --json
open asks the selected workspace for its web address, which is its custom domain when one is enabled and its subdomain otherwise. It then opens that address, or a page inside it, in your default browser. The address carries no credentials, so sign in to the workspace in the browser if needed. A browser only opens in an interactive terminal: with --no-input, JSON output, redirected stdin or in CI, the command stops with USAGE (exit 2) unless --url-only is set, which prints the address instead. A page is a path inside the workspace; one that would lead to another site is refused with USAGE.
If the workspace returns no web address, open uses the frontend origin from
the server's OAuth discovery document. It drops the authorization path, query,
fragment and any URL credentials. Invalid addresses and failed metadata
authentication still stop the command.
Inspect the data model
twenty metadata object list
twenty metadata object describe companies
twenty metadata field list companies --all
twenty metadata field describe companies tier --json
Object arguments accept exact, case-sensitive singular or plural API names. Field arguments accept exact API names. Labels are never matched, and ambiguous names fail with AMBIGUOUS_RESOURCE (exit 2). Missing names return NOT_FOUND (exit 4).
Object describe shows object properties. Use field list to inspect its fields; system fields are hidden unless --all is present. Field describe can inspect a named system field directly. Each field reports its own owner, independently of its object. If application names cannot be read, Custom remains identifiable and other owners are reported as unknown with a warning; ownership is not a permission check.
Inspection reads every metadata page before resolving names, so a match on an early page cannot hide an ambiguity on a later one. Each object/field traversal is capped at 10,000 items or 16 MiB of node data; exceeding either limit fails instead of returning incomplete metadata. Requests use the selected connection and fetch live metadata on every invocation. Human output shows labels, constraints, options and relationships; JSON also preserves IDs, universal identifiers, settings and relationship endpoints.
Read records
twenty data list companies --limit 20
twenty data list companies --filter 'employees[gte]:5000' --order-by 'employees[DescNullsLast]'
twenty data get people <id> --json
twenty data list people --all --format ndjson
These commands resolve the same exact singular/plural API names as metadata inspection, including custom objects, and reuse the selected connection. They require access to object metadata as well as the records. data get reads one record with one level of related records; it does not recursively expand or paginate relations.
data list reads one page by default, with a default --limit of 50 and a maximum of 200. --cursor passes the opaque REST starting_after cursor. --filter and --order-by pass REST expressions unchanged; server ordering and its ID tie-breaker are preserved. Every result includes page information, and human output shows a next-page command. Pagination is not a database snapshot; concurrent writes can change results or totals during traversal.
--fields name,employees selects human table columns only. Tables shorten cells longer than 60 characters and display absent values as -. JSON and NDJSON retain full records, including composite values and relation identifiers.
--all reads every remaining page, including when starting from --cursor. Human/JSON results are limited to 10,000 records and 16 MiB of serialized payload; human tables are also bounded. Exceeding a limit returns RESULT_LIMIT_EXCEEDED (exit 2), with no partial success. Every HTTP response is separately limited to 16 MiB, including in NDJSON mode.
Use explicit --format ndjson for larger traversals. It emits numbered start, record, page progress, and terminal result/error events, reading one page at a time and waiting for stdout when the reader is slow. resumeCursor advances only after a complete page has been written. After a partial page or a failure, resume with the last reported cursor and the same filter/order; records from the partial page may repeat. With no completed page, use the original cursor or restart without one. A stream without a terminal event is incomplete. Without --all, NDJSON still reads only one page.
Create an app
twenty app init my-app
twenty app init billing --path ./apps/billing --display-name Billing --json
app init creates a new app from the template bundled with the CLI, with fresh universal identifiers and twenty-client-sdk, twenty-sdk and twenty-ui pinned to the exact version the CLI was built with. It needs no installed SDK, saved remote or network access, and it only writes files: it does not install dependencies, create a Git repository, start a server, sign in or sync anything. A published CLI also writes a yarn.lock, so the first yarn install uses exact, integrity-checked versions. The next steps it prints, and returns as data.nextSteps in JSON, cover the rest, and name the remote when you pass --remote.
The name must be a valid npm package name, otherwise the command fails with INVALID_APP_NAME (exit 2). The app is created in ./<name> unless --path says otherwise; --display-name and --description set what Twenty shows. The target must not exist yet or be an empty directory; anything else fails with APP_PATH_UNAVAILABLE (exit 6) and nothing is written. The template is rendered in a hidden sibling directory and moved into place only after every placeholder was filled, so a failure or Ctrl+C does not leave a half-created app behind. An existing empty directory is filled with create-only writes, so a file that appears there meanwhile is never overwritten.
New apps declare engines.twenty as >= the template release version. The server
checks this range against the workspace's completed upgrade version on apply.
Upgrade the workspace before deploying a newer template, including during local
development. Adjust the range only after testing the app against older versions.
The integration tests of a new app run against a workspace through this CLI.
src/__tests__/global-setup.ts uninstalls any previous copy, runs
twenty app apply --create before the tests and twenty app uninstall --yes
after them, through src/__tests__/run-twenty.ts. That helper runs twenty with
--json, returns its result, and passes its progress through. It skips the
binaries a package manager puts first on PATH inside yarn test, so the
globally installed CLI runs; set TWENTY_CLI to use another executable.
Credentials come from TWENTY_API_URL and TWENTY_API_KEY,
which the template's Vitest config sets.
Add definitions to an app
twenty app add
twenty app add object --name invoice --name-plural invoices --no-input
twenty app add object --name invoice --name-plural invoices --create-view --create-navigation-menu-item --create-page-layout --no-input
twenty app add field --name amount --type NUMBER --object <object-universal-identifier> --json
twenty app add logic-function --name send-invoice --no-input
twenty app add front-component --name invoice-panel --no-input
app add creates definitions from the CLI's templates.
It discovers the containing app, or accepts --path <app-directory>. No sign-in
or workspace connection is needed. Use object, field, logic-function or
front-component.
Objects can also create optional UI definitions:
--create-view: a table view containing the object's name field.--create-navigation-menu-item: a navigation item pointing to the object.--create-page-layout: a record page layout with Fields and Timeline tabs, plus the fields view required by its Fields widget.
Combine these flags to select what to generate without a companion prompt.
Without any creation flags, a human interactive terminal asks whether to create
all three, defaulting to No. Press Enter or answer No to create only the object.
With --no-input, --json, redirected stdin or CI, companions are created only
when explicitly requested by flags. These flags are valid only for objects.
View, navigation and layout files go under src/views,
src/navigation-menu-items and src/page-layouts.
Files are created under src/objects, src/fields, src/logic-functions and
src/front-components, with kebab-case filenames and fresh universal UUIDs.
Existing files are never replaced, including filename collisions after case
normalization. Symlinked destination paths are refused. Both cases exit 6.
JSON returns app-relative paths in data.createdPaths.
Omitted values are prompted only in a human interactive terminal. With --json,
--no-input, redirected stdin or CI, required values must be supplied explicitly
or the command exits 2 before creating files. Labels default to the name; fields
default to TEXT. --object requires the parent's universal identifier, not its
workspace database ID. Relations additionally require --target-object and
--target-field; --relation-type defaults to ONE_TO_MANY and --on-delete
to CASCADE. The command does not create the reverse field or
check that these identifiers exist in a workspace.
Review the generated definition and its type-specific settings, then run
twenty app build and twenty app plan. Generation does not install or apply
anything. Cancellation before the file is created exits 130; existing app files
stay untouched, although empty parent directories can remain.
Build and check an app
twenty app build
twenty app typecheck
twenty app build --path ./apps/billing --json
These commands run inside an app project: the nearest folder, from the current one upwards, whose package.json depends on twenty-sdk. Pass --path to choose another app. In a folder that contains several apps, --path is required, and the error lists them.
The CLI owns manifest generation, bundling and typechecking. It uses the app's
installed twenty-sdk authoring exports (define and front-component, SDK
>=1.23.0). An app without an installed SDK fails with SDK_NOT_INSTALLED;
missing or unsupported authoring
exports fail with SDK_SOURCE_UNSUPPORTED. A Node version below every version the SDK's
engines.node range accepts fails with NODE_VERSION_UNSUPPORTED; any other
Node version outside that range continues with a NODE_VERSION_UNTESTED
warning, which doctor also reports. The CLI never installs dependencies or
substitutes another SDK. Yarn Plug'n'Play is not supported; use
nodeLinker: node-modules.
Typechecking uses typescript installed in the app or its workspace, never the
global CLI's parser dependency. Missing TypeScript fails with
TYPESCRIPT_NOT_INSTALLED. Configuration errors and unbuilt project references
fail with TYPECHECK_FAILED. For example, a project with an unbuilt reference
to tsconfig.spec.json can report TS6305: remove an unintended reference, or
build the referenced project before checking the app. Changing compiler versions
can also change diagnostics.
Builds run in a separate worker process. That process does not receive the CLI's
connections or credentials: TWENTY_API_URL, TWENTY_API_KEY, TWENTY_REMOTE
and every TWENTY_* token, key, secret or password variable are removed from its
environment. App and SDK output becomes PROJECT_OUTPUT diagnostics; an app
that exits the process fails with WORKER_FAILED. This separates output and
process state; it is not a sandbox for untrusted code.
app build produces a temporary snapshot under .twenty/cli/snapshots, reports
its files, upload roles, sizes, SHA-256 checksums, content hash and manifest, then
deletes the snapshot. Nothing is uploaded or kept. app typecheck checks the
project without writing files. Build and type errors exit 1 with diagnostics in
error.details.diagnostics. Worker failures report the underlying code in
error.details.toolingErrorCode. Worker process failures use
error.details.workerErrorCode. Ctrl+C cancels the worker and exits 130; a
worker that does not stop within a few seconds is killed. The JSON sdk object
identifies the app's installed authoring SDK version.
The CLI version determines build rules, including derived permission identifiers.
Different tooling versions can produce different manifests. Run twenty app plan
and inspect the changes before applying an app with a different tooling version.
Preview app changes
twenty app plan --remote dev
twenty app plan --path ./apps/billing --no-prune --json
twenty app plan --prune
app plan builds once with the CLI pipeline, releases the temporary snapshot, then requests the server's metadata preview with dryRun: true. It uses the usual connection selection and requires the server's APPLICATIONS permission. The server enforces authorization, ownership and manifest/version compatibility. No registration, installation, upload or metadata synchronization is performed, and planning never advances a pull base. The local build can generate app artifacts, just as app build does.
JSON marks plans with plan: true. A plan is not a saved approval: remote changes can alter what a later apply does. A missing owned application registration returns PLAN_UNAVAILABLE (exit 1). Register the app with twenty app apply --create, then plan again.
Entities missing from source are included as deletions by default, except for the workspace custom application, which keeps them unless you pass --prune. --no-prune passes inferDeletionFromMissingEntities: false to the preview and --prune passes true; without either the argument is omitted and the server decides. Servers released before --prune existed treat an omitted argument as true, so pass --no-prune to keep entities against them. The deprecated --no-delete still works as --no-prune with a DEPRECATED_OPTION warning; an explicit --prune or --no-prune takes precedence over it. Human output lists every action, identifies object/field deletions that would remove stored data, and shows the opt-out hint. JSON includes action details and counts. Application-variable values, including previous values in updates, are redacted from all plan actions regardless of their isSecret setting. A plan exceeding 10,000 actions or the transport's 16 MiB response limit fails instead of displaying an incomplete plan.
Apply an app
twenty app apply --remote dev
twenty app apply --create --json
twenty app apply --no-prune
twenty app apply --prune
app apply builds the app once with the CLI pipeline and keeps that build's snapshot until it finishes, so the files it uploads are the ones it built. It then asks the workspace for a fresh plan, shows it, and applies it: it installs the development app if needed, uploads the snapshot files, synchronizes the manifest, and regenerates the app's typed API client. It needs the server's APPLICATIONS and UPLOAD_FILE permissions.
- New apps. An app without a registration needs
--create, or a yes at the prompt in an interactive terminal. The CLI then registers the app (the server also requiresAPI_KEYS_AND_WEBHOOKSfor this), installs it, and plans its changes before uploading anything. Without approval it stops withCREATE_REQUIRED(exit 2). The registration's client secret is never requested. - Deletions. Entities missing from source are deleted by default (except in the workspace custom application), as in
app plan;--no-prunekeeps them,--prunedeletes them in every app, and the choice is sent to both the plan and the sync. JSON reportsinferDeletionFromMissingEntities: nullwhen neither flag is passed. Object and field deletions permanently delete stored data, so they need--yesor a yes at the prompt. Otherwise the command stops withCONFIRMATION_REQUIRED(exit 2) before changing anything.--yesnever changes which entities are deleted. - Uploads. File bytes go straight to the upload URLs the server returns, without the CLI's credentials. Each file is checked against the build's size and SHA-256 before anything is uploaded.
- Pull baseline. After an acknowledged sync, the CLI fetches the workspace ID and fresh application export, then atomically records
.twenty/cli/pull-base.json. This baseline letsapp pulldistinguish workspace changes from local edits. It is bound to the normalized API URL, workspace UUID and app UUID. JSON reportspullBase: "recorded","failed"or"unsupported"; only a recorded base addspullBasetocompletedPhases. Invalid exports or file-write errors preserve the prior base, warn withPULL_BASE_NOT_RECORDED, and allow client generation to continue. A server without the export API reports"unsupported"without a warning on every apply. The export is recorded as the server sent it; collections it lacks are read as empty by pull. Cancellation before the base is committed exits 130 withoutcome: "applied"andphase: "pullBase". - Typed client. After the sync, the CLI fetches the app's GraphQL schema from the workspace and calls the app's own
twenty-client-sdk/generateto regenerate the client in the app's ownnode_modules/twenty-client-sdk(clientGeneration: "generated"). It is skipped with aCLIENT_NOT_GENERATEDwarning when the app has nonode_modules/twenty-client-sdkof its own, as in a hoisted workspace. A symlinked client package is followed and its target rewritten, so don't apply two apps that share one client package at the same time. - Failures. A failed apply reports
details.phase,details.completedPhasesanddetails.outcome:not-startedwhen the failing step changed nothing,partialwhen some files were uploaded,unknownwhen a request was sent but its effect is not known, such as a failed or interrupted sync, andappliedwhen the sync succeeded but baseline recording was cancelled or client generation failed. Earlier steps, like a new registration, stay done. There is no rollback and no automatic retry: runtwenty app planto see where the workspace stands, then apply again. When client generation failed, the workspace has the new version but the client files may be incomplete: fix the problem, then runtwenty app generate-client, which regenerates the client without syncing again. Ctrl+C exits with 130 and reports the step it interrupted.
Remote changes made between the plan and the sync can change what the sync does. Remote changes between the acknowledged sync and the export can also enter the saved baseline without appearing in local source; this is not an atomic server snapshot of the sync. Planning, a failed sync, or a sync with an unknown outcome never advances the baseline.
Develop an app
twenty app dev --remote dev
twenty app dev --create --no-prune
twenty app dev --path ./apps/billing --format ndjson --no-prune
app dev builds and syncs once, then watches for edits. Each attempt uses the
same CLI build and strict project TypeScript checks as app apply. A failed
build prints diagnostics and keeps watching; it never uploads an incomplete
revision. It needs the same APPLICATIONS and UPLOAD_FILE permissions as apply.
The CLI watches the app folder and the external local files read by definition
loading, bundling and typechecking, including linked packages and extended
TypeScript configs. Relative imports of missing external files watch the nearest
existing parent, so creating the file can recover a failed build. The last
successful input graph stays watched after a failure. .git, .twenty,
node_modules, root dist, editor temporary files and .DS_Store are ignored.
Arbitrary filesystem reads inside app code are not discovered. Restart dev after
installing dependencies or changing the package manager's links.
Only one remote apply runs at a time. The compiler can prepare a newer complete snapshot while that apply finishes; intermediate edits coalesce into the latest revision. Uploads read independent, checksum-verified files, so a later build cannot overwrite them. An unchanged content hash skips sync only after that snapshot was acknowledged by the workspace. This is eventual convergence after edits settle, not an atomic checkout of files being edited concurrently.
Registration uses --create or a terminal confirmation. Deletion inference is
on by default except for the workspace custom application, with --no-prune
to keep missing entities and --prune to delete them in every app. Object and field
deletions require a terminal confirmation or --yes. Every revision requests a
fresh plan. An edit cancels a pending confirmation; approval for the
old revision cannot authorize the new one. A remote failure is reported with the
same phase/outcome details as apply and is retried only after a new source edit,
with a new plan. Inspect twenty app plan when a request's outcome is unknown.
After an acknowledged sync, dev records the pull base and regenerates the app's
own typed client when its schema, generator package or generated files changed.
Compilation pauses during generation, then explicitly rebuilds. Unchanged client
inputs and unchanged build output prevent a generation/sync loop. A schema fetch
failure keeps the old client and prints a warning. If generation starts writing
and fails, dev stops because the client files may be incomplete; fix the problem
and run twenty app generate-client before restarting dev.
Use human output or --format ndjson; --json is rejected before target lookup.
NDJSON uses ordered progress events with data.kind: watch-ready,
build-start, build-success, build-failure, build-skipped, sync-start,
sync-progress, sync-superseded, sync-failure and sync-success. Build events
carry the revision, successful builds also carry the build ID and content hash.
Output honors backpressure; buffered progress is bounded. Ctrl+C stops watching,
cancels active requests, releases snapshots after readers settle, and exits 130
with the interrupted remote phase when available. It does not roll back writes.
An abnormal worker exit or a filesystem-watcher failure ends the session; fix
the cause and restart twenty app dev. A killed process can leave temporary
folders in .twenty/cli/snapshots. After stopping all dev/apply sessions for that
app, abandoned snapshot folders can be removed.
Regenerate the typed client
twenty app generate-client --remote dev
twenty app generate-client --path ./apps/billing --json
app generate-client fetches the app's GraphQL schema from the workspace and regenerates the typed client in the app's own node_modules/twenty-client-sdk, the same step app apply and app dev run after a sync, without building, uploading or syncing. Use it after installing dependencies, after a failed client generation, or to pick up schema changes made in the workspace. It needs no server permission flag.
The app must already be installed in the workspace; otherwise the command fails with APP_NOT_INSTALLED (exit 4), and twenty app apply installs it and generates the client. An app without its own node_modules/twenty-client-sdk, as in a hoisted workspace, fails with CLIENT_SDK_NOT_INSTALLED instead of the warning app apply prints.
Pull an app
twenty app pull --remote dev
twenty app pull --path ./apps/billing --json
twenty app pull --path ./workspace-app --yes --no-input
Inside an app, app pull reads the identifier from the local application definition and pulls that application. Outside an app, it asks where to create a project for the selected workspace's custom application, then asks to create it, install its dependencies with Yarn, and pull. --path chooses an existing app or a new or empty destination; noninteractive creation requires both --path and --yes. It never overwrites an unrelated nonempty directory.
New projects reuse the bundled initializer's package and configuration files without demo entities. Pull writes the custom application's definition. An existing SDK project without an application definition also pulls the custom application. A missing custom application is an error. There is no --universal-identifier option.
Pull uses the selected connection and the server's APPLICATIONS permission. Creating a project here creates local files only; it does not register an application or change the workspace. Existing projects do not install dependencies automatically. If a new project's installation fails, the scaffold is kept so you can run yarn install there and retry pull.
The project must have twenty-sdk installed, version >=1.23.0, with its public twenty-sdk/define and twenty-sdk/front-component exports. Pull also checks that the SDK provides the authoring APIs required by the generated files. Missing APIs fail with SDK_SOURCE_UNSUPPORTED; install a compatible version (2.50.0 or later). Pull does not require a project TypeScript compiler. Run twenty app typecheck afterwards to check the generated definitions against your installed SDK.
Pull compares workspace metadata and local definitions using a baseline saved
by apply or a previous pull in .twenty/cli/pull-base.json. The baseline belongs
to one API URL, workspace UUID and application UUID.
Pull overwrites local edits to entities that changed on the workspace, without a confirmation prompt. With a matching baseline, unchanged workspace entities keep their local source, and confirmed remote deletions remove their files. Without a matching baseline, local-only definitions stay in place and pull does not infer deletions. Coverage gaps, unreadable definitions and local-only nested entities are preserved and reported; gaps do not require --force or an opt-in partial mode. JSON includes coverage, skipped, unreadableRelativePaths, localOnlyRelativePaths and overwrittenLocalChanges. Without a baseline, overwritten local edits cannot be distinguished from generated source.
Before replacing local files, pull stages the new content and backs up the originals. It updates the baseline only after writing the files. Ordinary write failures restore the previous files and baseline.
Failures in reconciliation report error.details.outcome: unchanged after an acknowledged refusal, cancellation before writing or successful rollback; unknown if a worker stops without acknowledging completion or rollback fails; pulled if writes and baseline completed but temporary-file cleanup failed. An interrupted worker can leave files partially written; inspect the changes and retained .twenty/cli/pull-backup-* files before retrying. A failed rollback also reports backupDirectory. Ctrl+C exits 130 unless the worker acknowledges a completed commit, in which case pull returns its result.
The current export contains metadata, translations and stored dependency files. Public assets and application source files are not exported yet. Workflows are written as defineWorkflow files in src/workflows; a workflow changed in the workflow builder, or one using steps or references an application cannot declare, is reported as a coverage gap and its local file is kept. The workspace Custom application is published from the builder too, so its workflows are written from their active version, and apply publishes a changed definition as a new version. Skills and agents are written as defineSkill and defineAgent files in src/skills and src/agents; one the server cannot reproduce from a definition, such as an agent on more than one role, is reported as a coverage gap and its local file is kept. Logic-function/front-component code and unsupported metadata are not regenerated. Pull restores package.json and yarn.lock from the application’s dependencies folder. If the exported package omits twenty-sdk, as the workspace Custom application does, pull keeps your local SDK dependency. Other exported files are refused before writing. Dependency files unchanged on the workspace keep local edits; changed remote files replace them. Missing remote files leave local files untouched. The installed generated client is left alone; pull never installs dependencies. Run yarn install after pulling dependency changes. Each export response is limited to 16 MiB. See the pull implementation for reconciliation and compatibility details.
Install a registered app
twenty app install --remote dev
twenty app install --path ./apps/billing --json
twenty app install --universal-identifier <id> --remote staging --json
app install installs a package already registered on the target server. It reads the local app definition to find its universal identifier, without building or typechecking the app; --universal-identifier works without a local project. Identifiers are sent in lowercase. It requires APPLICATIONS permission.
The server selects the registered package and version. Local source changes are not uploaded. For a private package, run app publish --private first; publishing to npm alone does not create a server registration. Installation can run app hooks and update an existing installation. Use app apply to sync local source instead.
The command waits up to ten minutes for its server installation job to complete, then verifies that the app is installed. While it waits, human output shows the job's progress as an updating percentage bar in an interactive terminal. Redirected output, CI and terminals with TERM=dumb print a plain progress line each time the percentage changes. JSON returns application, installed: true and jobId. Failed jobs return INSTALL_FAILED; missing or mismatched job status is an error, not a successful installation.
Identifier resolution and installation errors include details.phase, details.completedPhases and details.outcome, plus the universal identifier and job identifier when available. Identifier resolution failures report phase: "identity" and outcome: "not-started". Ctrl+C or a timeout stops waiting but does not cancel the server job. Run the same command again to retry or resume waiting for an installation that is still running. The command requires the server's triggerInstallApplication and findInstallApplicationJobStatus APIs, including lookup by jobId.
Uninstall an app
twenty app uninstall --remote dev
twenty app uninstall --yes --json
twenty app uninstall --universal-identifier <id> --yes
app uninstall reads the local app definition to find its universal identifier, without building or typechecking the app. It checks that the app is installed on the target and that the workspace allows uninstalling it, then uninstalls it. --universal-identifier works without a local project. It needs the server's APPLICATIONS permission.
Uninstalling runs the app's uninstall hook and deletes everything the app owns, including its objects, fields and their data. It always needs --yes, or a yes at the prompt in an interactive terminal; otherwise it stops with CONFIRMATION_REQUIRED (exit 2) before changing anything. An app that is not installed returns APP_NOT_INSTALLED (exit 4), and one the workspace does not allow to uninstall returns APP_NOT_UNINSTALLABLE (exit 6).
The app's registration is kept, so twenty app apply can install it again without --create. Failures report details.phase, details.completedPhases and details.outcome, as for apply: an uninstall request that fails after the server received it, or is interrupted with Ctrl+C, has an unknown outcome. Running the command again reports APP_NOT_INSTALLED once the app is gone. --universal-identifier accepts any UUID casing and sends the canonical lowercase form.
Execute an app function
twenty app exec --name add-numbers --remote dev --payload '{"a":2,"b":3}'
twenty app exec --universal-identifier <uuid> --payload @payload.json --json
printf '{"a":4,"b":7}' | twenty app exec --name add-numbers --remote dev --payload - --json
Run from the app folder or pass --path. The CLI reads app definitions to find
its functions, then executes the selected function's deployed code. Sync local
changes with app apply or app dev first. Execution does not build bundles,
typecheck, sync, register or install the app.
Choose exactly one of --name (exact deployed name), --universal-identifier,
--post-install, --pre-install or --uninstall-hook. Hook selectors run the
hook's code and its side effects without installing or uninstalling the app.
Payloads must be JSON objects, supplied inline, through @file, or through -
for stdin; the default is {}. The selected function must belong to both the
local app manifest and the installed app on the target workspace.
The current server requires a signed-in user and the APPLICATIONS and
WORKFLOWS settings permissions. Sign in with twenty auth login --url <url> --name dev, then pass --remote dev. API keys, including environment API-key
targets, cannot execute logic functions. The server additionally restricts
which functions the user may run on demand.
Human output shows status, duration, returned data, error and logs. --json
returns those fields in the standard envelope; NDJSON is not supported. A
function returning a non-SUCCESS status exits 1 with EXECUTION_FAILED, keeping
its data, logs and error in error.details with outcome: "completed".
There are no automatic retries. The request deadline uses the deployed
function's timeout plus 60 seconds. A lost response or Ctrl+C can leave the
function running on the server; the error reports outcome: "unknown" and asks
you to check its effects before retrying. An acknowledged execution rejection
reports "not-started". Ctrl+C exits 130, without rolling back side effects.
See the execution implementation for compatibility details.
Watch app logs
twenty app logs --remote dev
twenty app logs --name add-numbers --remote dev
twenty app logs --universal-identifier <uuid> --format ndjson
Run from the app folder or pass --path. This watches newly published execution
output from every logic function in that app. Output arrives when an execution
finishes, not line by line while it runs. It does not fetch historical logs,
watch other apps, or build, sync, register or install anything.
Names are not unique: --name matches every function with that exact name in the
app. Use --universal-identifier to isolate one function. The two filters are
mutually exclusive. Human output labels each execution with its function name
and identifier; NDJSON records contain applicationUniversalIdentifier,
functionName, functionUniversalIdentifier and logs.
Some server schemas expose only log text. If the identity fields are unsupported,
the CLI warns and subscribes once requesting only logs. An explicit filter
supplies that name or identifier; unknown identities are null in NDJSON and
omitted from human labels. With neither filter, those schemas cannot attribute
mixed output to individual functions.
The stream supports human output and --format ndjson; finite --json is
rejected. Ctrl+C closes it and exits 130. A server completion exits 0. A dropped
or stalled connection exits with an error and the emitted record count, with no
automatic reconnect because missed logs cannot be replayed. Slow output applies
backpressure; each SSE frame is limited to 16 MiB, with no session-size cap.
Connection setup and gaps between received body chunks each have a 60-second
deadline; server heartbeat comments keep quiet subscriptions alive.
This uses the existing app-log subscription and its WORKFLOWS permission and
application access checks. API keys and browser-login remotes are supported.
It does not require the paid audit-log entitlement, ClickHouse history or the
workspace-wide Settings logs API. See the log subscription implementation.
Expired browser sessions
For commands that use a workspace, interactive OAuth sessions are checked before the command starts. If a session is rejected or cannot be refreshed, the CLI offers to sign in again once, validates the new session, and saves its credentials without changing the remote's URL, default selection or other settings.
API keys, JSON/NDJSON output, --no-input, redirected stdin and CI never trigger
this prompt. Permission errors do not trigger sign-in either. If authentication
fails after a command starts, the CLI stops with the login hint; it does not
replay requests or restart an app apply. A remote changed during sign-in is left
as-is, and the command stops with CONFLICT.
Output
twenty version (or --version) reports the running executable's version.
twenty version --json also includes Node, platform and architecture.
twenty commands --json lists command arguments, flags, output modes and
project/target requirements for scripts that discover the command surface.
Commands print readable text by default. With --json, a command prints exactly one JSON document on stdout, including when it fails:
{
"schemaVersion": 1,
"ok": true,
"command": "version",
"data": {
"version": "2.46.0",
"node": "24.9.0",
"platform": "darwin",
"arch": "arm64"
},
"warnings": []
}
A failure has "ok": false and an error object with a stable code, a message, and sometimes a hint and details.
Exit codes:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Failure |
| 2 | Usage error or missing confirmation |
| 3 | Authentication or permission denied |
| 4 | Not found |
| 5 | Partial failure |
| 6 | Conflict |
| 130 | Cancelled |
Publish an app to npm
twenty app publish
twenty app publish --path ./apps/billing --tag beta --json
Builds and typechecks the app, packs that exact build, then publishes the package with public access. No Twenty remote or workspace authentication is required. Publishing to npm does not sync or install the app in a workspace.
Install npm and authenticate with the intended registry first. npm runs from the app directory, so its project/user configuration and environment credentials apply. --tag sets the npm dist-tag. GitHub Actions jobs with OIDC request provenance automatically; set TWENTY_APP_PUBLISH_DISABLE_PROVENANCE=true to opt out, for example when publishing from a private source repository.
Packing and publishing skip npm lifecycle scripts because the CLI already built the app. npm's package-file selection still applies. If package.json has a files field, it must include manifest.json and the generated app files; the command rejects an incomplete package before publication. npm excludes the root yarn.lock from packages, so the CLI also packs it as dependencies/yarn.lock, where Twenty reads it at install. Temporary packages and build snapshots are removed after completion or failure.
Human mode displays npm output and supports interactive authentication when a terminal is available. JSON mode returns one CLI envelope and does not prompt; configure an automation token or npm’s npm_config_otp environment option before running it. Failed npm commands return PUBLISH_FAILED with the subprocess exit code and captured output. If publication is interrupted after sending the package, check the registry before retrying, since the version may already have been published.
Publish to a private Twenty registry
twenty app publish --private --remote staging
twenty app publish --private --path ./apps/billing --json
--private publishes the same built package to the selected Twenty server registry instead of npm. It uses the normal saved remote or environment credentials, requests a tarball upload, sends the bytes directly to storage, then registers the uploaded app. npm is still needed for local packing, but npm registry credentials are not used and --tag is rejected. The server requires file-upload permission and MARKETPLACE_APPS permission on the target workspace.
Publishing registers a version; it does not install the app or directly sync the selected workspace. Publishing an update can trigger automatic upgrades in workspaces where the app is already installed with automatic upgrades enabled. The server enforces application ownership, version progression and engine compatibility. JSON results contain target: "private", the selected server under registry, the registration and installed: false, indicating that this command did not request installation.
Failed uploads never trigger registration. If registration fails or is interrupted after sending the request, the app may already be registered. The error includes the phase, upload file ID and an unknown outcome; check the server registry before retrying. Temporary packages are cleaned up in either case.
App translations
twenty app translations extract
twenty app translations extract --locale fr-FR
twenty app translations extract --path ./apps/billing --json
Use --path for an explicit app directory. Without --path, the CLI finds the
app containing the current directory.
Extraction runs locally, without a workspace connection. It reads app metadata
and static t, msg, and Trans strings in front-component source files. It
refreshes locales/en.json with source strings and updates existing target JSON
catalogs. --locale also creates a missing supported target catalog, for example
locales/fr-FR.json. The source locale en cannot be a target.
Translations for unchanged message/context pairs are preserved. New entries have
empty translations; obsolete entries are removed. Context groups remain separate.
Malformed target catalogs fail with INVALID_INPUT before writing any catalogs.
Unsafe catalog or staging paths report APP_PATH_UNAVAILABLE. Files under
locales/compiled are left untouched. Temporary files live under .twenty/cli.
Each catalog is replaced atomically; an
interrupted run may update only some catalogs, so rerun extraction to finish.
The command validates app definitions but does not bundle or upload them. Edit
the target catalogs, then run twenty app apply to deploy translations. Build
and apply already compile translations; no separate compile command is needed.
JSON output includes the app, source-string count, updated catalog paths and
diagnostics.