Introducing a new way to review your PRs.

Read the announcement

twentyhq / twenty

The open alternative to Salesforce, designed for AI.

View on GitHub

22 documents · Updated Nov 20, 2026

docs / application-cli

CLI application delivery

The Twenty CLI gives an engineer one path from a local application project to a connected workspace. It manages sign-in and workspace selection, supports API and metadata inspection, and moves an application through creation, validation, packaging, synchronization, deployment, and development. It also provides a Docker-based local Twenty environment for development and tests. See external integrations for the wider integration model, connected accounts and messaging for provider features, extension integrations for app extension points, and installed applications for the workspace-side lifecycle.

Command model

The CLI groups commands by user goal and applies shared rules for project discovery, workspace targets, output, errors, cancellation, and network access. A command can serve a person at a terminal or a script in CI without changing the workspace contract.

Workspace targets

Each target is a Twenty server URL paired with credentials. A command can use a named saved remote, the default saved remote, or an API URL and API key supplied by the environment. An explicit --remote choice takes priority. The target layer refreshes an expiring browser session before a request and keeps saved remotes in private local configuration.

References: packages/…/select-target.ts• L31-112 packages/…/resolve-target.ts• L20-146 packages/…/resolved-target.type.ts• L1-12 packages/…/commands.md• L147-175

Output contracts

Commands return a common result that can be rendered for a person or a tool. Human mode explains progress and outcomes. JSON returns one structured document, while NDJSON emits ordered events for long-running work such as development, logs, and exports. Stable error and exit codes let automation distinguish usage errors, permission failures, conflicts, missing resources, partial remote effects, and cancellation.

References: packages/…/create-output.ts• L1-160 packages/…/cli-error-code.type.ts• L1-64 packages/…/run-command.ts• L29-91 packages/…/commands.md• L323-331

Help catalog

The command catalog is the shared source for registration and help. Topics group local environment control, authentication, workspace access, API, metadata, data, and application actions, so the command surface stays discoverable from the terminal and from machine-readable command listings.

References: packages/…/command-catalog.ts• L1-87 packages/…/command-topics.ts• L5-58 packages/…/commands.md• L1-26

Network access

Workspace requests and app uploads can work through HTTP proxies. The CLI accepts fixed proxy headers or a command that creates fresh headers for an identity-aware proxy. It limits those headers to the selected workspace host and does not pass them to separate storage URLs. This keeps proxy access separate from app source and from upload credentials.

References: packages/…/commands.md• L205-265 packages/…/resolve-proxy-headers.ts• L9-31 packages/…/validate-proxy-header-or-throw.ts• L24-60 packages/…/put-upload-file.ts• L23-51

Local Twenty environment

The local command group runs a full Twenty development environment in Docker without a remote workspace target. It gives application engineers a repeatable local server for development, tests, health checks, logs, version changes, and data reset.

Local environment lifecycle

twenty local start creates or starts the main local environment at port 2020. --test selects a separate test environment at port 2021. For a new environment, the CLI uses an explicit image first. Otherwise it selects the highest published image that matches the nearest app's engines.twenty range, and uses latest only when no range exists. It waits for the health check before returning the local URL and a matching sign-in command.

An existing instance keeps its image and port. If its version does not match the app's engines.twenty range, startup warns and points to local upgrade; it does not silently replace the instance. A saved remote with the same name but a different URL also produces a --replace hint rather than changing the remote during local startup.

The environment keeps database, analytics, and file storage in named Docker volumes. local stop preserves the container and its data. local upgrade replaces the container while keeping its ports and volumes, and it does not roll back database migrations. local reset removes the selected container and its data after approval. These commands do not need a project or saved remote.

This diagram shows how local environment commands move between a Docker container, persistent data, and the application engineer.

flowchart LR
  Start[local start] --> Health[Health check]
  Health --> Ready[Local Twenty URL]
  Ready --> Use[Develop and test]
  Use --> Inspect[status or logs]
  Use --> Upgrade[local upgrade]
  Upgrade --> Health
  Use --> Stop[local stop]
  Stop --> Start
  Use --> Reset[local reset]
  Reset --> Fresh[Fresh data volumes]

