Reference

The quickstart covers init, plan, doctor, and install. The rest of the command surface, for reviewed updates, shared graphs, observability, and install records:

# Build caboodle from source instead of the release installer.
cargo install --git https://github.com/scbrown/caboodle --locked

# Report what would block an install here. Changes nothing; exits nonzero on a blocker.
caboodle doctor

# Answer the use-shaped interview. It asks who the themed crew members are and
# which questions the finished graph must answer, then only writes a plan.
caboodle init --guided

# Or supply the same intended-use contract non-interactively.
caboodle plan --profile retrieval --intent caboodle-intent.toml

# Optionally add canonical Quipu share directories to the reviewed corpus.
# The target database is explicit; apply stages imports but never promotes them.
caboodle plan --profile retrieval --share ./team-share --quipu-db ./knowledge.db

# Converge the reviewed plan, then prove each tool with a round trip.
caboodle apply
caboodle verify
caboodle verify-questions

# Or run both phases together after review.
caboodle install

# Ask whether the running stack matches this Caboodle build's reviewed pins.
# The command exits nonzero when anything is missing, unreadable, or drifted.
caboodle check-updates

# Converge only drifted tools, read every version back, and functionally verify
# each changed tool before recording it as current.
caboodle update

# A full tool + crew plan is explicit and reviewable.
caboodle plan --profile everything --crew both

apply installs a missing released tool and reads its version back; Bobbin comes from its checksummed release bundle (including its runtime), not a source build. A successful installer exit alone is not accepted. verify proves a marker is absent first, writes/indexes it, and then requires the reader path to return it. Every check uses a temporary isolated store; camayoc’s starts and stops its own scratch quipu server (see installed files). Progress is written atomically to .caboodle/state.json, so rerunning converges and preserves a still-current verified result.

check-updates compares the running identities with the release versions and source revisions pinned in the selected plan’s Caboodle build. It does not use an unreviewed “latest” endpoint. update is the mutation half: it installs only drifted selections through their existing checksummed/source-pinned adapters, requires version read-back to match the reviewed identity, runs the adapter’s functional proof, and only then records an updated transition. A second run is current and performs no installation. This keeps release selection in review while making deployed-versus-released drift executable rather than anecdotal.

If the interview loses input or its caller stops, rerun caboodle init --guided: accepted answers resume from .caboodle/interview.toml. The session disappears only after the complete plan has been written successfully.

The interview works backward from expected use. Each crew member has a free-form theme, domain, and role rather than a closed role enum. Each anticipated ontology question records its expected answer shape, the seed facts needed to exercise it, an executable SELECT/ASK query, and a result marker. caboodle verify-questions runs those reader-path checks after installation. Empty, duplicate, credential-bearing, or non-executable entries are refused before a plan is written.

Installable profiles today are kg (Quipu + Camayoc), retrieval (plus Bobbin), code-intel (plus Yupana), everything (plus Desire Path and, when selected with --crew, Shantytown/Creel), and crew (Shantytown, Creel, both, or standalone). CABOODLE installs checksum-pinned Shantytown and Creel distributions. Creel verification remains browser-owned: it requires explicit machine-readable doctor and admission documents and refuses missing, unknown, unredacted, or non-admit evidence. See the crew capability contracts.

Until Camayoc publishes core.pendant, CABOODLE installs its checksum-pinned bootstrap distribution: ontology, shapes, queries, and the same fail-closed gate proof. Verification then proves a separate first ingest with an absent control, reader-path retrieval, and an idempotent replay. Use --skip-install when package installation belongs to another system; the version and functional checks still run.

Yupana installs from its checksum-pinned v0.12.7 release and proves callers on an isolated fixture repository. CABOODLE builds Desire Path from the revision its v0.3.2 tag names (1f457ec), stamps that identity into dp version, and proves an isolated ingest/list round trip. Neither verification can write into the user’s normal Yupana state or Desire Path DB.

caboodle render-observability converts the reviewed selection plus explicit generic targets into Prometheus scrape config, starter alerts, a dashboard, and versioned contracts. validate-observability fails closed on missing targets or uncovered metrics; rendering is review-only and never claims a live scrape.

Applied/verified transitions and br JSONL lifecycle snapshots queue as redacted, content-addressed Quipu episodes. flush-episodes requires an HTTPS endpoint plus an environment-only token, proves a query marker first, and keeps the identical bytes pending on ambiguous delivery.

Profiles can also consume one or more directories produced by quipu share. Caboodle passes each directory unchanged to quipu import, records the returned share ID, staging graph, eligibility, and blockers in .caboodle/state.json, and leaves ROOT promotion to the explicit quipu import promote review step. Non-conforming or off-vocabulary shares remain quarantined and visible rather than being reshaped into a Caboodle-specific bundle.

Command and option index

Run caboodle <command> --help for that command’s complete option syntax. The table covers the current source tree; published binaries may lag new commands.

Files and configuration

The configuration reference documents plan, state, intent, environment variables and observability targets.

Words you will see

Quipu paired release updates

caboodle update-release --tool quipu --plan caboodle-plan.toml selects the exact version and per-target SHA256 in release-pins/quipu.toml, rather than implicitly trusting the latest release or its downloaded checksum. The publication must provide the expected archive and checksum exactly once; both the archive bytes and published sum must agree with the reviewed digest.

The plan must select a local release-flavor Quipu. Both quipu and quipu-server must be regular files selected by PATH in CARGO_HOME/bin (default $HOME/.cargo/bin), with matching versions. External servers, LanceDB source builds, shadowed paths, symlinks, downgrades, mixed versions and equal versions with different bytes are refused. The install does not restart any service or load data into a running store.

Both executables are backed up before either is replaced. The existing release lock and pending journal protect the pair; failed installed verification or an interrupted swap restores both prior binaries and the exact prior state. A corrupt backup retains the journal and refuses recovery before changing either file. Backup file renames and every ancestor directory entry are synced before the pair journal becomes durable; its removal is synced before success. A failed clear barrier reports uncertain completion and attempts to retain the exact pending record for later recovery. Failed retention remains an error, never a claim that completion or restoration is proved. Existing single-binary journals and Seeds rollback remain supported. This does not extend rollback-seeds to other tools.

Verification performs the existing negative/positive client and vocabulary round trips in temporary stores and checks the server version/help contract. It does not prove a running server, service restart, database migration or host delivery. --check inspects publication metadata without downloading or replacing executables and explicitly reports that checksum/functional proof has not run. Source pin updates still require review; no automatic pin writer or host schedule is introduced by this command.

Camayoc has no published release, and Shantytown’s wheel release lacks a checksum asset. Their explicit refusals preserve these missing trust anchors; source bundles and wheels are not guessed into standalone binaries.