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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.