stackbone storage

stackbone storage targets a running agent installation. With no --agent it uses the local-dev installation linked to the current project, so stackbone dev must be running. See target resolution. Every verb accepts --json and emits the standard envelope.

Operate the S3-style object store bound to the targeted installation. --bucket <name> is required on every object verb (an install can expose more than one bucket).

Command	Purpose
`stackbone storage buckets`	List the buckets the installation exposes.
`stackbone storage list`	List objects in `--bucket`, optionally under `--prefix`. `--limit` is 1-1000 (default 100), with `--cursor`.
`stackbone storage get <key>`	Download an object to stdout (or `--out <path>`) via a short-lived presigned URL.
`stackbone storage put <key>`	Upload a local `--file <path>` under the key.
`stackbone storage presign <key>`	Print a short-lived presigned download URL for the object.
`stackbone storage remove <key>`	Delete an object. Requires `--yes`.

list pages with --limit/--cursor, described under pagination. remove is destructive and refuses to run without --yes, described under destructive verbs.

JSON payload

// storage list: paginated, plus folder prefixes
{ "schema_version": 1,
  "items": [{ "key": "uploads/foo.txt", "size": 1024, "content_type": "text/plain",
              "last_modified": "2026-06-01T10:00:00Z", "etag": "\"9a0364b9…\"" }],
  "common_prefixes": ["uploads/"], "nextCursor": null, "prevCursor": null }

// storage presign <key>
{ "schema_version": 1, "url": "https://…", "expires_at": "2026-06-01T11:00:00Z" }

A presigned URL lasts one hour and carries the address it was signed with. get and presign both go through one, so the download works from your machine only while that address resolves there. A box that keeps its objects in AWS S3 or Railway Buckets also needs STACKBONE_S3_FORCE_PATH_STYLE=false in its .env: those backends put the bucket in a subdomain, and the default puts it in the path (what the bundled MinIO speaks). See path-style or subdomain.

stackbone rag manages the reserved rag/ key prefix: the backend rejects put/remove under it.

Exit codes: 0 ok · 4 not found (unknown bucket/key) · 5 permission (remove without --yes) · 1 generic (missing --bucket/--file). See exit codes.