toolpath-cli 0.1.1

CLI for deriving, querying, and visualizing Toolpath provenance
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137

# toolpath-cli

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

## Installation

```bash
cargo install toolpath-cli
```

This installs a binary called `path`.

Or run from source:

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

## Commands

### list

Discover available sources before deriving.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
# 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.

```bash
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.

```bash
# 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 --intent "Changed greeting"

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

# 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.

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

### haiku

```bash
path haiku
```

## Global flags

| Flag | Description |
|---|---|
| `--pretty` | Pretty-print JSON output |