:upload-file

Uploads a single local file via POST /bzz to a chosen postage batch and returns the resulting Swarm reference. Unlike :probe-upload, which posts a synthetic 4 KiB chunk to verify the upload path, :upload-file ships an actual operator-supplied file the same way swarm-cli upload would.

:upload-file <path> <batch-prefix>

<path> is a local file (directories are rejected; a future release will add a :upload-collection verb for that). The file is capped at 256 MiB so the cockpit's event loop doesn't stall while reading it; for larger uploads use swarm-cli where the upload runs out of process.

<batch-prefix> is the 8-character hex shown in the S2 table (trailing … allowed; bee-tui strips it). The chosen batch must be usable and have batch_ttl > 0.

Content type

Inferred from the extension for common types (.html → text/html, .json, .png, .pdf, .tar.gz, .wasm, …). Anything not in the table is uploaded as application/octet-stream — Bee will still serve it on download but the Content-Type header on GET /bzz/<ref> will be the generic value. Override semantics are not exposed yet (no --content-type flag); if you need a specific MIME, rename the file or use swarm-cli.

Output

The verb returns immediately with an "in flight" notice; the actual outcome lands on the command bar when Bee responds.

:upload-file ./build/index.html a1b2c3d4
→ upload-file (12_345B) to batch a1b2c3d4… in flight — result will replace this line

(a few hundred ms later …)
→ upload-file OK in 312ms — 12345B → ref e7f3a201… (batch a1b2c3d4…)

On failure:

→ upload-file FAILED after 412ms — batch a1b2c3d4…: 413 Payload Too Large

CI mode (--once upload-file)

The same verb is available out of the TUI for snapshot-publish workflows:

bee-tui --once --json upload-file ./dist/site.html a1b2c3d4

Emits structured JSON including reference, size, content_type, and batch_id so a downstream step can pin the ref or post it to a release artefact.

When to use it

  • Publishing a single file (a static page, a release asset, a PDF) without leaving the cockpit.
  • Pinning a known input with a known batch + known content type so the swarm hash is reproducible across runs.
  • Verifying a fresh batch is wired correctly by uploading a real file end-to-end (:probe-upload covers the chunk path; this covers the manifest path).

What it doesn't do

  • No directory upload. Single-file scope only — collection upload comes later.
  • No retrieval check. Stops at upload success; pair with :inspect <ref> after if you want to verify the manifest is parseable.
  • No automatic stamp picking. Explicit <batch-prefix> is required so you always know which batch your upload was stamped against.