# Read your first Campaign with the CLI


You need Node.js 20 or newer, npm and a terminal. For the first read, arrange a supported CLI session or an organization Key with `campaign:read`; the steps below verify its target and scope.

> Before using these instructions, check [operation availability and compatibility](/api/compatibility).

The `hbd` command is a terminal client for Campaign API operations and delivered-record reads. `hb` and `humanbased` are alternate executable names. The public beta is `humanbased` on npmjs. It is Apache-2.0 and needs no GitHub login:

```sh
npm install --global humanbased@0.1.0-beta.3
```

These examples target `humanbased@0.1.0-beta.3`; verification of its public npm artifact is pending. The pinned install keeps this walkthrough reproducible; `humanbased@beta` follows the moving beta channel. Ask [Humanbased support](mailto:support@humanbased.ai) if the installed version does not match the environment you were given.

Preparing a review of customer feedback? Go to [the delivered-data quality workflow](/api/cli-quality).

If your organization has authorized a checkout of the Humanbased monorepo, developers can build that checkout with Node.js 20 or newer and the repository's pnpm workspace:

```sh
pnpm install --frozen-lockfile
pnpm --filter @humanbased/cli build
node packages/cli/dist/hb.js --version
```

Run those commands from the repository root. For the examples below, replace `hbd` with `node packages/cli/dist/hb.js` when using the source build. A source build is a developer route, not a public package installation.

## Discover this build before using it

```sh
hbd --version
hbd --help --json
hbd config profiles list --json
```

The JSON help inventory and profile commands make no network request. The CLI connects to the public service by default; a profile records a configured destination, not a credential. Check the current profile before changing that destination.

Use `hbd auth login` for the supported browser sign-in flow, or provide an authorized organization key through `HB_API_KEY` as described below. Then run:

```sh
hbd auth status
hbd auth whoami --json
hbd capabilities --json
```

Check the selected organization and granted capabilities. A key supplied through `HB_API_KEY` takes precedence over a saved session. A configured destination must use its matching API origin; mismatched origins are refused.

## Choose a credential

A person can use `hbd auth login` on a supported build to approve a sign-in in the browser. The resulting CLI session has narrower authority than a full portal session. For unattended automation, supply an organization API Key through the runtime's secret mechanism as `HB_API_KEY` or `--token-stdin`. Do not place the Key in a command line, repository, profile, or agent prompt. Keys and browser sessions are different credentials with different permissions.

The server still decides whether the selected credential can read or change a particular Campaign. A capability in a local help listing is not proof of a grant. A `403` calls for `hbd auth whoami --json`, a check of the active organization, and review of that Campaign's permissions—not a broader retry with another person's credential.

## Read first and check the result

For a read-only starting point, list the Campaigns visible to the selected identity:

```sh
hbd campaign list --limit 5 --json
```

The machine response is one JSON envelope on standard output. Check its `error.code` and the process exit code; progress goes to standard error. An empty `data.items` means no Campaign was visible in that scope. If `data.has_more` is true, pass the returned `data.next_cursor` as `--cursor` for the next page. `--all` deliberately walks multiple pages, so use it only when that larger read is intended.

| Exit code | Meaning |
| --- | --- |
| `0` | The command met its completion rule; a receipt read can still report a failed write. |
| `1` | The request completed, but the command's completion rule did not hold: a document that fails validation, a plan that cannot be applied, or a `campaign records pull --all` export that stopped early. |
| `2` | Invalid command arguments or a malformed request. |
| `3` or `4` | Missing credential or insufficient permission. |
| `5` | Conflict or outcome requiring a person's decision. |
| `6` | Transient failure, or output that could not be delivered; follow the command's retry guidance. |
| `7`–`10` | Backend failure, spend limit, wait timeout, or contract mismatch; inspect `error.code`. |
| `130` | Interrupted. |

When you finish with a browser session, use `hbd auth logout`. `hbd auth sessions list` and `hbd auth sessions revoke` let you inspect and revoke saved sessions; an API Key is managed separately by its organization.

Continue with the [command reference](/api/cli).
