Sync & Doctor

Two commands to keep your ContextForge installation healthy. Doctor complains. Sync fixes.

doctor

Read-only health check. Reports problems without touching any files.

sync

Actively repairs and updates. Resolves everything doctor reports.

doctor — what it checks

✓config.json exists and is valid

✓lock.json exists and is valid

✓Registry is reachable

✓All packs listed in config.json are present in .contextforge

✓Expected .contextforge directory files exist

✓AGENTS.md exists (if Codex tool is selected)

✓CLAUDE.md exists (if Claude tool is selected)

✓Root files contain valid ContextForge blocks

✓git-workflow safety warnings are present

✓Detected stack packs are installed

Example output:

txt

$ npx @contextforge/cli doctor

Checking ContextForge installation...

✓ .contextforge/config.json exists
✓ .contextforge/lock.json exists
✓ Registry reachable (https://registry.contextforge.org/index.json)
✓ All 9 installed packs present in .contextforge
✓ AGENTS.md exists and contains ContextForge block
✓ CLAUDE.md exists and contains ContextForge block
✓ git-workflow safety warnings present
⚠ Stack pack "tailwind-v4" detected but not installed
⚠ Stack pack "react-performance" detected but not installed

2 issues found. Run: npx @contextforge/cli sync

sync — what it fixes

→Installs missing detected stack packs

→Updates stale packs to current registry versions

→Re-downloads changed pack files

→Repairs missing or corrupted .contextforge files

→Cleans up old directory structure from previous versions

→Regenerates root pointer files if absent or malformed

→Refreshes lock.json with resolved state

Example output:

txt

$ npx @contextforge/cli sync

✓ Re-detecting stack...
  Detected: nextjs, react, typescript, tailwind
✓ Fetching registry...
✓ Installing missing pack: tailwind-v4
✓ Installing missing pack: react-performance
✓ Updating stale pack: nextjs-best-practices (0.1.0 → 0.1.1)
✓ Regenerating .contextforge/lock.json
✓ All files up to date

Done. 3 packs updated.

The recommended workflow after pulling new changes from a repo that uses ContextForge: run npx @contextforge/cli sync to ensure your local installation matches config.json.

When to run each

After cloning a reposyncInstalls all packs from config.json

Something feels brokendoctor → syncDoctor diagnoses, sync repairs

Upgrading ContextForge CLIsyncMigrates old structure if needed

Registry published new pack versionssyncPulls latest pack files

Before committingdoctorConfirms installation is consistent

Next: FAQ