toolpath-cli

One binary that ties together everything Toolpath can do: derive provenance from git and Claude, query and filter documents, render DAG visualizations, track live editing sessions, and merge results into release graphs. If you want to use Toolpath without writing Rust, start here.

Unified CLI for deriving, querying, and visualizing Toolpath provenance documents.

Installation

cargo install toolpath-cli

This installs a binary called path.

Or run from source:

cargo run -p toolpath-cli -- <command>

Typical workflows

Capture the provenance of a PR:

path derive git --repo . --branch feature --pretty > pr-provenance.json

Visualize how a branch evolved, including dead ends:

path derive git --repo . --branch main:HEAD~20 | path render dot | dot -Tpng -o history.png

Review what an AI agent changed:

path derive claude --project . --pretty | path query filter --actor "agent:" --pretty

Record provenance for a live editing session:

cat src/main.rs | path track init --file src/main.rs --actor "human:alex"
# ... edit the file ...
cat src/main.rs | path track step --session /tmp/session.json --seq 1 --parent-seq 0
path track annotate --session /tmp/session.json --intent "Refactored auth"
path track close --session /tmp/session.json --pretty > session-provenance.json

Merge multiple sources into a release graph:

path merge git-provenance.json claude-provenance.json --title "v2.0 Release" --pretty

Commands

list

Discover available sources before deriving.

# List git branches with metadata
path list git --repo .

# List Claude projects
path list claude

# List sessions within a project
path list claude --project /path/to/project

# Machine-readable output
path list git --repo . --json

derive

Generate Toolpath documents from source systems.

# From git history (single branch -> Path, multiple -> Graph)
path derive git --repo . --branch main --pretty
path derive git --repo . --branch main --branch feature --title "Release v2"
path derive git --repo . --branch main:HEAD~20 --pretty

# From Claude conversation logs
path derive claude --project /path/to/project --pretty
path derive claude --project /path/to/project --session abc123
path derive claude --project /path/to/project --all

query

Query Toolpath documents.

# Walk ancestry from a step
path query ancestors --input doc.json --step-id step-003

# Find abandoned branches
path query dead-ends --input doc.json

# Filter by criteria (combinable)
path query filter --input doc.json --actor "agent:"
path query filter --input doc.json --artifact "src/main.rs"
path query filter --input doc.json --after "2026-01-29T00:00:00Z" --before "2026-01-30T00:00:00Z"

render

Render documents to other formats.

# Graphviz DOT output
path render dot --input doc.json --output graph.dot
path render dot --input doc.json --show-files --show-timestamps

# Pipe through Graphviz
path derive git --repo . --branch main | path render dot | dot -Tpng -o graph.png

merge

Combine multiple documents into a single Graph.

path merge doc1.json doc2.json --title "Release v2" --pretty
path merge *.json --pretty

track

Incrementally build a Path document step by step, useful for editor integrations and live sessions.

# Start a session (pipe initial content via stdin)
echo "hello" | path track init --file src/main.rs --actor "human:alex" --title "Editing session"

# Record a step (pipe current content via stdin)
echo "world" | path track step --session /tmp/session.json --seq 1 --parent-seq 0

# Record a step with VCS source metadata
echo "world" | path track step --session /tmp/session.json --seq 2 --parent-seq 1 \
  --source '{"type":"git","revision":"abc123"}'

# Add a note to the current step
path track note --session /tmp/session.json --intent "Refactored for clarity"

# Annotate any step with metadata (intent, source, refs)
path track annotate --session /tmp/session.json --step step-001 \
  --intent "Extract helper" \
  --source '{"type":"git","revision":"abc123"}' \
  --ref '{"rel":"issue","href":"https://github.com/org/repo/issues/42"}'

# Export the session as a Toolpath Path document
path track export --session /tmp/session.json --pretty

# Export and clean up
path track close --session /tmp/session.json --pretty

# List active sessions
path track list

validate

Check that a JSON file is a valid Toolpath document.

path validate --input examples/step-01-minimal.json
# Valid: Step (id: step-001)

haiku

path haiku

Global flags

Part of Toolpath

This is the CLI for the Toolpath workspace. See also:

• toolpath -- core types and query API
• toolpath-git -- derive from git history
• toolpath-claude -- derive from Claude conversations
• toolpath-dot -- Graphviz DOT rendering
• RFC -- full format specification