@codeledger/cli

@codeledger/cli — CodeLedger by ContextECF

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

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

Installing? 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 CodeLedger by ContextECF is published under the @codeledger scope.

Install

npm install -g @codeledger/cli

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 print a clear error pointing at the manual download page.

Usage

Identical to earlier versions of the CLI — the wrapper is a transparent launcher:

codeledger --version
codeledger init
codeledger activate --task "your task here"
codeledger scan
codeledger help

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

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:

• A warning is printed to stderr showing both versions.
• 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

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

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 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-blackbox. The hardened binary shipped with this wrapper is built deterministically by the release pipeline in that repo.