toolpath-cli

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