Global flags
global CLI grammar
blobyard [--json] [--quiet | --verbose] [--api-url <url>] [--workspace <slug>] [--project <slug>] [--retry-key <key>] <command> [command-options]| Flag | Meaning |
|---|---|
| --json | Emit one stable JSON document on standard output. |
| --quiet | Suppress non-essential status and progress output. |
| --verbose | Emit redacted diagnostics on standard error. |
| --api-url <url> | Override the Blob Yard API base URL. |
| --workspace <slug> | Select a workspace slug. |
| --project <slug> | Select a project slug. |
| --retry-key <key> | Reuse one opaque idempotency key when retrying the same mutation after an ambiguous result. |
--quiet and --verbose are mutually exclusive. Global flags are accepted before or after the command name.
Sessions, workspaces, and projects
| Command | Purpose |
|---|---|
| login [--name <device-name>] [--no-open] | Sign in through the browser-approved device flow. |
| logout | Revoke the current CLI session. |
| whoami | Show the current authenticated identity and scope. |
| init | Create project-local Blob Yard configuration. |
| workspaces list | List workspaces visible to the current identity. |
| workspaces create <name> | Create a workspace. |
| workspaces rename <name> | Rename the selected workspace. |
| projects list | List projects visible in the selected workspace. |
| projects create <name> | Create a project. |
Files, capabilities, retention, and Web Yards
| Command | Purpose |
|---|---|
| upload <path> [--path <logical>] [--include-ignored] | Upload a file or directory. |
| download <uri> --output <path> [--force] | Download an immutable or current object version. |
| ls [uri-prefix] [--versions] | List objects under an optional URI prefix. |
| rm <uri> | Soft-delete a logical object. |
| share <path-or-uri> [--expires <duration>] [--notify <email>] | Create an expiring share. |
| shares list | List redacted share metadata. |
| shares revoke <share-id> | Revoke a share by stable identifier. |
| preview <directory> [--expires <duration>] | Publish an isolated static preview. |
| previews list | List redacted preview metadata. |
| previews revoke <preview-id> | Revoke a preview by stable identifier. |
| deploy <directory> --yard <name> --public [--spa] [--clean-urls] | Publish a static directory to a named Web Yard. |
| deploy --all --public | Deploy every Web Yard configured in .blobyard.toml. |
| yard list | List Web Yards in the selected project. |
| yard show [name] | Show one Web Yard and its stable public URL. |
| yard history <name> | List immutable deploy history for a Web Yard. |
| yard rollback <name> [deploy-id] | Repoint a Web Yard to an earlier successful deploy. |
| yard delete <name> [--force] | Delete a Web Yard and its deploy history. |
| inbox create <name> [--expires <duration>] | Create a guest upload inbox. |
| inbox list | List redacted inbox metadata. |
| inbox revoke <inbox-id> | Revoke an inbox. |
| retention set --latest <count> [--branch <glob>] [--path <glob>] | Set or replace a retention policy. |
| retention show | Show the selected project's policy. |
| retention overview | Show the policy and latest retention run. |
| retention clear | Clear the selected project's policy. |
| completion <bash|zsh|fish> | Generate shell completion output. |
| mcp serve --stdio | Serve Blob Yard tools to a local AI client. |
Administration, billing, and account lifecycle
| Command family | Operations |
|---|---|
| audit | List redacted workspace audit events with bounded pagination. |
| members | List members, change a role, or remove a member. |
| invites | List, create, or revoke workspace invitations. |
| tokens | List, create, or revoke scoped API tokens. |
| trusts | List, create, or revoke GitHub Actions OIDC trusts. |
| sessions | List or revoke browser-approved CLI sessions. |
| billing | Show billing state, open Checkout or the billing portal, update a plan, or manage paid storage capacity. |
| account export | Request an export, show its state, or download one export part. |
| account delete | Show deletion state, prepare separate confirmation and recovery capabilities, complete deletion with --force, or retry a failed deletion job. |
Use blobyard <command> --help for the exact options accepted by one family. The OpenAPI document is the complete generated route inventory. One CLI workflow can safely orchestrate several HTTP operations, for example multipart upload or Web Yard deployment.
Intentional exclusions
Environment and configuration
| Variable | Meaning |
|---|---|
| BLOBYARD_API_URL | API base URL override. |
| BLOBYARD_WORKSPACE | Workspace slug override. |
| BLOBYARD_PROJECT | Project slug override. |
| BLOBYARD_TOKEN | Ephemeral bearer token that bypasses the credential store. |
| BROWSER | Preferred browser launcher for the login flow. |
Values resolve in order: command flag, environment variable, the nearest .blobyard.toml up the directory tree, the user configuration file, then the built-in default API URL. Workspace and project have no default and must come from one of those layers.
JSON output contract
stable JSON envelopes
{"ok":true,"data":{},"requestId":"req_9f2c4c8a"}
{"ok":false,"error":{"code":"NOT_FOUND","message":"That object was not found."},"requestId":"req_9f2c4c8a"}With --json the CLI prints exactly one envelope on standard output, for success and for failure. Local commands report a null requestId. Warnings and --verbose diagnostics stay on standard error, outside the envelope.