References: packages/…/commands.md• L28-79 packages/…/run-local-start-command.ts• L20-103 packages/…/resolve-local-image.ts• L14-86 packages/…/get-local-login-hint.ts• L8-39

Authentication and workspace access

Authentication connects a local CLI profile to a Twenty workspace. Browser sign-in provides a user OAuth session, while API keys provide a non-interactive path for scripts and CI. Named remotes keep the server and credential choice separate from the application directory.

Sign-in sessions

twenty auth login accepts a server URL and either opens a browser for OAuth or reads an API key from standard input. Browser sign-in checks the server's OAuth discovery data and validates the credential before saving it. auth status, auth token, and auth logout let engineers inspect, use, or remove saved access. Logout removes local credentials but does not revoke the server-side credential.

Login validates the credential before it writes the remote. If a named remote already points to another server, the command requires --replace, which prevents a local name from silently moving to a new workspace. Browser sign-in needs an interactive terminal; scripts and CI use --with-token and standard input. Login can also save proxy settings for a server so later commands can pass the same identity-aware gateway.

References: packages/…/README.md• L7-33 packages/…/run-auth-login-command.ts• L40-71 packages/…/run-auth-login-command.ts• L74-216 packages/…/discover-oauth-server.ts• L1-120 packages/…/get-local-login-hint.ts• L8-39 packages/…/commands.md• L109-175

Remote selection

Saved remotes separate workspace identity from the project directory. remote list, remote use, remote rename, and remote remove manage these connections. Target selection uses an explicit --remote first, then TWENTY_REMOTE, then the paired TWENTY_API_URL and TWENTY_API_KEY, and finally the saved default remote. Environment targets support scripts without saving credentials, but the API URL and API key must be supplied together.

References: packages/…/run-remote-list-command.ts• L1-80 packages/…/run-remote-use-command.ts• L1-61 packages/…/select-target.ts• L55-105 packages/…/resolve-target.ts• L103-146 packages/…/commands.md• L136-175

Workspace inspection

The CLI provides a direct workspace interface for checks that do not belong to an application build. It can send REST requests, run core or metadata GraphQL queries, inspect records, describe the object model, and export records for later use.

Direct API requests

api rest sends a request below the selected API URL. api graphql sends a query or mutation to either the core API or the metadata API. Both commands use the selected target and expose structured results for quick checks and repeatable scripts. REST paths stay inside the selected API URL. Writes execute under the workspace's normal permissions and do not receive an extra confirmation step.

References: packages/…/run-api-rest-command.ts• L37-65 packages/…/run-api-graphql-command.ts• L33-60 packages/…/commands.md• L176-203

Workspace metadata

Metadata inspection explains the schema that an application will read or change. Engineers can list objects and fields, describe constraints and relations, include system-owned entries when needed, and inspect ownership. Names use exact API names rather than labels. Ambiguous names fail instead of selecting an arbitrary resource. The CLI reads all metadata pages before resolving a name, so a later match can still expose an ambiguity.

References: packages/…/run-metadata-object-list-command.ts• L36-105 packages/…/fetch-metadata-inspection.ts• L18-95 packages/…/run-metadata-field-describe-command.ts• L1-120 packages/…/commands.md• L356-384

Record inspection

Record commands use the same object-name resolution as metadata inspection. data list reads a page or a bounded full traversal with filters and ordering, while data get reads one record and one level of related records. JSON preserves full values, and NDJSON supports larger page-by-page traversals with a resume cursor after a completed page.

References: packages/…/commands.md• L386-434 packages/…/run-data-list-command.ts• L1-120 packages/…/run-data-get-command.ts• L1-100

Record exports

data export asks the workspace to create a CSV from an object's records, follows progress, and downloads the result to a local file. Field selection, filters, and ordering use the same metadata and REST concepts as record inspection. The file is written through a temporary owner-only file and becomes visible only after the download succeeds.

An export is an asynchronous server job with a short-lived download link. It has no resume or redownload path, so an interrupted generation or download must run again. Existing files are kept unless --force is used.

References: packages/…/run-data-export-command.ts• L32-214 packages/…/download-record-export.ts• L17-118 packages/…/create-export-file-or-throw.ts• L11-121 packages/…/commands.md• L436-490

Application project lifecycle

