Metadata-Version: 2.4
Name: blobhub-cli
Version: 0.1.0
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

The command line interface for [BlobHub](https://blobhub.io/) — 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:

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

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

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

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

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

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

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