Skip to content
Docs
Download Markdown
In this article

Read your first Campaign with the CLI

Install, select an environment, authenticate and verify a bounded read.

Download Markdown

You need Node.js 20 or newer, npm and a terminal. For the first read, arrange a supported CLI session or an organizationThe Developer-side unit that holds Campaigns, data access, and funds Key with campaign:read; the steps below verify its target and scope.

Before using these instructions, check operation availability and compatibility.

The hbd command is a terminal client for CampaignA developer's data-production project and its settings 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:

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

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:

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

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:

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:

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 codeMeaning
0The command met its completion rule; a receipt read can still report a failed write.
1The 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.
2Invalid command arguments or a malformed request.
3 or 4Missing credential or insufficient permission.
5Conflict or outcome requiring a person's decision.
6Transient failure, or output that could not be delivered; follow the command's retry guidance.
7–10Backend failure, spend limit, wait timeout, or contract mismatch; inspect error.code.
130Interrupted.

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.