Skip to content

The open alternative to Salesforce, designed for AI.

9.0 KB
Raw Blame

Contributing to Twenty CLI

This package is the twenty executable in the Twenty monorepo. Its Nx project is named twenty-cli; its Yarn workspace and npm package are named twenty. Follow the repository's development instructions and nearby code conventions.

Build and verify

Run these from the repository root after installing its dependencies:

yarn nx build twenty-cli
node packages/twenty-cli/dist/cli.cjs --help
yarn nx lint twenty-cli
yarn exec tsgo -p packages/twenty-cli/tsconfig.json --noEmit

Tests that use real applications or SDK parity references require the repository SDK to be built. Its Nx target builds its dependencies:

yarn nx build twenty-sdk
cd packages/twenty-cli
yarn exec vitest run --maxWorkers=2

For a focused change, pass its test file or directory to vitest run. Command tests execute the public command runner with local HTTP fixtures. Worker tests exercise subprocess output, cancellation and snapshot lifetime. Parity suites compare generated source and artifacts against the SDK implementation; the SDK is a test reference, not a runtime tooling dependency.

Rebuild twenty-shared with --skip-nx-cache after switching branches or changing shared exports. Generated dist directories are not tracked, and stale outputs can invalidate dependent test and typecheck results. Use the direct TypeScript command above when checking a fix rather than relying on an Nx cache hit.

No live workspace is required for the unit suite. Passing it does not establish live authorization, remote upload or server-version compatibility. Exercise changed server workflows against a disposable workspace when appropriate.

Package map

Location Responsibility
src/catalog Command definitions, topics and lazy handler loading
src/commands Command orchestration and user-visible results
src/program Argument parsing, target setup, interaction and command lifecycle
src/config, src/target, src/oauth Saved connections, target selection and authentication
src/transport HTTP/GraphQL requests, proxy routing, limits and cancellation
src/metadata, src/data Workspace metadata inspection and record reads
src/local Local development instance lifecycle, Docker subprocesses, image selection and readiness
src/doctor Read-only setup and connection diagnostics
src/app Project tooling and application lifecycle, see its module map
src/input, src/output Input parsing, human/JSON/NDJSON output and error contracts
app-template App source, configuration and CLI-based integration-test harness copied by app init

Command definitions are the source for help and twenty commands. Keep handlers lazy so discovery does not load compiler or app code. Put a workflow's rules in its owning module; a command handler should connect parsed input, that module and output. Preserve meaningful behavior tests when moving implementation files.

Application tooling guarantees

The application module documentation describes each stage. Changes must preserve these contracts:

  • App definitions execute as trusted code in a disposable worker. The worker contains process exits, filters CLI credentials and captures bounded output; it is not a filesystem or network sandbox. Executable configs stay in the worker, and only serializable requests and results cross IPC.
  • A build's immutable snapshot stays alive until its consumers finish. Uploads verify containment, size and checksums. Failed or cancelled work must release the snapshots it owns without removing another build's files.
  • Apply reports which remote phases completed and whether the outcome is known. Do not retry writes or claim rollback when the server's result is unknown. Each apply uses a fresh plan; approval does not carry across dev revisions.
  • Pull stages source writes and its target-bound baseline together. Ordinary failures restore originals; interrupted workers and failed rollback report uncertainty and retain recovery information. Unsupported definitions remain visible in coverage reports.
  • JSON emits one result envelope. Streaming commands honor backpressure, bound buffering and emit a terminal result or error. Cancellation exits 130 unless the operation has already acknowledged its completed result.

Packaging

Vite builds the CLI, its worker and lazy chunks into dist. It also copies the CLI-owned app-template there. Chokidar, esbuild, tinyglobby and the CLI's TypeScript parser are runtime dependencies; other imported libraries are bundled. The parser is separate from the app's compiler used for typechecking.

The archive includes the command reference, contributor guide and application module READMEs so their relative links also work outside a repository checkout. It does not include the CLI's TypeScript implementation or tests.

For packaging changes, run the build and installation checks:

yarn nx run twenty-cli:test:package

This runs the binary declared in the workspace's package.json directly, packs the CLI, and installs the archive with only its production dependencies in a temporary directory outside the monorepo. It checks help, offline doctor, app initialization including the integration-test harness, and a compiler diagnostic from the installed worker. npm registry access is required for installation; the commands do not contact a Twenty workspace. Temporary files are removed afterward, and nothing is published. CI runs the same target for CLI and dependency changes.

The CLI CI job also runs scripts/test-app-publish.mjs after building the CLI and SDK. It starts a disposable Verdaccio registry with no upstream registries, publishes a fixture with real npm, downloads and inspects the tarball, and checks version rejection, incomplete packages and cleanup. On Linux CI the test runs inside a network namespace with only loopback enabled, so it cannot reach public npm. It uses temporary npm configuration and a local test token.

Releases

Publish the CLI when its changes warrant a release. A server release does not require a CLI release; skip versions when the CLI has no changes worth shipping. When publishing, aim to align the CLI version with the corresponding Twenty server, SDK and UI version.

Publishing is independent through the cli/ tag family: cli/v2.46.0 publishes only [email protected]. The tag version must match packages/twenty-cli/package.json. Bumping the package version alone does not publish the CLI.

app init pins twenty-client-sdk, twenty-sdk and twenty-ui to the twenty-sdk version of the commit the CLI was built from. main moves to the next, unpublished SDK version right after each SDK release:

  1. Start from the matching sdk/vA.B.C release commit. If a CLI version bump is still needed, make it on a branch from that commit.
  2. Once the SDK, client SDK and UI packages at A.B.C are on npm, tag the prepared commit cli/vA.B.C.
  3. Run the Publish npm packages workflow in twenty-infra with that tag as its ref. Creating the tag alone does not publish the package.

yarn npm publish first runs scripts/prepublish.mjs, which needs a fresh build and npm registry access. It checks the build first, and fails when the executable, worker, lazy chunks or templates are missing, when dist was built for another version, when one of its CLI runs fails or times out, or when app init would pin versions that are not on npm. An unreachable registry is reported separately from a missing version. The check does not read tags: it confirms that the pinned versions are published. Selecting the matching SDK release remains a release step.

Once the check passes, the script resolves the built app template's dependencies, with the versions that app init pinned during the check, using the repository's Yarn against the public registry, under a 3-day minimum release age that exempts the pinned Twenty packages. It then writes dist/app-template/yarn.lock. Apps created with app init then install exact, integrity-checked versions, including for people who enforce a minimum release age. The lockfile keeps the template's placeholder name, and the first yarn install renames that root entry.

The tests of both steps run with twenty-cli:test:package. To run the script before tagging:

yarn nx build twenty-cli
node packages/twenty-cli/scripts/prepublish.mjs

App integration tests

app-template/ contains the shared project scaffold. app init layers app-template/example/files/ and example/scripts.json onto it; app pull uses only the shared scaffold before writing the exported definitions.

app-template/example/files/src/__tests__ supplies the integration-test setup for CLI-created apps. It deploys the app before tests and uninstalls it afterward by invoking the installed CLI with --json. Apps invoke the executable rather than import the CLI as a library or add it as a dependency. See the template contract for executable selection and the compiler requirements for project setup.