Skip to content

Getting Started

This guide targets the 2.0.x release line.

  • Rust toolchain
  • Node.js for docs tooling and Pyright
  • Python if you want to run the benchmark harness

Note: cargo install sephera currently installs 0.7.1, the latest version published to crates.io (2026-10-09). For 2.0.0, use the prebuilt binaries from GitHub Releases below.

Install the published CLI:

Terminal window
cargo install sephera

If you do not want to install Rust locally, download a prebuilt archive from GitHub Releases.

Binary releases are a good fit when you want a fast local install on a supported desktop target and do not need Cargo on the machine itself. cargo install sephera remains the default path when you already use the Rust toolchain.

The user-facing examples in this documentation assume sephera is installed and available on your PATH.

Run a quick LOC scan:

Terminal window
sephera loc --path .

If you would rather not use a terminal, there is a graphical front-end. It counts lines of code in a directory you pick:

Terminal window
cargo run -p sephera_gui --profile release-gui

Pick a directory with the file picker, or type one and press Count. The GUI reads .sephera.toml and .gitignore exactly as the CLI does, so the number it shows is the number sephera loc would print. See the architecture notes for why it has its own cargo profile.

2.0.0 ships the CLI only: there is no packaged GUI in this release, so run it from source with the command above.

Run the same scan against a remote repository:

Terminal window
sephera loc --url https://github.com/Reim-developer/Sephera

Build a context pack:

Terminal window
sephera context --path . --focus crates/sephera_core --budget 32k

Analyze the codebase dependency graph:

Terminal window
sephera graph --path . --format markdown
sephera graph --path . --focus crates/sephera_core --output deps.md

Build a review-oriented context pack from Git changes:

Terminal window
sephera context --path . --diff HEAD~1 --budget 32k

--diff is a Git-only feature. Built-in modes are working-tree, staged, and unstaged. Any other value is treated as a base ref compared against HEAD through merge-base semantics.

In URL mode, context --diff keeps the base-ref behavior but intentionally rejects working-tree, staged, and unstaged because the remote checkout is a clean temp clone.

List configured profiles when the repository has a .sephera.toml file:

Terminal window
sephera context --path . --list-profiles

Analyze a GitHub tree URL directly:

Terminal window
sephera graph --url https://github.com/Reim-developer/Sephera/tree/master/crates/sephera_core --format markdown

If you are working directly from the repository, you can run the CLI with Cargo:

Terminal window
cargo run -p sephera -- context --path . --focus crates/sephera_core --budget 32k

Four groups, and all four have to pass. Clippy is denied at pedantic level, so a suggestion is a failure.

Terminal window
# Formatting and lints
cargo fmt --all --check
cargo clippy --workspace --all-targets --all-features -- -D warnings
# The fuzz targets are a separate member tree, so --workspace never reaches them.
cargo clippy --manifest-path fuzz/Cargo.toml --all-targets -- -D warnings
# Tests
cargo test --workspace

The end-to-end cases run the real resolver over expectations written by hand from what each language means, so they need a release binary:

Terminal window
cargo build --release
python e2e/run.py

The scripts check claims the documentation makes, and they need a corpus for the figures. On Windows set SEPHERA_CORPUS_DIR to $env:LOCALAPPDATA\sephera\corpus first:

Terminal window
$env:SEPHERA_CORPUS_DIR = "$env:LOCALAPPDATA\sephera\corpus"
python scripts/check_readme_examples.py # every documented command runs
python scripts/measure_accuracy.py --verify # the pinned extraction figures hold
python scripts/check_doc_links.py # documentation links are claims the tree can keep
python scripts/check_publish_order.py # every crate packages in dependency order
npx pyright

Install docs dependencies:

Terminal window
npm --prefix docs install

Run the docs site locally:

Terminal window
npm run docs:dev

Build the static docs site:

Terminal window
npm run docs:build

Run the default benchmark suite:

Terminal window
python benchmarks/run.py

For methodology, dataset policy, and caveats, see Benchmarks.