> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blobhub.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Drive BlobHub blobs, revisions and workflow code from a terminal

The **BlobHub CLI** is `blobhub`, a single binary that authenticates against BlobHub, addresses your orgs, blobs
and revisions, and works with what those revisions contain — from a terminal or from CI.

Its commands are grouped by **blob domain**, the axis the platform itself extends along. Authentication,
profiles, blob inspection and output formatting are shared by everything; everything else lives in a command
group named after a blob domain — `workflow` and `scheduler` today.

The CLI introduces **no new BlobHub backend endpoints** — every command speaks the existing BlobHub REST API as
the user whose API key it carries.

## Why the CLI exists

A workflow definition's `logic.code` component normally has its code typed into a textarea in the visual editor.
Code that lives there cannot be imported, unit-tested, linted, reviewed in a pull request, or version-controlled.

The `workflow` command group closes that gap. You keep the code as an ordinary Python package — modules,
subpackages, local imports, a test suite — and the CLI compiles it into the flat, import-less namespace the
platform's sandbox actually executes. That compilation is deterministic, so the code in your repository and the
code on the revision are the same code, and a rebuild over unchanged sources leaves `git status` clean.

## Install

```bash theme={null}
pipx install blobhub-cli
```

Requires Python 3.12+. The package is `blobhub-cli`; the binary it installs is `blobhub`.

To upgrade later:

```bash theme={null}
pipx upgrade blobhub-cli
```

## Quickstart

```bash theme={null}
# 1. Store credentials and validate your identity against /v1/users/me.
blobhub login

# 2. Describe the revision you deploy to, and what belongs on it.
$EDITOR manifest.yaml

# 3. Compile the package, upload what changed, and check what was uploaded.
blobhub workflow deploy -f manifest.yaml
```

A manifest describes **one revision**. This one deploys a single workflow definition whose `logic.code`
component (`id: c1`) is compiled from the Python package under `pkg/`:

```yaml theme={null}
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
    components:
      - id: c1
        code:
          base_path: pkg
          entry_point: entry.py
```

`definitions/checkout_flow.json` is the definition document itself. Write it by hand, or run
`blobhub workflow pull -f manifest.yaml` to fetch what is already on the revision.

In CI, skip the credentials file entirely: set `BLOBHUB_API_KEY`, and `BLOBHUB_API_URL` if you are not pointing
at the default. A key from the environment works with no credentials file present at all.

## What a deploy looks like

`blobhub workflow diff` reports what a deploy would change: which definitions are present on each side, what
moved in their topology and their code, and whether a code port was edited in the visual editor since the last
build. It writes nothing. `blobhub workflow deploy` then performs it — compile, upload only the definitions whose
document actually changed, and run the platform's own check against each workflow definition it uploaded.

When compilation fails, it fails before anything is uploaded, and the error names both the code and the module
it could not resolve. Every failure the CLI reports carries an error code, usually with a hint naming the way
out; the codes are catalogued in [Error codes](/cli/error-codes).

<Frame caption="`diff` reports the change, `deploy` applies and checks it — a later `deploy` refuses an unavailable import.">
  <img src="https://mintcdn.com/blobhub/qE9RdmidWveexnZk/cli/images/introduction/deploy-session.png?fit=max&auto=format&n=qE9RdmidWveexnZk&q=85&s=e883804d2627dc24b22b4bd0defcce21" alt="blobhub workflow diff and deploy in a terminal" width="2800" height="696" data-path="cli/images/introduction/deploy-session.png" />
</Frame>

## What's in this section

The pages are organized the way the binary is: what is shared comes first, then one group per blob domain.

The **Overview** group covers everything not tied to a kind of blob:

* [Concepts](/cli/concepts) — the mental model: shared versus blob-domain commands, what a manifest describes,
  the verbatim/compiled split, and the platform behaviours that shape every command.
* [Authentication](/cli/auth) — `login`, `logout`, `whoami`, and `profile ls` / `profile use`.
* [Utilities](/cli/utilities) — `doctor`, the preflight to reach for when another command fails, and `completion`.
* **Blob** — [`blob show`](/cli/blob/show), [`blob revisions`](/cli/blob/revisions) and
  [`blob limits`](/cli/blob/limits), which answer "what am I pointing at, and may I write to it?" for a blob of
  any domain.
* [Configuration](/cli/configuration) — the credentials file, the precedence ladder, the global flags, output
  streams, exit codes and the `--json` envelope.
* [Error codes](/cli/error-codes) — the full catalog: what each code means and how to resolve it.

The **Workflow** group covers the `workflow` blob domain: an overview of the deployment lifecycle, one page per
command, and three references — the manifest format, the compiler contract, and what the `logic.code` sandbox
binds.

The **Scheduler** group covers the [`scheduler`](/blob-types/scheduler/overview) blob domain and is structurally
identical: an overview, one page per command, and the scheduler manifest reference.

A new blob domain arrives as one more group, without changing anything above it.