Automation and agents

CLI guide

Use stable output, project defaults, shell completion, and safe diagnostics.

Before you start

Install and authenticate the CLI.
Know the workspace and project slugs required by the command.

Select scope and output

global options

blobyard --workspace demo-team --project release-files ls
blobyard --json projects list
blobyard --verbose whoami

--json emits one stable JSON document on standard output.
--quiet suppresses non-essential status output.
--verbose sends redacted diagnostics to standard error.
--api-url, --workspace, and --project override configured defaults.

Configure repeatable workflows

Configuration precedence is command flag, environment, project .blobyard.toml, user configuration, then the production API. BLOBYARD_TOKEN is a temporary scoped automation override and is never written to disk.

zsh completion

blobyard completion zsh > ~/.zfunc/_blobyard

Handle failures safely

Reference and troubleshooting

Syntax and behavior

Reusable syntax

global CLI grammar

blobyard [--json] [--quiet | --verbose] [--api-url <url>] [--workspace <slug>] [--project <slug>] <command> [command-options]

Concrete example

scoped JSON listing

blobyard --json --workspace demo-team --project release-files ls blobyard://demo-team/release-files/releases --versions

Values used

--json: Emits one stable JSON document on standard output.
--workspace and --project: Remote scope overrides available to every command.
releases: Optional logical-path prefix inside the selected project.
--versions: Includes immutable versions rather than current objects only.

Expected result

The command writes a machine-readable listing to standard output and keeps progress or redacted diagnostics on standard error.

If it fails

Remove either --quiet or --verbose because they are mutually exclusive.
Use --help on the command family when argument parsing returns exit code 2.

Security and lifecycle

Do not place BLOBYARD_TOKEN in command arguments. Environment-backed tokens must remain scoped, expiring, and protected by the host process.