stash-cli 0.8.0

A local store for pipeline output and ad hoc file snapshots
Documentation 
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

# Using `stash` in Agent Workflows

`stash` works well as a scratchpad for agent-style command-line work.

Instead of writing intermediate results to ad hoc files under `/tmp`, an agent
can store command output in `stash`, tag it, and come back to it later by stack
ref or attribute.

This is useful when:
- a command is expensive and you want to inspect the output more than once
- you want to compare the current result with an earlier run
- you want to label outputs with context such as `step`, `kind`, or `branch`

`stash` is not a replacement for real files when another tool requires a file
path. In those cases, use a normal file. But for reusable command output,
`stash` is often a better fit.

## Store command output for later inspection

```bash
cargo test -- --nocapture | stash -a kind=test-output -a step=pre-refactor
stash cat | less
stash attr @1
```

This gives you a reusable snapshot of the full test output without inventing a
temporary file name.

## Compare two `cargo test` runs

```bash
cargo test -- --nocapture | stash -a kind=test-output -a phase=before
# ... make changes ...
cargo test -- --nocapture | stash -a kind=test-output -a phase=after

diff -u <(stash cat @2) <(stash cat @1)
```

If you want to find the right snapshots first:

```bash
stash attrs --count
stash ls -a phase -a +phase
stash ls -A
```

## Keep benchmark runs by default

`cargo bench` is a particularly good fit for `stash`.

Benchmark output is often useful later, even when nobody planned ahead for a
comparison. If an agent stores each benchmark run with a few stable
attributes, it becomes easy to go back and compare current results with older
ones.

A good default is:

```bash
cargo bench | stash -a kind=cargo-bench -a commit="$(git rev-parse HEAD)"
```

That gives each run:
- `kind=cargo-bench`
- `commit=<git sha>`
- the built-in stash timestamp

Those three pieces are often enough to recover the right baseline later.

Useful follow-up commands:

```bash
stash attrs --count
stash ls -a ++kind -a ++commit
stash ls -A
diff -u <(stash cat @2) <(stash cat @1)
```

You can still add narrower labels when they help:

```bash
cargo bench --bench cli | stash -a kind=cargo-bench -a commit="$(git rev-parse HEAD)" -a suite=cli
```

This is a good habit for agent workflows because it preserves benchmark history
even when the comparison was not planned in advance.

## Keep the pipeline flowing with `stash tee`

If you still want to stream output to the terminal while saving it:

```bash
cargo test -- --nocapture | stash tee -a kind=test-output | less
cargo bench | stash tee -a kind=bench
```

This is useful in interactive debugging sessions where you want to watch the
command and still keep the result.

## Suggested attribute conventions

Small, predictable attributes make stash output easier to reuse:

- `kind=test-output`
- `kind=cargo-bench`
- `step=pre-refactor`
- `step=post-refactor`
- `phase=before`
- `phase=after`
- `branch=main`
- `commit=<git sha>`
- `suite=cli`

With a few consistent keys, you can quickly find related runs:

```bash
stash ls -a ++kind -a ++phase
stash ls -A
stash attrs --count
```

## When to use a real file instead

Prefer a normal file when:
- another program needs a filename
- you need to edit the result in place
- the output is part of a file-based interface or handoff

Prefer `stash` when:
- the output is mainly for inspection, comparison, or reuse
- stack refs like `@1` and `@2` are more useful than file paths
- the result benefits from lightweight labels