An application project is a local set of metadata definitions, runtime code, assets, translations, and configuration that the CLI turns into a workspace application. The lifecycle separates local checks from remote planning and synchronization, so an engineer can inspect changes before they affect the workspace.

This diagram shows the main path from a new project to a running application.

flowchart LR
  Init[Initialize project] --> Define[Add definitions and code]
  Define --> Check[Build and typecheck]
  Check --> Plan[Preview workspace changes]
  Plan --> Apply[Register, upload, and sync]
  Apply --> Dev[Develop and inspect]
  Apply --> Pull[Pull workspace metadata]

Project initialization

twenty app init creates an application from the template bundled with the CLI. It writes project identity, application identifiers, a supported Twenty version range, exact first-party package pins, a lockfile, and delivery workflow inputs. It does not install dependencies, authenticate, start a server, or change a workspace. The project is staged before it is placed in the requested new or empty directory, so a render failure does not leave a partial application.

The CLI package is published as twenty. Generated application projects use Yarn 4 and pin the application Node version in .nvmrc; the template's compatibility range must match the workspace version used for delivery. The CLI is installed globally and is not an application dependency.

References: packages/…/README.md• L7-15 packages/…/README.md• L35-89 packages/…/commands.md• L492-531 packages/…/create-app-project.ts• L137-203 packages/…/.nvmrc• L1 packages/…/package.json• L1-24

Definition authoring

twenty app add creates local definitions for the application data model, validation rules, logic functions, front components, and related workspace UI. The SDK also lets projects describe roles, workflows, skills, agents, connection and messaging providers, MCP servers, layouts, views, and other application entities. These definitions are local input for the next build. Generation does not install packages or apply workspace changes.

Universal identifiers link local definitions to workspace entities. Provider definitions connect their provider records to logic functions and application variables. The generated template also starts with an app-owned default function role that has broad record read, update, and soft-delete access but cannot be assigned to users or API keys. Runtime logic imports runtime types and helpers from the SDK, while build-time define* factories remain part of authoring. Review generated files before running app build and app plan.

References: packages/…/commands.md• L546-604 packages/…/README.md• L3-23 packages/…/prepare-app-add-files.ts• L47-326 packages/…/default-role.ts• L1-20 packages/…/define-connection-provider.ts• L73-175 packages/…/define-messaging-provider.ts• L11-78 packages/…/index.ts• L1-18

Local validation

app typecheck checks the project with its installed TypeScript setup without producing a build. app build reads supported SDK definitions, creates a manifest, packages application artifacts, and validates the identity and links between entities before remote work starts. The CLI uses the app's installed SDK and compiler. It does not install a missing dependency or substitute a global one.

The validation boundary protects identifiers, relations, roles, layouts, widgets, workflows, validation rules, settings links, and application-wide limits. It also checks that agents reference roles within the application's default role. A build or typecheck failure stops before upload or synchronization. Build rules depend on the CLI and SDK versions, so inspect a plan when tooling versions differ.

References: packages/…/commands.md• L606-672 packages/…/manifest-build.ts• L95-123 packages/…/manifest-build.ts• L644-800 packages/…/manifest-validate.ts• L235-341 packages/…/README.md• L1-50 packages/…/validate-agent-roles-within-application-role.ts• L1-120

Application bundles

The build turns application definitions and source into a manifest plus deployable artifacts. Logic functions, front components, static files, public assets, translations, dependencies, source imports, and the project README contribute to the application snapshot. Each snapshot records paths, roles, sizes, and hashes that the workspace can receive.

The source inventory follows the app's TypeScript configuration and local imports while excluding dependencies and unrelated paths. It also records local type declarations, CSS, imported assets, and each front component's own source set. Shared files are stored once. Front components are prepared for their remote-DOM worker runtime, with CSS and translation data included in their bundles. Build and source-reading work runs in a separate worker process that receives no CLI credentials. This boundary separates app tooling from target access, but it is not a sandbox for untrusted code.

References: packages/…/README.md• L13-58 packages/…/build-application.ts• L58-247 packages/…/collect-application-source-files.ts• L12-146 packages/…/compile-application.ts• L18-138 packages/…/get-front-component-build-plugins.ts• L25-44

Deployment and synchronization

