Metadata-Version: 2.5
Name: blobhub-cli
Version: 0.8.1
Summary: BlobHub command line interface — work with blobs, revisions, and their contents from the terminal
Project-URL: Homepage, https://blobhub.io/
Project-URL: Documentation, https://docs.blobhub.io/
Project-URL: Source, https://github.com/blobhubio/blobhub-cli
Project-URL: Issues, https://github.com/blobhubio/blobhub-cli/issues
Author-email: BlobHub <developers@blobhub.io>
License: MIT License
        
        Copyright (c) 2026 BlobHub. All rights reserved.
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: automation,blobhub,blobs,cli,command-line,versioning,workflows
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Description-Content-Type: text/markdown

# BlobHub CLI

[BlobHub](https://blobhub.io/) 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

```sh
pipx install blobhub-cli
```

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

## Authenticate

```sh
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:

```sh
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:

```sh
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`:

```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):

```sh
blobhub workflow pull -f manifest.yaml
```

Compile and deploy:

```sh
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:

```sh
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](https://docs.blobhub.io/cli/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`.

```yaml
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`.

```sh
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](https://docs.blobhub.io/cli/introduction).

## License

MIT. See `LICENSE`.
