Skip to main content

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.

The root --profile selects a stored profile for any command (blobhub --profile staging workflow events …), as BLOBHUB_PROFILE does. An exported BLOBHUB_API_KEY or BLOBHUB_API_URL still wins over the profile it names.

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: default                       # the blob's default revision, 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 workflow pull|push|build|deploy| prune and scheduler deploy) prints the exact intended calls without performing them; --json emits a single machine-readable object instead of the rendered output. The exception is workflow events --follow --json, which writes JSON Lines, one {"event", "schema_version"} object per event and no final object.

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.

Listeners and session events

A listener is a definition with category: listener that acts on a session's event stream: it filters events, batches them, and invokes a workflow, a thread item or an object write. It lives in the manifest beside the workflows and deploys, diffs, pulls and checks like any other definition. The source file holds the whole body (type: listener_definition, filter, batch, concurrency, invocation_target_type, invocation_target, receipt); a listener entry takes no components.

definitions:
  - alias: orchestrate
    category: listener                  # or inferred from `type: listener_definition` in the file
    source: listeners/orchestrate.yaml

A session is named as <session> (with -f manifest.yaml naming its blob and revision), <blob-id>/<revision>/<session> or <org>/<blob>/<revision>/<session>; a qualified reference takes no -f.

blobhub workflow events my-session -f manifest.yaml                      # newest 20 events
blobhub workflow events my-session -f manifest.yaml --types object.written --aliases 'worker/**' --follow
blobhub workflow events my-session -f manifest.yaml --listener orchestrate --after 2026-11-09T17:00:00Z
blobhub workflow events my-session -f manifest.yaml --cursor <token>     # continue the page a listing printed
blobhub workflow listeners my-session -f manifest.yaml [--listener orchestrate]
blobhub workflow listener disable my-session orchestrate -f manifest.yaml   # enable | disable, for this session

--types, --aliases and --executions repeat, and take globs where the platform does. A listing ends with more: --cursor <token> when there is another page; the token carries its own filter and direction, so pass it alone. --follow prints new events until interrupted without missing a late commit. workflow execute --watch follows the run's log the same way and ends once the platform reports the execution finished.

With --json, the new commands print these keys: workflow events {session, events, cursor}; workflow listeners {session_id, listeners, connections}, or with --listener {session_id, listener, executions, last_execution_id}; workflow listener enable|disable {session_id, listener}. workflow diff adds body_changed and validation_error to a listener's report, and scheduler ls adds invocation_target_type and target_alias to each schedule.

License

MIT. See LICENSE.

Metadata

Release files for blobhub-cli 0.8.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for blobhub-cli 0.8.0
File Size Uploaded Provenance Actions
blobhub_cli-0.8.0.tar.gz 102.9 kB With provenance Details for blobhub_cli-0.8.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for blobhub-cli 0.8.0
File Interpreter ABI Platform Actions
blobhub_cli-0.8.0-py3-none-any.whl Python 3 none any Details for blobhub_cli-0.8.0-py3-none-any.whl

Total release size: 237.1 kB

Release files / blobhub_cli-0.8.0.tar.gz

Download URL blobhub_cli-0.8.0.tar.gz
Size 102.9 kB
Tags Source
SHA-256 checksum
How to use checksums
869ac09617f3605e5ffee06255fa2cec7099efa1a15f4e66e844551eca05ffb7
BLAKE2b-256 checksum
How to use checksums
993733bd8231ba5e1b1f943b2def25d0e3021bfba2f991178f55c521745edd1e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / blobhub_cli-0.8.0-py3-none-any.whl

Download URL blobhub_cli-0.8.0-py3-none-any.whl
Size 134.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
29e68afc99e371cdee01917d2849ee86b2652650a0bbd02bee39c8caca665257
BLAKE2b-256 checksum
How to use checksums
1833551fe3c61d776e02b68174f053fbea841945f7aab319c2868d6be5155349
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for blobhub-cli 0.8.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for blobhub_cli-0.8.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page