Skip to main content

BlobHub CLI

BlobHub is the one-stop shop for agentic development. It is a new set of primitives to build against, which makes agents, copilots and the apps that use them easy to design and build — and inherently compatible, because they are all made of the same parts. Agents live and work inside BlobHub, so it is the system of record and action for them: every agent runs inside guardrails the company sets, and everything it does is on the record, written by the work itself. Under the hood, BlobHub is a serverless platform for versioned blob storage with workflow automation: a workflow, a schedule or a model is a typed, versioned blob behind one REST API.

The BlobHub CLI, blobhub-cli, builds, versions and deploys workflows and schedules from a terminal or CI. A workflow's code stays an ordinary Python package, with real imports and tests, and the CLI compiles it into the flat namespace a code component runs. A manifest in your repository lists what a revision should hold, so deploy writes only what changed and diff shows what would. Login, profiles and output are shared by every command; the rest is grouped by blob type, workflow and scheduler, with blob for inspecting a blob of any type. Every command speaks the public REST API as the user whose API key it carries.

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.

Workflows

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 Error codes 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.

Documentation

The full guide and command reference are at docs.blobhub.io.

License

MIT. See LICENSE.

Metadata

Release files for blobhub-cli 0.8.1

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.1
File Size Uploaded Provenance Actions
blobhub_cli-0.8.1.tar.gz 103.0 kB With provenance Details for blobhub_cli-0.8.1.tar.gz

Built distribution (wheel)

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

Total release size: 237.4 kB

Release files / blobhub_cli-0.8.1.tar.gz

Download URL blobhub_cli-0.8.1.tar.gz
Size 103.0 kB
Tags Source
SHA-256 checksum
How to use checksums
568b698d9bc23c509f7e28b185716c658de4eed34cc95f2cf9d0aa529555f04b
BLAKE2b-256 checksum
How to use checksums
5e3b1d990738266a304a85c714105536c00e8ef4145dc8033e111a303569fb4c
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 15, 2026.

Transparency log

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

Download URL blobhub_cli-0.8.1-py3-none-any.whl
Size 134.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
58157f09147b73fb24656884881301c3b7d7b0f2685fba1bc12e75628aa572ed
BLAKE2b-256 checksum
How to use checksums
25ccbccbdea5813b27191da5092f8a38016332b27da8bb10b08b1595d26d1c88
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 15, 2026.

Transparency log

Security for blobhub-cli 0.8.1

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.1.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 15, 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