The CLI supports direct workspace delivery, registry publication, workspace installation, a short local feedback loop, and workspace-to-project synchronization. Applying sends a verified local snapshot to a workspace. Publishing creates a package or registry version. Pulling restores supported workspace state into local source.

Metadata planning

app plan builds the project and asks the selected workspace for a read-only change set. It reports the actions that would be taken but does not register, upload, or synchronize the application. The server checks authorization, ownership, and application compatibility before returning the plan.

Missing source entities can become remote deletions. --no-prune keeps missing entities, while --prune requests deletion for every application. If neither option is set, the server's application-specific default applies. Object and field deletions need explicit approval because they can delete stored data. The plan groups dependent deletions and hides application-variable values. A plan is a preview, not a saved approval.

References: packages/…/run-app-plan-command.ts• L9-54 packages/…/format-app-plan.ts• L262-377 packages/…/group-app-plan-cascades.ts• L7-43 packages/…/parse-app-plan.ts• L26-77 packages/…/commands.md• L674-715

Metadata synchronization

app apply builds once, previews the resulting change set, uploads that same build snapshot, and synchronizes the workspace. With --create, it can register and install a missing development application. After a successful sync, it records a workspace-bound pull base and regenerates the app's own typed client when that package is installed locally.

Application files are checked against the build's recorded size and hash before upload. File bytes go to server-provided upload URLs, so the CLI credential is not sent to a separate storage host. Apply reports the remote phase and outcome when a failure occurs. An upload or sync failure can leave the workspace changed or its result unknown. The CLI does not roll back remote changes.

The pull base binds the application export to the normalized API URL, workspace, and application. It also records source, dependency, asset, and remote-source fingerprints for reconciliation. This lets a later pull tell a remote change from a local edit without treating an unmatched target as the same history.

Remote registration, file upload, synchronization, baseline recording, and client generation are separate phases. A later phase can fail after an earlier phase has changed the workspace, so the CLI reports the phase and outcome rather than claiming a rollback. Object and field deletion needs explicit approval. The baseline advances only after an acknowledged sync and a valid export.

References: packages/…/run-app-apply-command.ts• L25-168 packages/…/apply-app-build.ts• L1-220 packages/…/upload-app-files.ts• L132-385 packages/…/put-upload-file.ts• L10-55 packages/…/record-pull-base.ts• L1-120 packages/…/create-pull-base-write.ts• L16-66 packages/…/collect-source-fingerprints.ts• L17-48 packages/…/commands.md• L717-810

Workspace export

app pull moves a local-development application export into a project. The export can include metadata, translations, dependency files, public assets, and source for supported application definitions and their local imports. It also carries coverage entries that state which workspace entities were exported or could not be represented locally. The CLI validates file paths, source inventories, checksums, and application identity before writing.

Inside an app, the local application identity selects the target application. Outside an app, pull can create a project for the workspace's custom application and then pull. It does not register an application or change the workspace. Pulling a packaged or standard application is not supported because the export is for locally developed applications. Unsupported or missing workspace state remains a reported coverage gap.

References: packages/…/run-app-pull-command.ts• L26-105 packages/…/fetch-app-export.ts• L79-227 packages/…/app-export.type.ts• L3-26 packages/…/parse-pull-files.ts• L23-171 packages/…/commands.md• L912-980

Pull reconciliation

Pull compares the workspace export with local source and the target-bound pull base. With a matching base, unchanged workspace entities preserve local source and confirmed remote deletions can remove local files. Changed workspace entities replace local edits and appear in the report. Without a matching base, pull keeps local-only definitions and does not infer deletions.

The reconciliation restores supported definitions, translations, dependency files, public assets, workflow code-step files, skills, agents, and application source when the export can express them. This includes definition entry files and additional source used by logic functions and front components. Source keeps its original content and path when possible. Dependencies and assets use their own fingerprints, while remote source hashes track definition source and other application source separately. Unsupported entities, unreadable files, local-only definitions, and nested local definitions remain in place and appear in the report.

Pull stages writes and the new baseline together. Ordinary write failures restore the prior files and baseline. A worker that stops before it can confirm the result reports an unknown outcome and can leave backups for recovery. Remote changes can overwrite local edits without a prompt, so the pull report is part of the review step.

