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
| Trigger | Consequence | Guard |
|---|---|---|
| Only one API target environment variable is set | The CLI cannot identify a valid workspace target | Set both the API URL and API key, or use a saved remote |
| A saved remote name points to another URL | Login or local startup can target the wrong server or stop before saving | Confirm the URL and pass --replace only when the move is intended |
| A proxy header overrides a CLI-owned header or contains invalid characters | The request is rejected before it reaches the workspace | Use valid Name: value lines and let the CLI set authorization headers |
| Docker uses a remote socket or invalid context | Local commands can affect an unintended Docker host or stop before work starts | Select a local Docker context and unset a remote DOCKER_HOST override |
The app's engines.twenty range has no matching image | Local start cannot select a compatible image | Fix the range or pass an explicit image version |
local reset is approved for the wrong environment | The selected local database, files, and analytics data are deleted | Check the environment and use --test only for the test instance |
| The app lacks a supported SDK or TypeScript setup | Build or typecheck stops before a deployable snapshot exists | Install the supported app SDK and compiler with the supported Node and Yarn setup |
| An app definition has an invalid identity, relation, role, or provider link | Build fails before delivery | Review generated identifiers and run app build before planning |
app apply infers missing source entities as deletions | Workspace metadata and stored data can be removed | Review app plan and use --no-prune when source coverage is incomplete |
| Apply fails after workspace synchronization | The workspace may contain the new version while the pull base or client is incomplete | Read the phase and outcome, run app plan, then repair follow-up work before retrying |
| A published package is treated as installed | The workspace remains unchanged even though a package version exists | Run app install or use app apply for local source synchronization |
app pull uses the wrong identity, workspace, or unmatched baseline | Local definitions can be replaced by another app's export or local deletions can be missed | Check the selected remote, application identity, pull report, and baseline status |
| A workspace export includes unsupported files, missing source, or coverage gaps | Some workspace state is not written locally, or pull stops before writes | Read coverage and skipped entries, then restore unsupported state deliberately |
| A source definition moves locally while its server source inventory still uses the old path | Pull refuses to restore the definition's imported files | Move 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 changed | Pull can replace local content and report an overwritten edit | Review fingerprints and the pull report before building |
| A nested local definition would disappear during replacement | Pull preserves the parent file and reports it as skipped | Review skipped entities and resolve the local ownership before pulling again |
| Pull is interrupted during its file commit or baseline write | The result can be unknown and backups can remain for recovery | Inspect local changes and the reported backup path before retrying |
| A source change arrives during a pending development confirmation or sync | The old revision is discarded or the session requests a fresh plan | Wait for the next revision and review its new plan |
| npm trusted publishing is not configured for the repository and workflow | Public package publishing cannot create the required provenance record | Register the repository and publish.yml as an npm trusted publisher |
A package's files field omits manifest.json or generated app files | npm publication stops after packing and the package is not published | Include the manifest and generated files in the package contents |
| A private registry upload or registration ends with an unknown result | The package may exist in the registry even though the CLI reports failure | Check the registry with the reported upload file ID before retrying |
| A record export is interrupted or its download link expires | The CSV is not complete and cannot be resumed | Run the export again and keep the command connected until it finishes |
| The app has no own generated-client package directory | Apply or dev skips client generation, or generate-client fails | Install twenty-client-sdk in the app itself and regenerate after synchronization |
Key files
| File | Why to read it |
|---|---|
| packages/…/README.md | States the standalone CLI boundary, supported runtime, and shortest application workflow |
| packages/…/package.json | Defines the published CLI package and its runtime tool boundary |
| packages/…/commands.md | Gives user-facing behavior, permissions, safeguards, output, and recovery rules |
| packages/…/command-catalog.ts | Shows the complete command surface |
| packages/…/run-command.ts | Shows the shared target, output, cancellation, and failure boundary |
| packages/…/resolve-target.ts | Shows saved credentials, environment targets, OAuth refresh, and proxy settings entering a request |
| packages/…/run-local-start-command.ts | Shows how a local server image becomes a ready development environment |
| packages/…/create-app-project.ts | Shows the safe boundary for creating a local project |
| packages/…/prepare-app-add-files.ts | Shows how entity input becomes local definitions and optional object companions |
| packages/…/manifest-build.ts | Shows how local SDK definitions become an application manifest |
| packages/…/manifest-validate.ts | Shows the broad local validation boundary before remote work |
| packages/…/compile-application.ts | Shows how manifest, source, translations, and typecheck become one build result |
| packages/…/README.md | States the snapshot, source inventory, and upload contract |
| packages/…/format-app-plan.ts | Shows destructive change warnings, cascade display, and secret redaction |
| packages/…/run-app-apply-command.ts | Shows the build, upload, sync, pull-base, and client-generation lifecycle |
| packages/…/upload-app-files.ts | Shows verified artifact upload and failure reporting |
| packages/…/run-app-dev-command.ts | Shows the watch, rebuild, sync, and recovery loop |
| packages/…/run-app-pull-command.ts | Shows workspace export, project creation, and local reconciliation behavior |
| packages/…/pull-application.ts | Shows how export, fingerprints, source reconciliation, and one local transaction form a pull |
| packages/…/README.md | States pull coverage, baseline, source, and recovery limits |
| packages/…/plan-source-definition-writes.ts | Shows how definition source is restored and checked for conflicts |
| packages/…/plan-application-source-writes.ts | Shows how additional application source is restored and fingerprinted |
| packages/…/README.md | Defines ownership and failure behavior for generated client files |
| packages/…/run-data-export-command.ts | Shows the record export job, progress, and local file handoff |
packages/twenty-cli/app-template/.nvmrc | Pins the Node version used by generated application workflows |
| packages/…/publish.yml | Shows npm trusted publishing, provenance, and package publication from the generated app workflow |
| packages/…/define-connection-provider.ts | Shows the authoring contract for application connection providers |
| packages/…/define-messaging-provider.ts | Shows the authoring contract for messaging providers and their logic links |
| packages/…/index.ts | Shows the runtime boundary for deployed logic functions |