# scout
A light, **no-node** client for reading content from
[Swarm](https://www.ethswarm.org/). Point it at a public gateway (or any
Bee HTTP endpoint) and fetch content by reference — no node to run, no
stake, no postage batch. The "scout bee" that finds and fetches without
keeping the hive.
> Published on crates.io as **`swarm-scout`** (the binary and library are
> both `scout`).
## Install
```sh
cargo install swarm-scout # provides the `scout` command
```
## Usage
```sh
# read — no node, stake, or stamp
scout cat <ref> [path] # print content to stdout (manifest-aware, /bzz)
scout get <ref> <out> [path] # download content to a file
scout bytes <ref> # print the raw bytes behind a reference (/bytes)
# write — needs a Bee node holding a postage batch
scout up <file> [--name n] --stamp <batch> # upload a file (/bzz) -> ref
scout up-bytes <file> --stamp <batch> # upload raw bytes (/bytes) -> ref
scout up-dir <folder> [--index index.html] --stamp <batch> # upload a browsable collection -> ref
# feeds — a stable handle that always serves the latest content
scout keygen # identity (key + owner + pubkey)
scout publish <ref> --key <hex> -t <topic> --stamp <batch> # -> feed manifest ref
scout cat <feed-manifest-ref> # read latest (re-publish to update)
# sharing — encrypted + revocable (Access Control Trie)
scout share <file> --to <pubkey> --stamp <batch> # encrypt+grant; records a share id
scout shares # list your shares
scout grantees <id> # who has access
scout revoke <id> --grantee <pubkey> --stamp <batch> # drop a key
scout fetch <file_ref> --publisher <pk> --history <h> # recipient: decrypt
```
Reads default to the **public Swarm gateway** (`--gateway` / `$BEE_GATEWAY`
= `https://download.gateway.ethswarm.org`), so `scout cat <ref>` works with
zero setup. Uploads go to your own Bee node (`--node` / `$BEE_NODE`,
default `http://localhost:1633`) and need `--stamp` / `$BEE_STAMP` (a
usable postage batch):
```sh
scout cat <ref> # reads via the public gateway
scout --gateway http://localhost:1633 cat <ref> # ...or your own node / a private gateway
scout up photo.jpg --stamp <batch> # uploads to your node -> reference
BEE_NODE=https://my-node.example BEE_STAMP=<batch> scout up notes.md
```
## Library + examples
`scout` is also a library (`swarm-scout`): [`LiteClient`] wraps the
read/write/feed/ACT calls, and the **stash / perch / keep** tools below are
each built on it. See [`examples/`](examples) (`cargo run --example read --
<ref>`) and the API docs on [docs.rs](https://docs.rs/swarm-scout).
## Why "light"?
Reads (`/bzz`, `/bytes`) are served by any gateway or remote Bee — no
local node, stake, or stamp required. That's the light-node idea: most
people who *use* Swarm just want to fetch (and, later, share) content,
not operate infrastructure.
## Feeds (mutable pointers)
A feed gives you a **stable reference that always serves the latest
content** — the basis for "a folder/site whose contents change but whose
link doesn't."
```sh
scout keygen # save the key; note the owner
scout publish <ref> --key <key> -t mysite --stamp <batch> # prints a feed manifest ref
scout cat <feed-manifest-ref> # serves the latest published content
# publish again under the same key+topic → the same manifest ref now serves the new content
```
## Sharing (ACT)
Encrypted, revocable sharing via Swarm's Access Control Trie. `share`
uploads a file encrypted and grants a set of recipient **compressed
pubkeys** (`scout keygen` prints one); recipients download with the
`file_ref` + `publisher` + `history`. `revoke` drops a key without
re-uploading.
Shares you create are recorded in `~/.scout/shares.json` and managed by a
short **id** (`scout shares`), so you don't juggle hex refs:
```sh
scout keygen # note the pubkey
scout share secret.pdf --to <recipient-pubkey> --stamp <batch> # -> id + refs
scout shares # list your shares
scout grantees <id> # who currently has access
scout revoke <id> --grantee <recipient-pubkey> --stamp <batch>
scout fetch <file_ref> --publisher <pubkey> --history <h> out.pdf # recipient side
```
A recipient decrypts on **their own** Bee node (configured with the key
behind their pubkey); the node does the decryption, so `fetch` works for
whoever's node it runs against (the publisher always; a grantee on theirs).
## Status
- **Read** — `cat` / `get` / `bytes`; no node, stake, or stamp.
- **Write** — `up` / `up-bytes` to a Bee node holding a postage batch.
- **Feeds** — `keygen` / `publish`; read the latest via `cat`.
- **Sharing (ACT)** — `share` / `shares` / `grantees` / `revoke` / `fetch`.
- All verified end-to-end against a live Bee node (2.7.2).
## The scout toolkit
scout is the foundation; three focused tools are built **on its library**:
| **[stash](https://github.com/ethswarm-tools/stash)** | `swarm-stash` | sync a folder ↔ Swarm (a feed-backed drive) |
| **[perch](https://github.com/ethswarm-tools/perch)** | `swarm-perch` | publish a folder as a website (stable URL) |
| **[keep](https://github.com/ethswarm-tools/keep)** | `swarm-keep` | an encrypted secrets/notes vault |
Full guide: the **[scout handbook](https://ethswarm-tools.github.io/scout/)**.
Built on [bee-rs](https://github.com/ethswarm-tools/bee-rs).
## License
MIT