This diagram shows how an export becomes a safe local change set rather than a direct overwrite.

flowchart LR
  Export[Workspace export] --> Validate[Check identity and file coverage]
  Validate --> Compare[Compare target-bound baseline and local source]
  Compare --> Plan[Plan writes, deletions, and preserved files]
  Plan --> Stage[Stage source and baseline]
  Stage --> Commit[Commit local changes]
  Commit --> Report[Report writes, gaps, and overwritten edits]

References: packages/…/README.md• L42-100 packages/…/README.md• L109-216 packages/…/build-pull-entities.ts• L38-70 packages/…/plan-pull-writes.ts• L126-240 packages/…/plan-source-definition-writes.ts• L15-165 packages/…/plan-application-source-writes.ts• L14-86 packages/…/preserve-nested-pull-entities.ts• L12-177 packages/…/pull-application.ts• L33-307

Published deployment

app publish builds and packages an application, then publishes it either to npm or to a selected private Twenty registry. Public npm publishing uses npm trusted publishing with an OIDC provenance record when the generated workflow is used. That record identifies the GitHub source of the package and can support marketplace ownership claims. Public npm publishing does not need a Twenty remote and does not install or synchronize the app. app install is a separate action that installs a registered package selected by the workspace.

The generated delivery workflows pin the CLI used for checks and deployment. The generated npm workflow uses the app's Node version file and a current npm release for trusted publishing. The package step must return one valid archive description before the CLI can publish it. The repository must be registered as an npm trusted publisher before the workflow can publish with provenance.

References: packages/…/commands.md• L1026-1068 packages/…/commands.md• L1256-1330 packages/…/publish-app-to-server.ts• L18-143 packages/…/parse-npm-pack-output-or-throw.ts• L7-68 packages/…/README.md• L17-40 packages/…/publish.yml• L1-55

Package installation

app install asks a workspace to install a package that is already registered in its application registry. It uses the package selected by the server and does not build or upload local source. Private publication creates a registry version but does not install it; local source delivery remains the role of app apply.

References: packages/…/commands.md• L1029-1071 packages/…/commands.md• L1301-1333

Development workflows

The CLI supports a short local feedback loop and inspection of behavior already deployed to a workspace. Development repeats the same build and synchronization contract as apply, while inspection commands do not change the deployed application.

Live development

app dev watches the project and the external local files used by definition loading, bundling, and typechecking. Each valid revision builds a complete snapshot, plans and applies metadata changes, uploads verified files, records the new pull base, and updates the typed client when needed. A failed build keeps watching for a source change. Authentication and permission failures stop the session because a retry without a valid target is unsafe.

Only one remote apply runs at a time. Edits during an active sync supersede a pending revision, while the current upload continues from its verified snapshot. The watcher keeps the last successful input graph after a build failure and ignores generated, dependency, and editor temporary paths. An acknowledged unchanged content hash can skip a later sync. The result is eventual convergence after edits settle, not an atomic view of files edited during a sync.

References: packages/…/run-app-dev-command.ts• L27-297 packages/…/run-dev-loop.ts• L1-220 packages/…/README.md• L3-47 packages/…/commands.md• L812-890

Typed client generation

After an acknowledged sync, apply and dev can regenerate the app's typed client from the workspace GraphQL schema. The generator belongs to the app's installed twenty-client-sdk, so the generated files stay with the app that owns them. app generate-client repeats this step without building, uploading, or synchronizing.

Client generation is skipped after apply when the app has no own client package directory, but the explicit command fails in that case. A generation failure can leave partial client files. Fix the package or schema problem before regenerating, and do not treat client generation as a remote rollback.

References: packages/…/README.md• L1-42 packages/…/commands.md• L777-810 packages/…/commands.md• L892-910

Runtime inspection

app exec runs a deployed logic function as the signed-in user and can invoke application lifecycle hooks with a JSON payload. app logs watches new execution output and can filter it by function. Neither command builds or synchronizes the app, so they inspect the behavior of the version already deployed to the workspace.

References: packages/…/run-app-exec-command.ts• L1-160 packages/…/subscribe-to-app-logs.ts• L1-160 packages/…/commands.md• L1104-1199

Translation extraction

