CLI Reference

Command reference

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

Examples below use npx @codeledger/cli for a no-install quick reference. In a browser or cloud AI coding session, use the vendored ./.codeledger/bin/codeledger instead — npx needs npm registry access those sandboxes may not have.

Core

codeledger init

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

--force

Overwrite existing config

npx @codeledger/cli 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/cli 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/cli 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/cli 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/cli 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/cli 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/cli session-summary

codeledger progress-check

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

npx @codeledger/cli 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/cli 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/cli truth --export pdf

codeledger pre-pr

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

npx @codeledger/cli 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/cli ci pr-check --json

codeledger setup-ci

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

npx @codeledger/cli setup-ci

Architecture

codeledger health

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

--json

Machine-readable health data

npx @codeledger/cli 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/cli discover --task "add webhook delivery"

codeledger intervene

Detect architecture issues and produce prioritised intervention recommendations.

npx @codeledger/cli 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/cli 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/cli learnings --limit 5

codeledger next

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

npx @codeledger/cli next

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