CLI

Every tool is a standalone Node.js script run with node <tool>.mjs. The engine is dependency-free, so there is nothing to install first. Each tool accepts --help (-h) and prints its own usage. The examples below run against the bundled demo manifest, apps/playground/manifest.json.

resolver.mjs

Resolves one OKF concept across the layer stack into an effective concept — section merge, level precedence, provenance, and per-section conflicts — and prints it as JSON.

node resolver.mjs --manifest <file> --concept <id> [--profile <id>]

Flag	Required	Meaning
--manifest <file>	yes	Path to the layers manifest.
--concept <id>	yes	Concept ID to resolve, e.g. decisions/primary-db.
--profile <id>	no	Select this profile before inspecting the working directory.
--help, -h	no	Print usage and exit.

node resolver.mjs --manifest apps/playground/manifest.json --concept decisions/primary-db

Output is the effective concept: contributors (each layer with its level and last-updated date), frontmatter, frontmatterProvenance, and sections[], where each section carries the sourceLayer that won it and an optional conflicts array for dissenting layers. See Merge semantics.

mcp-server.mjs

Runs the stdio MCP server that exposes the resolved cascade to AI agents. Runs in cascade mode (a manifest) or the legacy two-layer mode (explicit personal + shared directories).

node mcp-server.mjs --manifest <file> [--profile <id>]
node mcp-server.mjs --personal <dir> --shared <dir>

Flag	Required	Meaning
--manifest <file>	one mode	Cascade mode: resolve the full stack in the manifest.
--profile <id>	no	Explicit profile override. Otherwise the server uses its startup working directory, then default.
--personal <dir>	one mode	Legacy mode: personal bundle directory (level 3). Use with --shared.
--shared <dir>	one mode	Legacy mode: shared bundle directory (level 0). Use with --personal.
--help, -h	no	Print usage and exit.

Provide either --manifest, or both --personal and --shared.

node mcp-server.mjs --manifest apps/playground/manifest.json

The server speaks MCP over stdin/stdout. See MCP tools for the tools it exposes and Connect an agent for wiring it into a client.

The MCP initialization instructions identify the stable profile id and reason (explicit, project, default, or legacy-default) without including a local project path. The human-readable label is returned as structured initialization metadata rather than instruction prose, so synced display text cannot become an agent directive. Selection is fixed for that process lifetime.

profile

Inspects and manages local Project Profiles without opening source adapters:

contextcake profile current [--profile <id>] [--json]
contextcake profile list [--json]
contextcake profile create <label> [--project <path>]
contextcake profile map <id> <path>
contextcake profile unmap <path>
contextcake profile delete <id> [--confirm]

current reports the selected id, label, reason, and matched root when one applies. create is the deliberate migration point for a flat manifest and returns the verified backup path. Project folders are canonicalized locally and never synced. delete refuses default, previews affected mappings and Pack assignments, and requires --confirm; it removes references but never source, Pack, overlay, cache, or live-repository files.

ingest.mjs

Classifies a list of normalized repo signal events through the context policy and writes a dashboard-ready signals.json (signals plus per-repo coverage).

node ingest.mjs --events <file> --out <file>

Flag	Required	Default	Meaning
--events <file>	no	packages/core/fixtures/mock-events.json	Normalized event list to classify.
--repos <file>	no	packages/core/fixtures/repos.json	Repo config (owners, areas) for coverage summaries.
--out <file>	no	apps/control-surface/signals.json	Where to write the signals output.
--policy <file>	no	packages/core/fixtures/context-policy.json	Classification rules.
--demo	no	—	Use the bundled mock events.
--help, -h	no	—	Print usage and exit.

node ingest.mjs --events packages/core/fixtures/mock-events.json --out apps/control-surface/signals.json

The output feeds write.mjs and the control-surface dashboard. See The capture write path.

pack.mjs

Inspects, installs, updates, rolls back, and detaches content-only ContextCake Packs. This is a local workflow: no account is required. Installed versions are immutable, and remove detaches the Pack layer without deleting the files.

