blobhub-cli

The command line interface for BlobHub — the serverless platform for versioned blob storage. blobhub authenticates against the platform, addresses your orgs, blobs and revisions, and works with what those revisions contain, from a terminal or from CI.

How the CLI is organized

Everything that is not tied to a particular kind of blob — authentication and profiles, JSON output, error reporting — is shared:

blobhub login | logout | whoami | profile ls | profile use

Everything else is grouped by blob domain, which is the axis the platform itself extends along. Each domain adds its own command group and its own manifest types over one shared base:

blobhub workflow …      # workflow blobs — the domain implemented today

workflow is the first domain and currently the most developed one. Its flagship capability — deploying a revision's code from a real Python package rather than hand-editing it in the visual editor — is described below. Further domains slot in as additional command groups without changing anything above this line.

Install

pipx install blobhub-cli

(or pip install blobhub-cli inside a virtualenv). Requires Python 3.12+; installs a blobhub binary.

Authenticate

blobhub login

Prompts for the API URL (defaults to https://api.blobhub.io/v1) and your API key, verifies it against the platform, and stores it as a named profile under ~/.blobhub/credentials.yaml (0600, refused on load if looser). Multiple profiles are supported:

blobhub profile ls                  # list stored profiles, marking the default
blobhub profile use staging         # switch the default
blobhub login --profile staging --api-url https://api.staging.blobhub.io/v1
blobhub whoami                      # resolved identity, profile, URL, and key scope

For CI, skip the credentials file entirely — set BLOBHUB_API_KEY (and optionally BLOBHUB_API_URL, BLOBHUB_PROFILE); the environment always wins over a stored profile, and a key from the environment alone works with no credentials file present at all.

login itself can also run non-interactively and still store a profile, which the environment-only approach above does not:

printf '%s' "$API_KEY" | blobhub login --profile ci --api-key-stdin --api-url https://api.blobhub.io/v1

--api-key and --api-url each accept a literal, --*-stdin (at most one flag per invocation may read stdin), or --*-env VAR naming an environment variable to read from; --no-input fails instead of prompting when a value has no source. Prefer --api-key-stdin over a literal --api-key, which stays visible in ps and shell history.

A manifest may name its blob bare (blob: checkout) instead of org-qualified. The org then comes from the global --org option (blobhub --org acme-corp workflow deploy …) or from BLOBHUB_ORG; with neither, the bare name is a manifest error naming all three ways to supply one.

The workflow domain

A workflow blob's revision holds definitions whose logic.code components normally have their code typed into the browser, where it cannot be imported, unit-tested, linted, reviewed or version-controlled. The workflow command group closes that gap: you keep the code as an ordinary Python package, and the CLI compiles it into the flat, import-less namespace the platform's sandbox actually executes.

A worked example: deploying a workflow

Say your revision has one workflow definition, alias checkout_flow, with a logic.code component (id: c1) whose code should come from a real Python package rather than being typed into the editor:

my-project/
├── manifest.yaml
├── definitions/
│   └── checkout_flow.json      # the definition document — pulled from, or pushed to, the platform
└── pkg/
    ├── entry.py                 # entry_point
    └── lib/
        └── pricing.py           # a local module entry.py imports

manifest.yaml:

type: workflow_blob_deployment
version: "1.0"
blob: acme-corp/checkout                # <org>/<blob>, or a bare <blob> plus --org/BLOBHUB_ORG
revision: latest                        # or a pinned revision UUID
definitions:
  - alias: checkout_flow
    source: definitions/checkout_flow.json
    category: workflow
    components:
      - id: c1
        code:
          base_path: pkg
          entry_point: entry.py

First pull the current definition (skip this if you're starting a definition from scratch):

blobhub workflow pull -f manifest.yaml

Compile and deploy:

blobhub workflow deploy -f manifest.yaml

deploy builds every bound component locally (inlining local imports from pkg/, stripping sandbox-pre-bound and allowlisted imports, rejecting anything else), uploads only the definitions whose serialized document actually changed, and runs the platform's check_definition against each workflow definition it uploaded. Re-running deploy with nothing changed uploads nothing and says so. --dry-run on every mutating command prints the exact intended calls without performing them; --json emits a single machine-readable object instead of the rendered output.

Other commands in the workflow group:

blobhub workflow diff -f manifest.yaml     # report local/remote differences without writing or uploading
blobhub workflow build -f manifest.yaml    # compile locally only, no network
blobhub workflow check -f manifest.yaml    # re-run check_definition against what's already deployed
blobhub workflow push -f manifest.yaml     # upload verbatim, without the compiler (rarely what you want)

If a code port was edited in the visual editor since the CLI last built it, build/deploy refuse to overwrite it with REMOTE_EDIT (or UNMANAGED_CODE for hand-typed code the CLI never built) — pass --force to overwrite, or reconcile by hand first. See docs/reference/error-codes.md for the full catalog of error and advisory codes, what each one means, and how to resolve it.

License

MIT. See LICENSE.