CLI Reference

Command reference

Every command with flags and examples. For the full list, run codeledger help.

Core

codeledger init

Initialize CodeLedger in a repo. Creates .codeledger/, config, and memory ledgers. Run once per repo.

--force

Overwrite existing config

npx codeledger init

codeledger scan

Rebuild the repo index: dependency graph, churn history, test map, phrase index, and co-commit graph.

--full-policy

Include all policy zones in output

npx codeledger scan

codeledger activate

Score every file for the given task and write .codeledger/active-bundle.md.

--task "..."	Task description (required)
--budget-tokens N	Override token budget (default 8000)
--budget-files N	Override max file count (default 25)
--session ID	Write to a session-scoped bundle path

npx codeledger activate --task "add rate limiting to the API gateway"

codeledger bundle

Generate a context bundle as JSON without writing active-bundle.md. Useful for scripting.

--task "..."	Task description
--json	Output raw JSON bundle

npx codeledger bundle --task "migrate auth to Clerk" --json

codeledger refine

Refine the active bundle with new learnings discovered mid-session.

--learned "..."

New context to incorporate

npx codeledger refine --learned "auth helper lives in packages/shared/auth"

Session

codeledger session-progress

Write a ground-truth snapshot of session commits, changed files, and remaining bundle files.

npx codeledger session-progress

codeledger session-summary

Print a session-end value recap: bundle recall, precision, token savings, and dollar estimate.

--final	Mark as the session-ending summary
--json	Machine-readable output

npx codeledger session-summary

codeledger progress-check

Show how much of the active bundle has been read and edited. Use after completing a stage.

npx codeledger progress-check

Verification

codeledger verify

Run architectural verification: Review Intelligence, drift detection, discovery violations, and contract checks.

--explain	Richer reasoning for each finding
--json	Machine-readable findings
--update-baseline	Accept current findings into baseline
--show-triaged	Show suppressed and baselined findings
--invariant <name>	Filter to one invariant module

npx codeledger verify --explain

codeledger truth

Run a Truth Audit — produces a signed implementation certificate, CIC score, and topology report.

--export pdf	Export signed PDF certificate
--json	Machine-readable audit output

npx codeledger truth --export pdf

codeledger pre-pr

Pre-PR verification gate: runs verify, audit, and evidence checks before you open a pull request.

npx codeledger pre-pr

CI / PR

codeledger ci pr-check

Emit PR risk, drift, and evidence-gap signals from the current diff. Advisory by default.

--base <ref>	Base ref for diff (default: origin/main)
--head <ref>	Head ref for diff (default: HEAD)
--json	JSON output with full signal breakdown
--comment-file <path>	Write PR comment markdown to file
--mode block	Fail exit code on High risk or evidence gaps
--use-test-map	Use per-file test linkage instead of file heuristic

npx codeledger ci pr-check --json

codeledger setup-ci

Generate GitHub Actions workflow files for PR review and audit CI.

npx codeledger setup-ci

Architecture

codeledger health

Architecture Health Score (AHS) across five dimensions: DRI, EDS, STS, OFS, DCS.

--json

Machine-readable health data

npx codeledger health

codeledger discover

Pre-build intelligence: detect existing implementations before you write new code.

--task "..."	Describe the capability you plan to build
--json	JSON verdict and overlap map

npx codeledger discover --task "add webhook delivery"

codeledger intervene

Detect architecture issues and produce prioritised intervention recommendations.

npx codeledger intervene

Reporting

codeledger explain

Explain the latest run using evidence, scoring signals, and prior outcome patterns.

--json	Machine-readable explanation
--surface <cli\|ide\|markdown\|ci>	Rendering target

npx codeledger explain

codeledger learnings

Show recurring patterns, hotspots, and trend learnings from recent runs.

--limit N	Number of patterns to show
--json	Machine-readable patterns

npx codeledger learnings --limit 5

codeledger next

Recommend next best actions based on current signals and historical outcomes.

npx codeledger next

Missing a command? Run npx codeledger help for the full list, or ask in Discussions.