@codeledger/cli — ContextECF CodeLedger

Deterministic, bounded context selection for AI coding agents. Published by Intelligent Context AI, Inc..

• Website: https://codeledger.dev
• Live demo: https://demo.codeledger.dev
• Source: https://github.com/codeledgerECF/codeledger
• npm: @codeledger/cli

Installing ContextECF CodeLedger? Make sure you use the scope: npm install -g @codeledger/cli. There is an unrelated unscoped codeledger package on npm by a different author. The real ContextECF CodeLedger package is published under the @codeledger scope.

Install

npm install -g @codeledger/cli@latest
cd your-repo
codeledger ready

This package is a thin npm wrapper. When you install it, the postinstall step downloads the platform-specific hardened binary from the matching GitHub Release, verifies its SHA256 against SHA256SUMS-v<version>.txt, and caches it under ~/.cache/codeledger/bin/.

No engine code, scoring logic, or formulas ship to npm. The wrapper is ~30 KB of plain JavaScript that fetches, verifies, and launches the real CodeLedger binary.

Supported platforms (tier 1)

• darwin-arm64 (Apple Silicon macOS)
• linux-x64

Intel Mac (darwin-x64): deferred in v0.10.6 — no working Intel Mac runner was available on the release CI plan at the time of the release. Intel Mac users can build from source or wait for the runner situation to stabilize in a later release.

Other platforms fall through postinstall softly — npm install succeeds, but running codeledger will either use a repo-local vendored runtime if the current repo has .codeledger/bin/, or print a clear recovery message pointing at the manual download page.

Usage

After installing, start inside a repo with codeledger ready. It initializes CodeLedger if needed, scans the repo, vendors the browser/cloud runtime, and prints the ambient task-context status.

codeledger ready
codeledger ready --task "your task here"
codeledger scan
codeledger help

If you installed an earlier CodeLedger version and codeledger vendor cannot find the standalone runtime, upgrade first and rerun the command:

npm install -g @codeledger/cli@latest
codeledger ready
codeledger vendor

All arguments, environment variables, stdin, and exit codes pass straight through to the hardened binary.

If the global hardened binary is missing but the repo already has a vendored runtime, the npm shim automatically falls back to:

./.codeledger/bin/codeledger <command>

This keeps existing repos usable after a skipped postinstall, air-gapped install, or unsupported global platform.

Version parity

When you run a globally installed codeledger inside a repo that has a repo-local CodeLedger (.codeledger/bin/), the CLI detects whether the running version differs from the repo-local version. If it does:

1. A warning is printed to stderr showing both versions.
2. The CLI automatically re-executes the command via the repo-local binary so that command behavior matches what the repo expects.

This prevents a stale global install from silently producing different results than the repo-local CLI. To avoid the delegation overhead, invoke the repo-local wrapper directly:

./.codeledger/bin/codeledger <command>

Environment variables

| Variable | Purpose | |---|---| | CODELEDGER_SKIP_POSTINSTALL=1 | Skip the binary download during npm install. Useful for air-gapped environments. You are responsible for placing the binary at the expected cache path afterwards. | | CODELEDGER_BINARY_URL=<url> | Override the download base URL. Use this to fetch the binary from a corporate mirror or internal CDN. The URL must serve the same filenames as the GitHub Release, plus a SHA256SUMS-v<version>.txt sibling. | | CODELEDGER_CACHE_DIR=<path> | Override the cache directory (default ~/.cache/codeledger/bin). |

Air-gapped / offline install

CODELEDGER_SKIP_POSTINSTALL=1 npm install -g @codeledger/cli@latest

# then place the hardened binary at:
#   ~/.cache/codeledger/bin/codeledger-hardened-v<version>
# and chmod +x it.

# If this repo is already initialized, use the committed vendored runtime:
./.codeledger/bin/codeledger ready

Download the binary + SHA256SUMS from the GitHub Release matching the installed version:

https://github.com/codeledgerECF/codeledger/releases

Recovery

If postinstall was skipped (e.g. npm install --ignore-scripts), recover with any of:

npm install -g @codeledger/cli@latest
# or retry the current install
npm rebuild @codeledger/cli
# or
node $(npm root -g)/@codeledger/cli/scripts/postinstall.js
# or download the binary manually from the release page and chmod +x it

License

See LICENSE. The CodeLedger binary itself is governed by the CodeLedger Core Engine License.

Source

Source code lives at https://github.com/codeledgerECF/codeledger. The hardened binary shipped with this wrapper is published through the same public GitHub Releases channel used by the installer.