Versioning

Chroma uses semver. Every modification to the engine, CLI, or the standalone Chroma-CLI/ package must increment the version in the same change.

The current version is the single line in Chroma/VERSION. After this change it is 0.3.1.

Where the version lives

• chroma --version / -v reads the VERSION file next to the script first (repo or standalone package), then $CHROMA_HOME/VERSION.
• Output format: Chroma vX.Y.Z (also printed briefly at the start of every command except help / --version).

There is no second hardcoded version string in the CLI.

When to bump

Agents and humans follow the same table. Cursor rules:

• .cursor/rules/chroma-versioning.mdc — Chroma engine + CLI
• .cursor/rules/chroma-desktop-versioning.mdc — Chroma Desktop only
• .cursor/rules/chroma-desktop-cli-versioning.mdc — combined overview (both products)

How to bump

Chroma CLI (engine + chroma command)

From the TargApps workspace root:

./scripts/bump-chroma-cli-version.sh              # patch (alias of bump-chroma-version.sh)
./scripts/bump-chroma-cli-version.sh minor
./scripts/bump-chroma-cli-version.sh major

Equivalent:

./scripts/bump-chroma-version.sh              # patch
./scripts/bump-chroma-version.sh minor
./scripts/bump-chroma-version.sh major

The script updates Chroma/VERSION, Chroma/Cargo.toml, Chroma/pkg/package.json, and (if present) Chroma-CLI/VERSION plus Chroma-CLI/pkg/package.json. Recompiling the WASM engine (Chroma/build.sh) regenerates pkg/package.json from Cargo.toml.

Chroma Desktop

./scripts/bump-chroma-desktop-version.sh              # patch
./scripts/bump-chroma-desktop-version.sh minor
./scripts/bump-chroma-desktop-version.sh major

Updates Chroma-Desktop/VERSION, Cargo.toml, and tauri.conf.json. Desktop versioning is independent from the CLI/engine semver.

This versioning system itself is a Chroma change, so the version moved 0.1.0 → 0.1.1 (patch). The NestJS-style CLI logger is a new capability, so the version moved 0.1.1 → 0.2.0 (minor).

Reinstall on the system

chroma install wipes $CHROMA_HOME by default and rebuilds it from the checkout (clean reinstall). From a monorepo checkout:

./Chroma/cli/chroma.sh install

From the standalone package (Chroma-CLI/ or a downloaded chroma-cli.zip):

./chroma.sh install

Pass --no-rebase-root to update in place without deleting $CHROMA_HOME. After install, chroma --version must print Chroma v<VERSION>.

See CLI for toolchain provisioning, PATH, and templates.

Full local stack update

After engine or CLI changes, rebuild and sync everything with one command:

./scripts/update-chroma-stack.sh

This runs WASM build, plugin sync, Chroma-Fs (if present), Chroma-Server, CLI install to ~/.chroma, consumer pkg/ copies, Chroma-Desktop, and Targ-Apps-Finance. Partial flags (--cli-only, etc.) exist for advanced use; see ./scripts/update-chroma-stack.sh --help.

Sync vendored pkg/ in consumer apps

Apps that vendor the compiled WASM engine (engine.vendorDir: "pkg" in chroma.json) must keep pkg/package.json aligned with Chroma/VERSION. The workspace script automates discovery, copy, and verification:

./scripts/update-chroma-consumers.sh              # copy fresh pkg/ + verify
./scripts/update-chroma-consumers.sh --check-only # verify without copying
./scripts/update-chroma-consumers.sh --rebuild    # force Chroma/build.sh first
./scripts/update-chroma-consumers.sh check        # NestJS log format smoke test

Source order (documented in the script): Chroma/pkg/ after Chroma/build.sh, then Chroma-CLI/pkg/ (synced by build.sh). If neither matches Chroma/VERSION, the script runs Chroma/build.sh unless --check-only is set.

Consumers discovered today: projects with chroma.json + vendored pkg/ (e.g. Targ-Apps-Finance), plus Chroma-Desktop/pkg and Chroma-Desktop/src/view/pkg. Template trees under Chroma/cli/examples, Chroma-CLI/examples, and Chroma/example are excluded.

Each step logs with the same NestJS-style format as chroma ([Chroma] {pid} - {timestamp} LOG [UpdateConsumers] …). After copy, the script prints PASS or FAIL per project and exits non-zero on any mismatch.

Typical workflow after bumping Chroma:

./scripts/bump-chroma-cli-version.sh
./scripts/update-chroma-stack.sh       # one command: WASM, CLI, consumers, Desktop, Finance

For release packaging (zip, installers, docs downloads), use ./scripts/build-chroma-cli.sh instead. To sync only vendored pkg/ copies:

./scripts/update-chroma-consumers.sh

chroma build copies chroma.json into the output directory (dist/ by default) for both static and dynamic apps.