# The `:command` bar
A vim-style colon prompt for actions that don't fit on the
keymap: jump to a screen by name, fire on-demand checks,
switch profiles, export a diagnostic bundle.
## Opening + closing
| `:` | Open the command bar (focus moves to a one-line prompt at the bottom) |
| `Esc` | Close without running |
| `↵` | Run the command |
| `Backspace` | Delete left |
The screen behind the bar keeps refreshing — gauges don't
freeze while you're typing.
## Status line
After a command runs, the bottom line shows the result for
~3 seconds before fading:
- **Info** (green) — `→ Health`, `diagnostic bundle exported to /tmp/...`
- **Err** (red) — `unknown command: "..."`, `usage: :set-logger <expr> <level> ...`
If you missed the message, just re-run — the status sticks
until the next command or the next 3 s tick.
## Screen jumps
Every screen has a name; `:<name>` jumps there.
| `:health` | S1 — Health gates |
| `:stamps` | S2 — Stamps + bucket drill |
| `:swap` | S3 — SWAP / cheques |
| `:lottery` | S4 — Lottery + rchash |
| `:warmup` | S5 — Warmup checklist |
| `:peers` | S6 — Peers + bin saturation |
| `:network` | S7 — Network / NAT |
| `:api` | S8 — RPC / API health |
| `:tags` | S9 — Tags / uploads |
| `:log` | S10 — Command log |
These are equivalent to pressing `Tab` until you reach the
target screen, but faster on a 10-screen carousel.
## Action commands
| `:diagnose` (alias `:diag`) | [diagnose](./diagnose.md) | Dump the full snapshot + recent log buffer to a file |
| `:pins-check` (alias `:pins`) | [pins-check](./pins-check.md) | Run a full integrity check on every locally pinned reference |
| `:loggers` | [loggers](./loggers.md) | Snapshot the live logger registry to a file |
| `:set-logger <expr> <level>` | [loggers](./loggers.md) | Change one logger's verbosity at runtime |
| `:topup-preview <batch> <amount>` | [stamp-previews](./stamp-previews.md) | Predict TTL + cost of topping up an existing batch |
| `:dilute-preview <batch> <new-depth>` | [stamp-previews](./stamp-previews.md) | Predict capacity / TTL change of diluting a batch |
| `:extend-preview <batch> <duration>` | [stamp-previews](./stamp-previews.md) | Predict cost to gain N days/hours of TTL |
| `:buy-preview <depth> <amount>` | [stamp-previews](./stamp-previews.md) | Predict TTL / capacity / cost of a hypothetical fresh buy |
| `:buy-suggest <size> <duration>` | [stamp-previews](./stamp-previews.md) | Suggest the minimum (depth, amount) to cover a target |
| `:probe-upload <batch>` | [probe-upload](./probe-upload.md) | Upload one synthetic 4 KiB chunk; report end-to-end latency |
| `:upload-file <path> <batch>` | [upload-file](./upload-file.md) | Upload a single local file via `POST /bzz`, return Swarm reference |
| `:upload-collection <dir> <batch>` | [upload-collection](./upload-collection.md) | Recursive directory upload as a Swarm collection (tar `POST /bzz`); auto-detects `index.html` |
| `:feed-probe <owner> <topic>` | [feed-probe](./feed-probe.md) | Latest update for a feed (read-only lookup) |
| `:feed-timeline <owner> <topic> [N]` | [S14 — Feed Timeline](../screens/s14-feed-timeline.md) | Walk a feed's history (newest first), open S14 |
| `:watch-ref <ref> [interval]` | [watch-ref](./watch-ref.md) | Re-run `:durability-check` on `<ref>` periodically (default 60 s) |
| `:watch-ref-stop [ref]` | [watch-ref](./watch-ref.md) | Cancel one (or all) active `:watch-ref` daemons |
| `:pubsub-pss <topic>` | [S15 — Pubsub](../screens/s15-pubsub.md) | Subscribe to a PSS topic, surface frames in S15 |
| `:pubsub-gsoc <owner> <id>` | [S15 — Pubsub](../screens/s15-pubsub.md) | Subscribe to a GSOC SOC, surface frames in S15 |
| `:pubsub-stop [sub-id]` | [S15 — Pubsub](../screens/s15-pubsub.md) | Cancel one (or all) active pubsub subscriptions |
| `:context <name>` (alias `:ctx`) | [context](./context.md) | Switch to a different node profile from your config |
| `:context` | [context](./context.md) | List configured profiles (no switch) |
| `:quit` (alias `:q`) | — | Exit the cockpit |
## Why a colon prompt?
Two reasons:
1. **Discoverability without clutter.** The cockpit can have
ten screen-jumps + half a dozen action commands without
each one needing its own keybinding. The keymap stays
minimal (`Tab`, `↵`, `Esc`, `?`, `:`, `q`); rare commands
live behind the colon.
2. **Familiarity.** Anyone who's used vim, k9s, or lazygit
has the muscle memory. The cockpit's job is to *not*
require new muscle memory.
## What's not on the bar
These actions deliberately don't have a `:command` form:
- **Cashing out cheques.** Cashout is on-chain; it costs gas;
you should think about whether to do it. The cockpit
surfaces the data (S3 Pane 2) but won't trigger the
on-chain transaction. Use `curl POST /chequebook/cashout/<peer>`
if you really mean it.
- **Buying / topping up postage.** Same reasoning. S2 shows
TTL and worst-bucket; the `:*-preview` verbs (see
[stamp-previews](./stamp-previews.md)) compute predicted
TTL/cost without writing — but `bee postage buy` and `bee
postage topup` themselves are operator decisions with
funding consequences and stay outside the cockpit.
- **Stake deposit / withdraw.** Same.
- **Connect / disconnect peers.** Bee's kademlia handles
this without operator help; manual `connect` is a
debugging escape hatch.
The cockpit is a read-mostly observer. The few mutating
commands it *does* have are scoped to diagnostic state, not
funds-bearing actions: `:set-logger` (changes a Bee logger
level) and `:probe-upload` (uploads one synthetic 4 KiB chunk
worth fractions of a cent of BZZ to verify the upload path
works end-to-end).
## See also
- [`:diagnose`](./diagnose.md)
- [`:pins-check`](./pins-check.md)
- [`:loggers` / `:set-logger`](./loggers.md)
- [Stamp dry-run previews](./stamp-previews.md)
- [`:probe-upload`](./probe-upload.md)
- [`:upload-file`](./upload-file.md)
- [`:upload-collection`](./upload-collection.md)
- [`:feed-probe`](./feed-probe.md)
- [S14 — Feed Timeline](../screens/s14-feed-timeline.md)
- [S15 — Pubsub watch](../screens/s15-pubsub.md)
- [`:context`](./context.md)