Install

Install

Install Ledgerful locally

v0.2.12 · macOS, Linux, Windows · package managers and prebuilt binaries · no hosted account required.

cargo install --git https://github.com/Ryan-AI-Studios/Ledgerful --bin ledgerful
install · cargo · source build
AvailableRuns locallySource install needs Rust 1.85+ via rustup.rs. Homebrew and cargo binstall install prebuilt release binaries.

Expected result: a ledgerful binary on your PATH, ready to scan repos and start the local dashboard.

See the architectureView source repository

Package managers and prebuilt installs

Live channels install a real release binary (or a source build). Only verified public packages show install commands — no fabricated paths.

Homebrew

macOS · Linux

Available

Official tap formula. Installs the prebuilt release binary for Apple Silicon, Intel macOS, or Linuxbrew.

Prerequisite: Homebrew (brew.sh)

brew install Ryan-AI-Studios/tap/ledgerful
Homebrew · install

macOS release binaries are not yet codesigned or notarized. Homebrew formula installs usually avoid browser quarantine; if Gatekeeper reports “developer cannot be verified”, run the quarantine bypass below.

cargo binstall

any · Rust users

Available

Uses Cargo.toml [package.metadata.binstall] to resolve the matching GitHub release archive. Prefer this over a full workspace cargo install when a prebuilt asset exists. No crates.io publish required.

Prerequisite: cargo-binstall (cargo install cargo-binstall)

cargo binstall --git https://github.com/Ryan-AI-Studios/Ledgerful
cargo binstall · install

Requires cargo-binstall on the machine. Resolves the latest git version with matching release assets; if no matching prebuilt asset exists, binstall may fall back to compiling from source.

Scoop

Windows

Available

Official Scoop bucket for the portable Windows x86_64 zip (ledgerful.exe at archive root — no 7-Zip prerequisite).

Prerequisite: Scoop (scoop.sh)

scoop bucket add ledgerful https://github.com/Ryan-AI-Studios/scoop-bucket
scoop install ledgerful
Scoop · install

Manifest version/hash are bumped from published release .sha256 sidecars by engine release automation.

winget

Windows

Available

Community package Ledgerful.Ledgerful on microsoft/winget-pkgs (portable Windows zip).

Prerequisite: App Installer / winget (Windows 10+)

winget install Ledgerful.Ledgerful
winget · install