app translations extract updates local translation catalogs from application metadata and static translation calls in front-component source. It preserves existing translations for unchanged messages, creates empty entries for new messages, and removes obsolete entries. Build and apply compile and deliver the catalogs after they are edited.

References: packages/…/commands.md• L1332-1364 packages/…/plan-translation-writes.ts• L115-252 packages/…/extract-application-translations.spec.ts• L44-167

Application removal

app uninstall removes an installed application's workspace-owned objects, fields, data, and hook effects after explicit approval. It keeps the registration, so a later app apply can install the application again without --create. This is a workspace data operation, not local project cleanup.

References: packages/…/run-app-uninstall-command.ts• L16-91 packages/…/uninstall-app.ts• L1-100 packages/…/commands.md• L1064-1110

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep target precedence aligned across authentication, API inspection, planning, applying, pulling, and development. A change can send a metadata or deployment request to the wrong workspace.
  • Keep proxy headers limited to the selected workspace origin and separate from storage upload URLs. A change can leak gateway credentials or prevent renewal before the request reaches Twenty.
  • Keep local image selection aligned with engines.twenty, published image tags, local ports, and the separate test environment. A mismatch can start an incompatible server or connect tests to development data.
  • Keep local container names and volume destinations stable across start, stop, upgrade, and reset. A mismatch can detach an existing database or delete the wrong data.
  • Keep the bundled template, first-party package pins, engines.twenty, generated workflow CLI version, Node version file, npm publishing setup, and published CLI release aligned. A mismatch can make a new app fail its local, CI, or package delivery path.
  • Keep the SDK definition exports, manifest entity types, provider links, role permission identifiers, and pull entity mappings aligned. A new entity must be generatable when intended, readable during build, validated, and recoverable during pull.
  • Keep install-time logic handlers separate from runtime triggers. Their supported inputs and version-upgrade behavior must remain aligned with install and upgrade processing.
  • Keep application definition source paths, imported application source paths, public asset paths, dependency fingerprints, remote source fingerprints, and local source fingerprints aligned. A mismatch can overwrite local source or report a false local edit.
  • Keep workflow code-step identifiers, generated source paths, ownership scans, and stale-file deletion aligned. A mismatch can overwrite an unrelated code file or leave source for a removed step behind.
  • Keep pull staging, rollback, baseline commit, and outcome reporting aligned. A partial file commit must not be reported as unchanged or as a successful pull.
  • Keep app-worker credential filtering and tooling diagnostic mapping aligned. App code must not receive CLI secrets, and its failures must remain distinct from CLI failures.
  • Keep export progress, temporary-file handling, download validation, and overwrite behavior aligned. A failed CSV export must not replace a prior destination with partial data.

Important failure modes