node pack.mjs inspect <directory> [--checksum sha256:...]
node pack.mjs install <directory> --manifest <file> [--packs-dir <directory>] [--profile <id>] [--level <n>] [--checksum sha256:...]
node pack.mjs update <directory> --manifest <file> [--packs-dir <directory>] [--profile <id>] [--checksum sha256:...]
node pack.mjs update <directory> --manifest <file> --apply [--packs-dir <directory>] [--profile <id>] [--level <n>] [--checksum sha256:...]
node pack.mjs list --manifest <file>
node pack.mjs rollback <id> --manifest <file> [--packs-dir <directory>] [--profile <id>] [--version <semver>]
node pack.mjs remove <id> --manifest <file> [--profile <id>]

inspect checks PACK.yaml, its creator/license/rights/freshness metadata, the content-only permission declaration, file types, size limits, symlinks, and the Pack’s SHA-256 tree checksum. install repeats those checks, copies the release to a versioned Pack store next to the manifest, and adds an explicit okf-local base layer. update first returns a non-mutating file-level diff; repeat it with --apply to retain and switch to the candidate version. Use --packs-dir to choose a different local store and --level to choose precedence.

node pack.mjs inspect ./my-pack
node pack.mjs install ./my-pack --manifest ~/Library/Application\ Support/ContextCake/manifest.json --level 0
node pack.mjs rollback my-pack --manifest ~/Library/Application\ Support/ContextCake/manifest.json

The packaged contextcake CLI exposes the same commands under contextcake pack and defaults the manifest to the desktop app’s local manifest.

write.mjs

Writes captured OKF concepts from an ingest signals.json into a target layer bundle. team_candidate signals are written directly; review_required signals are staged under _review/ for human approval; ignore and local are skipped.

node write.mjs --signals <file> --manifest <file> [--profile <id>] --target-layer <name>

Flag	Required	Meaning
--signals <file>	yes	The signals.json produced by ingest.mjs.
--manifest <file>	yes	Manifest whose layers name the write targets.
--profile <id>	no	Explicit profile override; otherwise use cwd mapping then default.
--target-layer <name>	no	Curated local OKF layer to write into. Plain Markdown folders and live layers are rejected. Defaults to the highest eligible layer below the top of the cascade.
--dry-run	no	Report what would be written without touching disk.
--help, -h	no	Print usage and exit.

node write.mjs --signals apps/control-surface/signals.json --manifest apps/playground/manifest.json --target-layer team --dry-run

See The capture write path.

promote.mjs

Profile-aware live promotion resolves both the live source and curated target from one selected profile:

node promote.mjs --manifest <file> [--profile <id>] --capture <id> --target-layer <name> [--dest <id>]
node promote.mjs --manifest <file> [--profile <id>] --approve <review-file> --target-layer <name> [--telemetry]

The review file records the profile id, manifest revision, live-layer and target-layer fingerprints, capture id, destination, and capture-content hash. Approval fails closed if configuration or capture content changed after staging.

The old directory-to-directory commands remain available only as an explicit advanced compatibility mode and carry no Project Profile isolation guarantee:

node promote.mjs --legacy-paths --from-live <root> --capture <id> --target <root>
node promote.mjs --legacy-paths --personal <dir> --shared <dir> --file <concept-or-path> [--dry-run] [--print-git]

See Promoting concepts.

classify-context.mjs

Classifies a single repo or team signal event into ignore, local, team_candidate, or review_required, and prints the classification as JSON. This is the per-event core that ingest.mjs runs in batch.

node classify-context.mjs --event <file>

Flag	Required	Meaning
--event <file>	one mode	Event JSON to classify.
--demo	one mode	Classify a bundled sample event instead.
--policy <file>	no	Classification rules. Defaults to packages/core/fixtures/context-policy.json.
--help, -h	no	Print usage and exit.

Provide either --event or --demo.

node classify-context.mjs --demo

Related

• layers.json manifest — the file every --manifest flag points at
• MCP tools — what mcp-server.mjs exposes
• Override syntax — controlling the merge from frontmatter
• ContextCake Packs — inspect the public catalog and complete file structures