swarmops blob put#

Store FILE's content as a blob, outside any commit, and print its id, which a change names it by: {"blob": ID}. A change list holds at most 64 MiB and a commit's contents 1 GiB together; a blob named by id counts toward neither.

Syntax#

swarmops blob put [OPTIONS] <FILE>

Required arguments#

Optional arguments#

The command also takes the global options.

Examples#

swarmops --repo [tmp]/store --as agent/worker-17 blob put [tmp]/payload.txt

{
  "ok": true,
  "op": "blob_put",
  "api": 1,
  "result": {
    "blob": "[blob]",
    "size": 12,
    "written": true
  },
  "meta": {
    "repo": "[tmp]/store",
    "elapsed_ms": "[elapsed_ms]",
    "resolved": {},
    "auth": "trust"
  }
}

Details#

blob put stores one file's bytes in the store as a blob, outside any commit, and prints the blob's id. A later change names it by that id, {"content": {"blob": "<id>"}}, and the commit then neither sends nor reads those bytes again. Its MCP tool is blob_put, which takes the content inline, in base64 or as a file on the server's host.

Why it exists#

A change list is at most 64 MiB of text, and a commit's contents at most 1 GiB together. A blob named by id counts toward neither: only one blob's own limit applies, 512 MiB. So large or many files go in one blob put each, then one commit names them all. Over MCP, where every request line is at most 64 MiB, it is also the way to send a file once and refer to it in several commits.

Behaviour#

• FILE is read whole, by the command, on this host; - reads stdin to its end.
• The id is the content's hash: the same bytes always give the same id, whoever puts them. A put of bytes the store holds already writes nothing and says written: false; so does a put that a concurrent writer of the same bytes beat. size is the content's length in bytes.
• The blob is durable when the command returns.
• It is a mutation, so it needs an identity (--as or SWARMOPS_AGENT), but it records it nowhere: a blob has no author, no time and no metadata. The commit that names it records who wrote the file.
• It runs outside any transaction: it writes the object alone, takes no lock on the store's metadata and writes no journal frame, so op log does not list it and there is nothing to undo. Until a commit names the blob, nothing in the metadata does.

Patterns#

BASE=$(swarmops resolve main | jq -r .result.id)
B=$(swarmops blob put big.bin | jq -r .result.blob)
printf '[{"path": "assets/big.bin", "op": "put", "content": {"blob": "%s"}}]' "$B" > change.json
swarmops commit -m "add the asset" --changes change.json --parent "$BASE"

• With many files, put them first, then commit one change list that names every id. The commit's blobs_written is 0 for each of them.
• Before putting a large file again, blob has tells whether the store holds it already.
• A blob nothing names stays in the store: nothing removes it, as nothing is removed yet (Where a store may live).

Failures#

Return information#

result is a BlobPutResp (swarmops schema BlobPutResp prints its JSON Schema).

Envelope op: blob_put.

Exit codes:

• 0: Success.

Errors#

No golden step shows this command failing yet.

Any command that opens a store may also fail with a store error, such as E_NOT_A_REPO, E_IO or E_STORE_CORRUPT; a command line the grammar refuses is E_INVALID_ARG (exit 2).

See also#

• swarmops commit
• swarmops land
• swarmops blob has
• CLI reference
• Error codes