--once CI mode

Run a single verb without launching the TUI. Designed for CI pipelines, cron jobs, monitoring scripts, and any situation where you want a one-shot answer with a clean exit code instead of a full-screen cockpit.

bee-tui --once <verb> [args…] [--json]

The whole TUI runtime — App, screens, ratatui, supervisor, watch hub — is bypassed. Only what the verb actually needs is built: pure-local verbs touch nothing; Bee-API verbs build a one-shot ApiClient from your active node profile and call Bee directly.

Output

By default, one human-readable line on stdout:

$ bee-tui --once readiness
readiness OK · status=ok · radius=8 · in [1,30]

With --json, a single JSON object on stdout:

$ bee-tui --once readiness --json
{"verb":"readiness","status":"ok","message":"readiness OK · status=ok · radius=8 · in [1,30]","data":{"status":"ok","radius":8}}

JSON shape (stable since v1.3 — see "Stability contract" below):

Exit codes

The split between 1 and 2 matters in CI: code 1 is "the node says no" (alert your on-call); code 2 is "the script is wrong" (fix your YAML).

Tracing

Tracing / logging is not initialised in --once mode. Stdout is reserved for the human line or JSON object — nothing else is written there. Stderr stays clean unless the verb itself prints to it. This keeps bee-tui --once safe to use inside $(), pipes, and structured-output parsers.

The 24 verbs

Pure-local (5 — no Bee call required)

These do not touch the Bee API; you can run them on a build agent that has no Bee node.

Bee API (9 — connects to your active node)

Stamp economics (10 — fetches chain state + stamps then runs pure math)

These all hit the Bee API once to fetch the inputs, then do their work in pure Rust — no chain mutation, no stamp purchase, no upload.

Stability contract

The --once surface is part of bee-tui's semver-stable surface since v1.3:

• The four exit codes (0 ok, 1 unhealthy/failed, 2 usage) are pinned. New failure modes get one of the existing codes, never a new one.
• The JSON shape {verb, status, message, data} is pinned. Future minor versions may grow data with new keys, but existing keys won't be renamed or removed without a v2.0.0 bump.
• Existing verbs won't be removed. New verbs may appear in minor versions.

If you script against --once in CI, you can pin a minor version and trust the surface won't break under you.

Examples

Smoke-test a Bee node from CI

- name: Bee readiness gate
  run: bee-tui --once readiness

Exit 0 → all good. Exit 1 → fail the build.

Watch a stamp in CI

- name: Stamp plan-batch gate
  run: bee-tui --once plan-batch ee7f3a20

Exits 1 when the batch needs Topup, Dilute, or both. Hook a Slack notification onto the failure to nudge the operator before the batch hits the cliff.

Periodic durability check from cron

*/30 * * * * /usr/local/bin/bee-tui --once durability-check $REF --json \
  | jq -c '. + {timestamp:now}' >> /var/log/bee-durability.jsonl

The JSONL is append-only, parseable by anything that speaks JSON, and re-runnable without parsing TUI output.

Upload from a build pipeline

- name: Publish site to Swarm
  run: |
    REF=$(bee-tui --once upload-collection ./public $BATCH --json | jq -r .data.reference)
    echo "site_ref=$REF" >> $GITHUB_OUTPUT

The data.reference field is part of the v1.5 stable surface.

See also

• The :command bar — the cockpit-mode counterpart to most of these verbs
• S12 Watchlist — :durability-check model in depth
• Stamp dry-run previews — the stamp-economics verbs in cockpit form