TriggerConsequenceGuard
Only one API target environment variable is setThe CLI cannot identify a valid workspace targetSet both the API URL and API key, or use a saved remote
A saved remote name points to another URLLogin or local startup can target the wrong server or stop before savingConfirm the URL and pass --replace only when the move is intended
A proxy header overrides a CLI-owned header or contains invalid charactersThe request is rejected before it reaches the workspaceUse valid Name: value lines and let the CLI set authorization headers
Docker uses a remote socket or invalid contextLocal commands can affect an unintended Docker host or stop before work startsSelect a local Docker context and unset a remote DOCKER_HOST override
The app's engines.twenty range has no matching imageLocal start cannot select a compatible imageFix the range or pass an explicit image version
local reset is approved for the wrong environmentThe selected local database, files, and analytics data are deletedCheck the environment and use --test only for the test instance
The app lacks a supported SDK or TypeScript setupBuild or typecheck stops before a deployable snapshot existsInstall the supported app SDK and compiler with the supported Node and Yarn setup
An app definition has an invalid identity, relation, role, or provider linkBuild fails before deliveryReview generated identifiers and run app build before planning
app apply infers missing source entities as deletionsWorkspace metadata and stored data can be removedReview app plan and use --no-prune when source coverage is incomplete
Apply fails after workspace synchronizationThe workspace may contain the new version while the pull base or client is incompleteRead the phase and outcome, run app plan, then repair follow-up work before retrying
A published package is treated as installedThe workspace remains unchanged even though a package version existsRun app install or use app apply for local source synchronization
app pull uses the wrong identity, workspace, or unmatched baselineLocal definitions can be replaced by another app's export or local deletions can be missedCheck the selected remote, application identity, pull report, and baseline status
A workspace export includes unsupported files, missing source, or coverage gapsSome workspace state is not written locally, or pull stops before writesRead coverage and skipped entries, then restore unsupported state deliberately
A source definition moves locally while its server source inventory still uses the old pathPull refuses to restore the definition's imported filesMove the entry back before pulling, or redeploy the definition at its new path
A public asset, dependency, or application source changes remotely while local source also changedPull can replace local content and report an overwritten editReview fingerprints and the pull report before building
A nested local definition would disappear during replacementPull preserves the parent file and reports it as skippedReview skipped entities and resolve the local ownership before pulling again
Pull is interrupted during its file commit or baseline writeThe result can be unknown and backups can remain for recoveryInspect local changes and the reported backup path before retrying
A source change arrives during a pending development confirmation or syncThe old revision is discarded or the session requests a fresh planWait for the next revision and review its new plan
npm trusted publishing is not configured for the repository and workflowPublic package publishing cannot create the required provenance recordRegister the repository and publish.yml as an npm trusted publisher
A package's files field omits manifest.json or generated app filesnpm publication stops after packing and the package is not publishedInclude the manifest and generated files in the package contents
A private registry upload or registration ends with an unknown resultThe package may exist in the registry even though the CLI reports failureCheck the registry with the reported upload file ID before retrying
A record export is interrupted or its download link expiresThe CSV is not complete and cannot be resumedRun the export again and keep the command connected until it finishes
The app has no own generated-client package directoryApply or dev skips client generation, or generate-client failsInstall twenty-client-sdk in the app itself and regenerate after synchronization

Key files

FileWhy to read it
packages/…/README.mdStates the standalone CLI boundary, supported runtime, and shortest application workflow
packages/…/package.jsonDefines the published CLI package and its runtime tool boundary
packages/…/commands.mdGives user-facing behavior, permissions, safeguards, output, and recovery rules
packages/…/command-catalog.tsShows the complete command surface
packages/…/run-command.tsShows the shared target, output, cancellation, and failure boundary
packages/…/resolve-target.tsShows saved credentials, environment targets, OAuth refresh, and proxy settings entering a request
packages/…/run-local-start-command.tsShows how a local server image becomes a ready development environment
packages/…/create-app-project.tsShows the safe boundary for creating a local project
packages/…/prepare-app-add-files.tsShows how entity input becomes local definitions and optional object companions
packages/…/manifest-build.tsShows how local SDK definitions become an application manifest
packages/…/manifest-validate.tsShows the broad local validation boundary before remote work
packages/…/compile-application.tsShows how manifest, source, translations, and typecheck become one build result
packages/…/README.mdStates the snapshot, source inventory, and upload contract
packages/…/format-app-plan.tsShows destructive change warnings, cascade display, and secret redaction
packages/…/run-app-apply-command.tsShows the build, upload, sync, pull-base, and client-generation lifecycle
packages/…/upload-app-files.tsShows verified artifact upload and failure reporting
packages/…/run-app-dev-command.tsShows the watch, rebuild, sync, and recovery loop
packages/…/run-app-pull-command.tsShows workspace export, project creation, and local reconciliation behavior
packages/…/pull-application.tsShows how export, fingerprints, source reconciliation, and one local transaction form a pull
packages/…/README.mdStates pull coverage, baseline, source, and recovery limits
packages/…/plan-source-definition-writes.tsShows how definition source is restored and checked for conflicts
packages/…/plan-application-source-writes.tsShows how additional application source is restored and fingerprinted
packages/…/README.mdDefines ownership and failure behavior for generated client files
packages/…/run-data-export-command.tsShows the record export job, progress, and local file handoff
packages/twenty-cli/app-template/.nvmrcPins the Node version used by generated application workflows
packages/…/publish.ymlShows npm trusted publishing, provenance, and package publication from the generated app workflow
packages/…/define-connection-provider.tsShows the authoring contract for application connection providers
packages/…/define-messaging-provider.tsShows the authoring contract for messaging providers and their logic links
packages/…/index.tsShows the runtime boundary for deployed logic functions