slice-cli

slice-cli

Query your codebase by slice: what owns this file, what's the blast radius before you edit, where a concept lives, what the runtime flows are — and which docs went stale.

slice turns a folder of "slice" documents (slices/*.md) into a fast query surface for humans and AI agents. A slice is a named region of a codebase — its files, dependencies, call-stack flows, and durable system notes. Ask it what owns a file, what transitively depends on a slice before you change it, where an abstraction lives, and how requests flow at runtime. And because DOCS.yaml maps docs to slices with a content fingerprint of the code each was last verified against, it also tells you which design docs have gone stale — exactly, surviving commits and rebases.

Install

slice is a single self-contained binary (Rust). Two ways to get it:

Prebuilt binary — download the archive for your platform from the latest release, unpack it, and put slice on your PATH.

Build from source (needs a Rust toolchain):

git clone https://github.com/scodge-24/slice-cli && cd slice-cli
cargo install --path rust/slice-rs        # installs the `slice` binary

Two opt-in build features extend the surface (both off by default; the default build has zero network dependencies):

cargo install --path rust/slice-rs --features semantic   # locate / find --semantic / semantic-index
cargo install --path rust/slice-rs --features ast        # Tree-sitter spans for outline/symbols

semantic commands need an OPENROUTER_API_KEY at runtime (embeddings); ast swaps the heuristic symbol spanner for full Tree-sitter spans (set SLICE_SYMBOLS=heuristic to force the old path).

Requires git on PATH at runtime. slice browse additionally needs optional fzf (>= 0.30); every other command works without it.

From a checkout you can also run it without installing:

cargo run --manifest-path rust/slice-rs/Cargo.toml -- --repo examples/mock-repo list --json

slice-cli began as a Python tool and was ported to Rust. The Python implementation is preserved at tag python-impl-final and branch package-refactor.

60-second tour

This repo ships a self-contained demo under examples/mock-repo/. Point slice at it with --repo.

Orient on a file before you touch it — one command tells you the owning slice, its dependencies, and how requests flow through it:

$ slice --repo examples/mock-repo context src/auth/middleware.py
slice: auth-service
description: Authentication and session management
doc: slices/auth-service.md
files: src/auth/middleware.py, src/auth/sessions.py
dependencies:
Invariants:
- A token is valid only if unexpired AND its session still exists.
- Sessions live in memory; a process restart drops all sessions.
Runtime Flows:
request -> require_auth -> verify_token -> get_session -> handler
...

Check the blast radius before you change a slice — every slice that (transitively) depends on it:

$ slice --repo examples/mock-repo deps auth-service --reverse --transitive
api-handlers

Then there's doc staleness. Change a file and slice tells you exactly which doc to review, and you stamp it back in sync once it's updated:

$ slice --repo examples/mock-repo affected-docs src/auth/middleware.py
[STALE] auth-guide  (auth-guide.md)  [auth-service]
  - examples/mock-repo/src/auth/middleware.py
  - examples/mock-repo/src/auth/sessions.py
$ slice --repo examples/mock-repo stamp auth-guide
stamped auth-guide -> 5fb503f...

examples/ is sample data — a mock repo for the tool to operate on, not documentation about slice itself.

Core commands