Install

Install Ledgerful on your machine.

Build the ledgerful binary from source. The engine, ledger, dashboard, and MCP server all run locally — no hosted account required.

cargo install --git https://github.com/Ryan-AI-Studios/Ledgerful --bin ledgerful

install · cargo · source build

See the architecture View source repository

Public. The canonical repository is publicly accessible at github.com/Ryan-AI-Studios/Ledgerful. Anonymous HTTPS, GitHub API, and raw-file access are all confirmed. Source-install commands are actionable.

01 · PREREQUISITES

Get the Rust toolchain.

Source install requires rustc and cargo. Install via rustup.rs using the platform instructions for your OS. The stable toolchain is sufficient — no nightly features are required.

Once installed, confirm with rustc --version. A working Rust 1.74+ toolchain is the floor for current Ledgerful builds.

02 · INSTALL

Build and link the binary from source.

source install

Use Cargo to install directly from the Ledgerful GitHub repository. Crates.io is not used — only the git source path is supported for v0.1.x. This is the same command shown above.

cargo install --git https://github.com/Ryan-AI-Studios/Ledgerful --bin ledgerful

install · source build · ~3–6 min on first run

The first build compiles the engine and links the ledgerful binary. Subsequent installs reuse the build cache. The binary is placed in your Cargo bin directory — make sure that directory is on your PATH.

03 · VERIFY

Confirm the binary is reachable.

post-install

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

ledgerful --version
ledgerful verify --health

verify · version string and dependency health

Verify checksums for release binaries: Pre-built release binaries with SHA-256 checksums are available on the v0.1.8 GitHub Release page. Checksum verification is a required step before running any downloaded binary — see the exact checksum verification steps on the release verification page.

04 · SMOKE TEST

Run a 30-second first pass.

Four real commands, in order. On a warm build cache this takes under 30 seconds. Run scan --summary from inside a git repository root — the other three work from anywhere.

ledgerful --version
ledgerful init
ledgerful doctor
ledgerful scan --summary

smoke test · ~30s · version → init → doctor → scan summary

--version prints the installed binary version. init sets up local Ledgerful state (.ledgerful/) in the current directory. doctor runs the environment and dependency health check shown below. scan --summary prints a compact, one-line-per-file risk summary for the working tree.

Representative output for the doctor step:

Ledgerful Doctor - Environment Health Check==================================================Environment:         WindowsActive Shell:        PowershellLEDGERFUL_PLATFORM:  os=windows, arch=x86_64, family=windows, target_triple=x86_64-pc-windows-msvcTools:  git                Found (C:\Program Files\Git\cmd\git.exe)  gemini             Found (C:\Users\RyanB\AppData\Roaming\npm\gemini.cmd)Current Path:        C:\dev\ledgerfulPath Type:           NativeActive Ask Backend:  Gemini (Cloud)Embedding Model:     nomic-embed-text (768 dims) @ http://127.0.0.1:8083Completion Model:    gemma-4-E4B-it-Q6_K.gguf @ http://127.0.0.1:8081Native Graph:        Ready (CozoDB active, 7462 nodes, 31911 edges)Index Health:  • Search index: OK (1526 documents)  • Graph state: Current  • Impact report: Current (Clean tree)GPU VRAM:            0.0 GB / 11.1 GB (Driver limitation: zero-usage reporting on Intel Arc)

Representative output — captured from a real v0.1.6 runledgerful doctor

05 · FIRST COMMANDS

A fuller reference, once the smoke test passes.

Each command below exercises a different local-first surface. None of them contact a remote service by default.

# Environment health check (daemon, ledger, key state)
ledgerful doctor

# Analyze repo changes vs. main
ledgerful scan --base-ref main

# Scan with JSON output and an explicit impact report
ledgerful scan --base-ref main --impact --json

# Run a full ledger audit
ledgerful audit

# Start the loopback dashboard daemon (binds 127.0.0.1:52001)
ledgerful web start

reference · scan · audit · dashboard

SOC2-style evidence export is dashboard-only: after ledgerful web start, open the dashboard and use its Export action (served locally via the daemon’s /api/compliance/export route while the dashboard is running). There is no standalone CLI subcommand for it — see the compliance export docs for the full walkthrough.

06 · UPDATE & UNINSTALL

Update in place, or remove Ledgerful entirely.

Ledgerful is an ordinary Cargo-installed binary — updating and removing it use plain Cargo commands, not a custom updater or an uninstall script.

cargo install --git https://github.com/Ryan-AI-Studios/Ledgerful --bin ledgerful

update · re-run the same install command

Re-running the install command rebuilds from the latest source at that git ref and replaces the existing binary. There is no separate update command.

cargo uninstall ledgerful

uninstall · cargo uninstall

This removes the installed binary from your Cargo bin directory. Local state under ~/.ledgerful/ (keys, ledger, indexes) is left in place — delete that directory yourself for a full clean removal.

07 · TROUBLESHOOTING

If something doesn’t work.

Three common first-run problems and the real fix for each.

ledgerful: command not found. The Cargo bin directory isn’t on your PATH. Add $HOME/.cargo/bin (or %USERPROFILE%\.cargo\bin on Windows) to your PATH and open a new shell.

Install seems stale after pulling new commits. Cargo can reuse a cached build for the same git ref. Force a clean rebuild with --force:

function(){throw Error("Attempted to call INSTALL_COMMAND() from the server but INSTALL_COMMAND is on the client. It's not possible to invoke a client function from the server, it can only be rendered as a Component or passed to props of a Client Component.")} --force

troubleshooting · force a clean rebuild

--force is a real Cargo flag — it rebuilds and reinstalls even when Cargo believes the same version is already installed.

Windows SmartScreen prompt. Authenticode signing is not yet implemented (see Platform notes below) — SmartScreen may prompt on first run of a locally built binary. This is expected and is not a sign of a corrupted build.

08 · PLATFORM NOTES

Path and key locations by OS.

Ledgerful stores keys under ~/.ledgerful/keys/ on Unix-like systems and %USERPROFILE%\.ledgerful\keys\ on Windows. These directories are created on first use and contain your local Ed25519 signing material.

Platform	Shell	Install path	Key storage	Note
Linux	bash / zsh	`$HOME/.cargo/bin/ledgerful`	`$HOME/.ledgerful/keys/`	Add $HOME/.cargo/bin to PATH if not already.
macOS	zsh (default)	`$HOME/.cargo/bin/ledgerful`	`$HOME/.ledgerful/keys/`	Apple silicon and Intel both supported.
Windows	PowerShell / Git Bash	`%USERPROFILE%\.cargo\bin\ledgerful.exe`	`%USERPROFILE%\.ledgerful\keys\`	Authenticode signing not yet implemented; SmartScreen may prompt on first run.

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.

09 · WHERE NEXT

Continue the install → operate flow.

Docs → CLI reference, dashboard, MCP server, GitHub Action, sync, compliance, and release verification.
Architecture → The three Ledgerful surfaces and the planned control plane.
Trust & security → Local-first data flow, signing model, SOC2 export layout, telemetry, and disclosure.
Pricing → License terms and feature-state matrix.

Install first, evaluate on the box.

Ledgerful is built for engineers who want the receipts on disk, not in a hosted dashboard. Install once, verify a release, and judge the local-first claim with your own data.