First package accepted 2026-07-30. Community index is live at 0.2.12 (microsoft/winget-pkgs#430322 merged 2026-09-06). History: older leftover 0.2.8 (#415913) merged; older leftover 0.2.9 (#416853) closed-superseded. Homebrew/Scoop (org-owned) and GitHub Releases track the engine cut more tightly. Authenticode is not yet implemented; SmartScreen may prompt on first run.

Cargo (source)

any · full toolchain

Available

Canonical source build from the public GitHub repository. Crates.io is not used for distribution.

Prerequisite: Rust 1.85+ (rustup.rs)

cargo install --git https://github.com/Ryan-AI-Studios/Ledgerful --bin ledgerful
Cargo (source) · install

Requires Rust 1.85+ via rustup. First build takes several minutes; subsequent installs reuse the cargo cache.

One-line release installers

Download the matching prebuilt archive when one exists for your platform, or fall back to a source build. These scripts do not re-check the published .sha256 sidecars — use the release verification docs when you need checksum verification.

One-line (macOS / Linux)

Unix

Available

Downloads the matching prebuilt release archive when one exists for your platform, then installs it under ~/.local/bin. Falls back to cargo install when no asset matches. Does not re-verify published .sha256 sidecars (use release verification docs for that).

curl -fsSL https://raw.githubusercontent.com/Ryan-AI-Studios/Ledgerful/main/install/install.sh | sh
One-line (macOS / Linux) · install

One-line (Windows)

PowerShell

Available

Downloads the portable Windows zip when available and installs under %USERPROFILE%\.ledgerful\bin. Falls back to cargo install when needed. Does not re-verify published .sha256 sidecars (use release verification docs for that).

iwr https://raw.githubusercontent.com/Ryan-AI-Studios/Ledgerful/main/install/install.ps1 -UseBasicParsing | iex
One-line (Windows) · install
macOS Gatekeeper (interim): release macOS binaries are not yet Apple-codesigned or notarized. If a downloaded binary reports “developer cannot be verified”:
xattr -d com.apple.quarantine "$(which ledgerful)"
macOS · quarantine bypass (interim)
The durable fix is codesign + notarize in the engine release pipeline.

Choose your platform

Pick a tab for the recommended prebuilt path, binary location, and first scan. Source install still works on every OS when you need a custom build.

Recommended installer

Homebrew (Linuxbrew) or cargo binstall

brew install Ryan-AI-Studios/tap/ledgerful
Linux · recommended

Alternative: cargo binstall --git https://github.com/Ryan-AI-Studios/Ledgerful

Binary path
$HOME/.cargo/bin/ledgerful (cargo) or brew prefix
Verify command
ledgerful --version
First scan command
ledgerful scan --summary

Prefer brew or cargo binstall for a prebuilt binary; use the source cargo install when you need a custom feature build.

Recommended installer

Homebrew

brew install Ryan-AI-Studios/tap/ledgerful
macOS · recommended

Alternative: cargo binstall --git https://github.com/Ryan-AI-Studios/Ledgerful

Binary path
brew prefix or $HOME/.cargo/bin/ledgerful
Verify command
ledgerful --version
First scan command
ledgerful scan --summary

Apple Silicon and Intel are both supported. If Gatekeeper blocks a downloaded binary, use the quarantine bypass in the Homebrew card notes.

Recommended installer

Scoop (portable zip)

scoop bucket add ledgerful https://github.com/Ryan-AI-Studios/scoop-bucket
scoop install ledgerful
Windows · recommended

Alternative: cargo binstall --git https://github.com/Ryan-AI-Studios/Ledgerful

Binary path
Scoop shims or %USERPROFILE%\.cargo\bin\ledgerful.exe
Verify command
ledgerful --version
First scan command
ledgerful scan --summary

Authenticode signing is not yet implemented; SmartScreen may prompt on first run. Prefer Scoop or winget install Ledgerful.Ledgerful for a prebuilt Windows binary; community index is live at 0.2.12 (#430322 merged 2026-09-06).

Install in five steps

From a package manager or source build to your first repo review.

01 · INSTALL CLI

Pick a live channel and install the binary.

Prefer a package manager or prebuilt path when you want a release binary without a full workspace compile. Use the source cargo install when you need a custom feature build. Crates.io is not used for distribution.

brew install Ryan-AI-Studios/tap/ledgerful
install · Homebrew (prebuilt) · recommended on macOS/Linux
scoop bucket add ledgerful https://github.com/Ryan-AI-Studios/scoop-bucket
scoop install ledgerful
install · Scoop (prebuilt) · Windows
cargo binstall --git https://github.com/Ryan-AI-Studios/Ledgerful
install · cargo binstall · any platform with cargo-binstall
cargo install --git https://github.com/Ryan-AI-Studios/Ledgerful --bin ledgerful
install · cargo · source build · ~3–6 min on first run
Expected result

The installer places a ledgerful binary on your PATH(Homebrew prefix, cargo bin dir, or the one-line installer's install location). Open a new shell if the command is not found immediately.

02 · VERIFY BINARY

Confirm the binary is reachable and healthy.

Print the version string and run a dependency health check. Both commands exit non-zero on a broken install.

ledgerful --version
ledgerful verify --health
verify · version string and dependency health
Expected output — captured from a real v0.2.12 run

ledgerful --version

ledgerful 0.2.12 (dd0efdcecbeb)

ledgerful verify --health

Verification Health Check
Checking verification dependencies...
  Checking git...
  [OK] git is available.
  Checking ledger state...
  [NOTE] No impact report found. Run 'ledgerful scan --impact' after making changes.
  [OK] Runner: cargo test (nextest not available)

All verification dependencies are available.

A fuller environment report is available via ledgerful doctor:

✓ Doctor: ready for publish env · 5 warning(s) · 1 optionalLedgerful Doctor - Environment Health Check==================================================Environment:         LinuxActive Shell:        UnknownLEDGERFUL_PLATFORM:  os=linux, arch=x86_64, family=unix, target_triple=x86_64-unknown-linux-gnuTools:  git                Found (/usr/bin/git)  gemini CLI         NOT FOUND (optional CLI; not the Cloud Ask backend)Current Path:        /tmp/neutral-repoPath Type:           NativeWork root:           /tmp/neutral-repoState dir:           /tmp/neutral-repo/.ledgerfulActive Ask Backend:  Local (127.0.0.1)Native Graph:        Ready (CozoDB active, 1 nodes, 1 edges)Index Health:  • Gate mode: observe (matches ledger history)  • Search index: Empty (0 documents — run 'ledgerful index')  • [warn] [graph-empty] Graph state: Empty (never indexed)  • [warn] [impact-missing] Impact report: None (run 'ledgerful scan --impact')  • [warn] [search-empty] Search index: present but empty (0 documents); full-text search unusable until populated    ledgerful index    # first search also rebuilds when empty:    # ledgerful search "<query>"    ledgerful doctor --json── Optional Accelerators ──────────────────────Embedding Model:     unreachable (Local embedding model server at http://127.0.0.1:8083 is unreachable after 1 retries)Completion Model:    Not configured11 hygiene finding(s) collapsed (1 optional warning) — run doctor --full2 signing finding(s) deferred (observe) — run doctor --fullGPU VRAM:            n/a (Windows-only monitoring)
Representative output — captured from a real v0.2.12 runledgerful doctor
03 · SCAN A REPO

Run a one-line summary on a git repository.

Run from inside a git repository root. The scan reads the working tree and produces a compact per-file risk summary. No source is uploaded by default.

ledgerful scan --summary
scan · first pass
Expected result

A one-line-per-file summary showing change category, risk state, and impacted paths for the working tree. For a deeper report, add --impact or --json.

04 · LAUNCH DASHBOARD

Start the local loopback dashboard.

The dashboard is served by the CLI on 127.0.0.1:52001 with an ephemeral local token. Nothing is hosted externally.

ledgerful web start
dashboard · local loopback
Expected result

A browser opens to the local dashboard (or visit http://127.0.0.1:52001). The dashboard shows Project Health and Recent Changes for the scanned repo.

05 · REVIEW RESULT

Read the dashboard or export evidence.

Review per-file risk state, recent changes, and impact reports. For compliance workflows, export a signed SOC 2-style evidence ZIP from the dashboard or run ledgerful export evidence --profile soc2. See the compliance export docs for the full walkthrough.

Run your first scan: ledgerful scan

Once the binary is installed, pick a repo and run a summary scan. The local dashboard and evidence export are one command away.

Golden path proof CLI docsDashboard guide
OS code signing status: Windows Authenticode and macOS Developer ID / Gatekeeper notarization are not yet implemented. Source-built or downloaded binaries may trigger OS security prompts on first launch. OS code signing is a planned enhancement for a future release.