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>] [--cwd <path>] [--json]
contextcake profile list [--json]
contextcake profile show [<id>] [--json]
contextcake profile create <label> [--project <path>]
contextcake profile rename <id> <label>
contextcake profile clone <id> <label>
contextcake profile map <id> <path>
contextcake profile unmap <path>
contextcake profile delete <id> [--confirm]
contextcake profile purge-state <id> [--confirm]

current reports the selected id, label, reason, and matched root when one applies. show adds the profile’s sources, pending sources, mappings, Packs, and state folder. create is the deliberate migration point for a flat manifest and returns the verified backup path. rename changes the label, never the id. clone copies sources and Pack assignments but not mappings or state; MCP sources in the copy stay pending until configured on this machine. 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, and it moves the profile’s state folder aside rather than deleting it. purge-state --confirm deletes that folder once no profile owns the id.

Commands that change the manifest accept --expect-revision sha256:… and refuse with exit 4 if the manifest changed since you read that revision.

Output and exit codes

Through contextcake, --json prints one JSON envelope rather than the bare result: { schemaVersion, ok, command, context, data, warnings, nextActions }, with the old result under data and a typed error when ok is false. Exit codes follow contextcake help --json: 2 for invalid input (including an unknown flag), 3 not found, and 4 when a command needs --confirm (so a delete preview exits 4). This is a deliberate pre-1.0 change for the contextcake command. node profile.mjs from a checkout keeps the bare JSON and its old exit codes.

source

Manages the selected profile’s sources. Experimental.

contextcake source list [--json]
contextcake source show <name>
contextcake source add <name> --path <folder> [--kind okf-local|files] [--level <n> | --position <n>]
contextcake source add <name> --repo <owner/name> [--ref <ref>] [--include <path>] [--token-env <NAME>]
contextcake source add <name> --kind git --repo <owner/name or URL> [--ref <ref>] [--subdir <path>]
contextcake source add <name> --command <executable> --trusted [-- <args>...]
contextcake source update <name> [--path <folder>] [--rename <new>] [--level <n>]
contextcake source level <name> <level>
contextcake source reorder <name>...
contextcake source remove <name>...
contextcake source test [<name>...]
contextcake source sync <name>
contextcake source prune [--confirm]
contextcake source pending-list
contextcake source pending-configure <name> [--path <folder>] [--command <executable> --trusted] [--token-env <NAME> [--api-base <url>]]
contextcake source pending-dismiss <name>...

list and show never open a source, and list an invalid entry as a row with its error. add checks a folder exists, a public repo answers, and an MCP command answers tools/list; it does not index. An MCP source runs its command as you, so add needs --trusted and always warns. reorder takes every source in the profile, first wins, and refuses while an invalid entry exists. remove refuses to save while other invalid entries remain; name them all. remove keeps a managed clone; prune --confirm deletes clones no source uses, and never one with changed, untracked, or ignored files, a stash, an unfinished merge, or commits no remote has. test reads each source once and exits 6 if any could not be read. pending-configure shows where a GitHub source reads from; to give it a token when that is not api.github.com, restate the address with --api-base.

settings

contextcake settings list [--json]
contextcake settings get <key>
contextcake settings set <key> <value>
contextcake settings reset <key>... | --all

A value stored in the manifest wins over its environment variable, which wins over the default. list and get report which one applied. Experimental.

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

contextcake concept and file

Reads the selected profile’s knowledge the way the app and MCP do. These commands are experimental.

contextcake concept list [--type <type>] [--json]
contextcake concept search <query> [--type <type>] [--source <name>] [--limit <n>] [--json]
contextcake concept read <id> [--json]
contextcake concept links <id> [--json]
contextcake file list [--json]
contextcake file read <layer>/<path> [--json]

search ranks like the app’s search box (at most 50 hits). read returns the resolved concept with provenance, per-section conflicts[], and fresherDissent; without --json it prints the same markdown MCP read_file returns. links matches MCP get_links. file read only reads inside a folder source’s root and exits 5 for a path that leaves it.

Each accepts --profile, --cwd, and --timeout. When a source cannot be read (a missing folder, an unreachable remote, an invalid layer) the command still answers from the rest, exits 0, and names the source in coverage.degraded. Pass --require-complete to exit 6 instead.

contextcake doctor

A fresh, bounded check of this machine. It uses the default manifest unless --manifest is supplied, and it runs even when no manifest exists:

contextcake doctor [--manifest <file>] [--profile <id>] [--cwd <path>] [--json]

Checks the manifest and any invalid layers, the selected profile, whether each folder or remote source can be reached, whether the config, data, and cache folders are writable, and every contextcake on PATH with the version its install files record (doctor never runs them). It warns when more than one install is on PATH or when the first one has a different version than the CLI you ran, since a harness runs whichever comes first. MCP sources are never started, and GitHub sources whose credential is in the app’s keychain are not contacted; both are listed as not probed and do not count against --require-complete. The Mac app’s CLI also checks device-local collector availability. A failed check exits 8, with the report in error.details and fix commands in nextActions. See diagnostics.

Related

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