bee-check 0.6.0

Retrievability checker for Ethereum Swarm references. Multi-vantage stewardship probes, per-chunk drill-down, and one-shot re-seed.
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

# Command reference

```
bee-check <INPUT> [OPTIONS]
```

## Positional

| Argument | Description |
|----------|-------------|
| `<INPUT>` | Swarm reference (64- or 128-hex) or feed handle `feed:OWNER:TOPIC` (40-hex owner, 64-hex topic). Feed inputs are resolved via `GET /feeds/{owner}/{topic}` on the first `--bee`. |

## Probing

| Flag | Default | Description |
|------|---------|-------------|
| `-b`, `--bee <URL>` | `$BEE_API_URL` or `http://localhost:1633` | Bee API URL. Repeat for multi-vantage. |
| `--gateway <URL>` | `https://api.gateway.ethswarm.org` (unless `--no-gateway`) | Public gateway to HEAD-probe via `{url}/bzz/{ref}/`. Repeat for multiple. |
| `--no-gateway` | — | Skip public-gateway probing entirely. |
| `--target-overlay <HEX>` | — | Sort vantages closest-first to this target overlay and tag each with `target_proximity`. |
| `--per-chunk` | off | Walk the manifest and probe every reachable chunk on every vantage. Capped at 1000 chunks. |
| `--cold` | off | End-to-end download probe. Streams `GET /bytes/{ref}` from each Bee URL and `GET /bzz/{ref}/` from each gateway, recording total bytes + elapsed_ms. Complements stewardship. |
| `--timeout <SECS>` | `60` | Per-call timeout. |
| `--concurrency <N>` | `8` | Max parallel chunk probes during `--per-chunk`. |

## Re-seed

| Flag | Description |
|------|-------------|
| `--reseed` | After probing, re-upload the reference via `PUT /stewardship/{ref}`. Requires `--stamp`. |
| `--stamp <ID>` | Postage batch ID for re-seed (64-hex). |

See [The re-seed flow](./reseed.md) for the full sequence.

## Output

| Flag | Default | Description |
|------|---------|-------------|
| `--output <FORMAT>` | `text` | One of `text`, `json`. See [Output formats](./output-formats.md). |
| `-v`, `--verbose` | off | Repeat for more: `-v` info, `-vv` debug (incl. every HTTP call), `-vvv` trace. Default level is `warn`. `RUST_LOG` overrides if set. |

## Help and version

```bash
bee-check --help
bee-check --version
```

## Worked examples

Single vantage against the default Bee:

```bash
bee-check c79394a6c311f816373ec9945365325e7fc0784cfa9a62deec1524d2c2bdc36a
```

Three vantages + a gateway, JSON output:

```bash
bee-check <ref> \
  --bee https://a.example \
  --bee https://b.example \
  --bee https://c.example \
  --gateway https://api.gateway.ethswarm.org \
  --output json
```

Resolve a feed first, then probe the current update:

```bash
bee-check feed:1234567890abcdef1234567890abcdef12345678:5678abcd...
```

Per-chunk drill-down across two vantages, machine-readable:

```bash
bee-check <ref> \
  --bee http://localhost:1633 \
  --bee https://b.example \
  --per-chunk \
  --output json | jq '.chunk_stats'
```

Pre-flight + re-seed in one command:

```bash
bee-check <ref> --reseed --stamp <batch-id> --bee https://my-bee.example
```

Stewardship + cold-download in one shot — useful when stewardship
disagrees with `/bzz` and you want to confirm bytes actually flow:

```bash
bee-check <ref> --cold --bee http://localhost:1633 \
  --gateway https://api.gateway.ethswarm.org \
  --output json | jq '.cold_downloads'
```