The create-baseline
command line.
Reference for the create-baseline CLI. The command, flag and exit-code tables on this page are generated from src/cli/surface.js, and a test pins that module to the argv parser in bin/cli.js, so the page cannot drift from the binary without failing CI.
Commands
Three commands, one of which is the default. If the first positional is not a subcommand the CLI installs; when it is upgrade or doctor, that command runs instead. Install will refuse to touch a target that already holds an install, checking five sentinel paths and exiting 1 if it finds any of them. Upgrade needs the manifest that install wrote, and exits 2 without one. Doctor writes nothing at all.
$ create-baseline <target> [options]
Materialize the baseline into <target>. Refuses when any sentinel path is already present unless --force is passed. Creates the target directory when it does not exist.
Copies the template, deep-merges .mcp.json, appends any missing baseline patterns to .gitignore, writes the install manifest, and mirrors the shipped tree to .claude/.baseline-prior/ for later upgrades to diff against.
$ create-baseline upgrade [target]
Reconcile an installed target against a newer template with a three-tier merge. Requires .claude/.baseline-manifest.json; exits 2 without one.
Prunes baseline files removed upstream that you had not touched. When the target manifest already records this CLI version and nothing is staged, it prints "already on baseline X.Y.Z; nothing to do" and exits 0 without writing.
$ create-baseline doctor [target]
Report drift between an installed target and its install snapshot, counting matched, customized, missing and added files. Read-only.
Exit 0 when nothing is missing, 1 when any baseline file is missing, 2 when there is no manifest to compare against.
Flags
10 flags, grouped by what they change. Every flag is a boolean and none of them takes a value. Because most apply to a single command, each row names the commands it can be used with.
install behaviour
Overwrite an existing install instead of refusing. Prompts for the literal word "overwrite" and requires an interactive terminal; without a TTY it exits 2 rather than proceeding unattended.
Preserves .claude/workflows.jsonl, the workflow-track schema, and the two runtime memory files regardless.
applies to install
Print the intended actions and write nothing.
applies to install, upgrade
security posture
Materialize a hardened target/.npmrc carrying ignore-scripts=true and min-release-age=7. Off by default.
An existing target/.npmrc is preserved verbatim. Operators who already set these in ~/.npmrc do not need the flag.
applies to install
Skip the CI and secrets posture: the gitleaks pre-commit gate, the scripts/ci helpers, and the branch-protection config template. On by default.
Also sets ci_posture.enabled false in the delivered project.json, so the opt-out survives upgrades instead of being re-delivered.
applies to install
PlantUML jar
Skip both the jar download and the Java preflight.
Conflicts with --require-plantuml; passing both exits 2.
applies to install
Treat a failed jar fetch, a sha256 mismatch, or a missing Java as fatal and exit 4. Without it these warn and the install continues.
Conflicts with --no-plantuml; passing both exits 2.
applies to install
doctor output
Promote customized files to exit 1 and prefix each with TAMPERED: plus its shipped and observed sha256.
Intended for detecting post-install tampering of the baseline tree.
applies to doctor
Emit the structured report on stdout instead of the text renderer. Honours --strict and uses the same exit codes.
applies to doctor
misc
Print usage and exit 0.
applies to install, upgrade, doctor
Print the CLI version and exit 0.
applies to install, upgrade, doctor
Exit codes
Success, or a doctor run that found nothing missing.
User abort, a conflict without --force, a doctor run reporting missing files, or an aborted upgrade.
Bad command line, input needed but no terminal attached, doctor found no manifest, or the removed --merge flag was passed.
Upgrade kept your customized files, or preserved files that were removed upstream.
Under --require-plantuml, the jar fetch or Java preflight failed; or a mechanical merge produced conflicts to resolve.
A semantic merge was staged for the /upgrade-project skill to reconcile inside Claude Code.
Upgrade tiers
The shipped manifest declares which of three tiers each file belongs to before any merge begins.
If a file is tier 1 and you have changed it, the run stops and offers four choices: keep your version, take the new baseline, merge, or abort. Should you keep your version, the run exits 3 when anything was skipped. Choose merge and the incoming bytes are parked under .claude/state/upgrade/<timestamp>/ and the run exits 5, leaving /upgrade-project to reconcile them inside Claude Code.
Tier 2 files are merged for you, through git merge-file --diff3. BASE comes from the .claude/.baseline-prior/ copy that install wrote, or from npm should that copy have gone missing. A clean merge lands quietly; a conflicted one is written out with markers and exits 4.
Where judgement is needed the shell merges nothing at all. A tier 3 file is parked alongside whatever tier 1 chose to merge, and the run exits 5.
Separately from all three tiers, the upgrade will delete baseline files that were dropped upstream, provided you have not edited them.
If the target's manifest already records this CLI's baseline_version and nothing is parked, the run prints already on baseline X.Y.Z; nothing to do and exits 0 without writing. That is the one case which skips the merge entirely.
Doctor categories
Each category is a statement about one file's hash. matched means the hash is unchanged, customized means it differs, missing means a baseline file has gone, and added means a file is present now that the install snapshot did not have, which is usually /init-project's doing. Only missing changes the exit code by default; the flag table above says what --strict changes.
A brand-new install reports customized: 1 for .claude/project.json, which is a known wrinkle rather than real drift. The CLI writes baseline_version into that file after it has taken the manifest snapshot, so the hash can never match. A strict run will therefore exit 1 on a clean install.
Merge semantics
Install and upgrade merge exactly two files. Every other path is either copied or preserved.
To keep a change to a server the template names, put it under a name the template does not use. .mcp.json gets a deep merge: servers the template names belong to the baseline and refresh from it, while servers it does not name are yours and stay byte for byte. Change one of the baseline's own servers and the next upgrade will overwrite it.
You never lose a line from .gitignore, because the merge only ever appends. It runs offline and is deterministic, so your file survives byte for byte and only the baseline patterns you lack are added, under a comment header.
Four paths are never written, on install or on upgrade: .claude/workflows.jsonl, the workflow-track schema, and the two runtime memory files. Those memory files are rewritten on every conversation turn, so prompting you about them would be a false alarm every single time.