Getting Started
Getting Started
Section titled “Getting Started”This guide targets the 2.0.x release line.
Requirements
Section titled “Requirements”- Rust toolchain
- Node.js for docs tooling and Pyright
- Python if you want to run the benchmark harness
Install from crates.io
Section titled “Install from crates.io”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:
cargo install sepheraInstall from GitHub Releases
Section titled “Install from GitHub Releases”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.
Use the CLI
Section titled “Use the CLI”The user-facing examples in this documentation assume sephera is installed and available on your PATH.
Run a quick LOC scan:
sephera loc --path .Use the GUI
Section titled “Use the GUI”If you would rather not use a terminal, there is a graphical front-end. It counts lines of code in a directory you pick:
cargo run -p sephera_gui --profile release-guiPick 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:
sephera loc --url https://github.com/Reim-developer/SepheraBuild a context pack:
sephera context --path . --focus crates/sephera_core --budget 32kAnalyze the codebase dependency graph:
sephera graph --path . --format markdownsephera graph --path . --focus crates/sephera_core --output deps.mdBuild a review-oriented context pack from Git changes:
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:
sephera context --path . --list-profilesAnalyze a GitHub tree URL directly:
sephera graph --url https://github.com/Reim-developer/Sephera/tree/master/crates/sephera_core --format markdownDevelop from source
Section titled “Develop from source”If you are working directly from the repository, you can run the CLI with Cargo:
cargo run -p sephera -- context --path . --focus crates/sephera_core --budget 32kCore development checks
Section titled “Core development checks”Four groups, and all four have to pass. Clippy is denied at pedantic level, so a suggestion is a failure.
# Formatting and lintscargo fmt --all --checkcargo 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
# Testscargo test --workspaceThe end-to-end cases run the real resolver over expectations written by hand from what each language means, so they need a release binary:
cargo build --releasepython e2e/run.pyThe 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:
$env:SEPHERA_CORPUS_DIR = "$env:LOCALAPPDATA\sephera\corpus"
python scripts/check_readme_examples.py # every documented command runspython scripts/measure_accuracy.py --verify # the pinned extraction figures holdpython scripts/check_doc_links.py # documentation links are claims the tree can keeppython scripts/check_publish_order.py # every crate packages in dependency ordernpx pyrightDocs development
Section titled “Docs development”Install docs dependencies:
npm --prefix docs installRun the docs site locally:
npm run docs:devBuild the static docs site:
npm run docs:buildBenchmarks
Section titled “Benchmarks”Run the default benchmark suite:
python benchmarks/run.pyFor methodology, dataset policy, and caveats, see Benchmarks.