The open alternative to Salesforce, designed for AI.
CLI application pull
Pull reconciles the server's application export with local definitions and a target-bound baseline. It preserves unsupported and local-only entities, reports overwritten local edits, and commits source changes and the new baseline as one transaction. Source generation and translation behavior are covered by parity and reconciliation tests.
See the app tooling overview for package boundaries.
Contract
- An existing application's local identifier selects the target. With no local definition, the command fetches
currentWorkspace.workspaceCustomApplication.universalIdentifier. Apply baseline recording still queries only the workspace ID. - Outside an app, pull offers to create a local project and install its dependencies before reconciliation. Noninteractive creation requires
--pathand--yes. The initializer omits demo entities, and unrelated nonempty directories are refused. - Missing custom applications fail before project creation. The worker still checks that the local identity matches the export before writing.
- Source scanning stays inside the disposable CLI worker so configs containing functions are never serialized through IPC. Only the server export and report cross that boundary. Selected credentials are removed from the worker environment. App source is trusted developer code, not sandboxed code.
- The wire/export and baseline boundary check identity and envelope fields, not every metadata collection.
toPullManifestis the single explicit assertion into the typed writers, preserving their trust in the server schema. Missing/null object and field collections are consumed with?? [], like the other collections. Malformed entity contents can still make reconciliation fail before writing. We do not duplicate the server's schema. - The baseline file is an envelope whose
manifestmember is anExportedManifest. Reconciliation walks arrays generically without maintaining a second collection list. Unrecognized collections and non-array metadata survive; protected or unreconciled definitions retain their prior baseline entries. preparePullEntitiesresolves the source layout once for current and baseline entities. Planning, overwrite reporting and nested-definition protection consume these prepared entities. A definition can leave a parent only when another retained or written file contains it, or its remote deletion is confirmed.- Fields already declared with
defineFieldstay in their existing files, even when the server exports them inside an object. Object generation excludes those fields; baseline comparisons use the same source layout. Pull also removes duplicate inline copies left in object files, while retaining the standalone definitions. - Before destination writes,
assertPullSdkExportschecks the actual imports emitted by the writer against the app's SDK. It checks export presence, not every config shape; run typecheck to validate the generated definitions against the installed SDK. - Temporary files and the baseline live under
.twenty/cli. Apply and pull sharecreatePullBaseWriteas the serializer. The baseline is bound to the API URL, workspace UUID and application UUID. Pull stages it with mode 0600 and writes it after the source files. - The baseline can carry
sourceFingerprints, a SHA-256 per app-relative source, locale and dependency file. Apply captures them before building. Pull reports an overwritten local change when a file it rewrites or deletes no longer matches its fingerprint. Without a fingerprint it compares the file with the writer's rendering of the baseline, which is reliable only for source produced by that writer. Pull carries fingerprints forward, updating the files it writes and dropping the ones it deletes. - Ordinary I/O failures restore originals. Cancellation is checked before committing the staged plan, not halfway through it. An acknowledged successful commit wins over cancellation. The parent can forcibly kill an unresponsive worker after its grace period, so an unacknowledged result has outcome
unknown, never a claim that rollback succeeded. Failed rollback retains backups and reports their directory; failure to clean up after a completed commit has outcomepulled. - Human reporting uses CLI terminal escaping, machine reporting contains the full coverage and path lists, and gaps warn without stopping successful writes. Unknown coverage status strings remain visible. Pull does not prompt for approval or require a clean Git checkout; remote changes overwrite conflicting local edits and are included in the report.
Translation string extraction uses the CLI's TypeScript parser. Traversal, static-string rules, whitespace normalization and deduplication are checked against the SDK reference by parity tests. It does not depend on ts-morph or load parser tooling for help and command discovery.
Workflows arrive in manifest.workflows and are written as defineWorkflow files. Their filter operands and form field types use SDK enums; filter group logical operators stay string literals, which every SDK with defineWorkflow accepts. A workflow the server cannot express as a definition is reported as UNSUPPORTED coverage, so its local file is kept.
Skills and agents arrive in manifest.skills and manifest.agents and are written as defineSkill and defineAgent files, with no enum bindings. The server exports one only when its definition reproduces the stored entity; otherwise it is reported as UNSUPPORTED coverage, so its local file is kept.
Pull requests exportApplication(shouldIncludeDependencies: true). Export defaults to metadata-only files (files: []) for existing clients and apply baselines. Pull restores dependencies/package.json and dependencies/yarn.lock to the project root, in the same transaction as metadata and the baseline. Exact folder and filename checks reject all other exported files, including record attachments, public assets and source. If the remote package omits twenty-sdk, pull retains the local SDK dependency so the workspace custom app remains usable with the CLI. The baseline stores remote dependencyFingerprints separately from written sourceFingerprints for this case. Other exported dependency contents are copied exactly. Dependency files unchanged on the server preserve local edits; remote changes replace local contents and use the usual overwrite report. Missing remote files leave local files untouched. Pull does not install dependencies, generate the typed client or write logic-function/front-component source. Export responses have a 16 MiB cap. Pull does not modify the workspace. Because pull is partial, app apply of the workspace custom application only deletes entities missing from source with --prune.
Tests cover writers, planning and reconciliation. Command tests build the actual Vite worker, exercise an authoring-only SDK, local mock HTTP, credentials/output isolation, SDK export refusal and forced termination after the first destination write. The repository SDK tests cover canonical generated definitions, nested coverage, translation preservation, target mismatch, overwrite reporting and rollback.