HoneyHive CLI

@honeyhive/cli is a fully autogenerated command-line client for the HoneyHive REST API. It provides a one-to-one mapping of subcommands to API endpoints, organized into namespaces: honeyhive datasets, honeyhive datapoints, honeyhive experiments, etc.

The CLI is generated from the same OpenAPI specification as the TypeScript API SDK, so command-line flags stay in lockstep with the API. JSON-shaped fields accept JSON literals; scalar fields take their natural shell type. Run honeyhive --help to discover namespaces, or honeyhive <namespace> --help to discover commands.

For more information about HoneyHive, visit the HoneyHive documentation. For the full command reference, see the CLI documentation site.

Installation

macOS (Homebrew)

brew tap honeyhiveai/tap
brew install honeyhive

Linux (install script)

The install script downloads the linux-x64 or linux-arm64 binary from the corresponding GitHub Release, verifies its SHA256, and installs it to /usr/local/bin (falling back to ~/.local/bin if /usr/local/bin isn't writable). To install to a different directory, set the INSTALL_DIR environment variable.

curl -fsSL https://github.com/honeyhiveai/honeyhive-cli/releases/download/v1.0.0-rc.6/install.sh | sh

Note: Alpine and other musl-based Linux distributions are not supported. The CLI binary is dynamically linked against glibc (it embeds the official Node.js runtime), and musl is not ABI-compatible with glibc. The install script will succeed on Alpine, but the installed binary will fail to launch with not found (the kernel reporting that the glibc dynamic linker is missing). Use a glibc-based distribution such as Debian, Ubuntu, Fedora, or RHEL.

Homebrew on Linux is also supported — if you already use Homebrew, the macOS commands above (brew tap honeyhiveai/tap then brew install honeyhive) work on Linux as well.

Authorization

The HoneyHive API authenticates requests using an API key sent as a Bearer token in the Authorization header. There are two ways to provide it.

Environment variable (recommended)

Set the HH_API_KEY environment variable. The CLI reads it automatically when no --api-key flag is provided:

export HH_API_KEY=...
honeyhive datasets list

--api-key flag

Pass the key directly on the command line. Never hard-code the key or commit it to source control — always read it from a secret store or environment variable:

honeyhive --api-key "$MY_HONEYHIVE_KEY" datasets list

Configuration

By default the CLI talks to https://api.honeyhive.ai. To point at a self-hosted deployment or a staging environment, set the HH_API_URL environment variable or pass --base-url:

export HH_API_URL=https://honeyhive.example.com
honeyhive datasets list

# Or per-invocation:
honeyhive --base-url https://honeyhive.example.com datasets list

Verbose logging

Pass --verbose (or set HH_VERBOSE=true) to log the resolved API URL, a masked API key, and the CLI version on startup. Useful when debugging "is this hitting prod or staging?" or "did the right HH_API_KEY get picked up?".

honeyhive --verbose datasets list
# API URL: https://api.dp1.us.honeyhive.ai
# API Key: hh_****5Qrg
# Package: @honeyhive/cli v1.0.0

Output is written to stderr and only fires once per invocation. An explicit --verbose flag matches the precedence of the other flags. The masked API key keeps the recognized prefix (hh_, hh_org_, hh_ws_, hh_cp_, hh_dp_) and the last 4 characters; anything else renders as 8 fixed-width asterisks.

Example: Creating and Deleting a Dataset

Datasets are collections of datapoints used as test sets for evaluations. The following example creates a dataset, appends a datapoint to it from a local JSON file, and then deletes the dataset. JSON-shaped flags accept any string, so reading individual fields from a file with $(jq '…' file.json) keeps the datapoint definition out of the command line.

Given a datapoint.json file like this:

{
  "inputs": { "question": "What is the capital of France?" },
  "ground_truth": { "answer": "Paris" }
}

Create the dataset, append the datapoint, then clean up. The CLI reads HH_API_KEY from the environment (see Authorization).

# 1. Create the dataset and capture its ID from the response.
DATASET_ID=$(honeyhive datasets create \
  --name "qa-eval-set" \
  --description "Question/answer pairs for evaluation" \
  | jq -r '.result.insertedId')

# 2. Append a datapoint from the local file, linked to the new dataset.
honeyhive datapoints create \
  --inputs "$(jq '.inputs' datapoint.json)" \
  --ground-truth "$(jq '.ground_truth' datapoint.json)" \
  --linked-datasets "[\"$DATASET_ID\"]"

# 3. Later, delete the dataset.
honeyhive datasets delete --dataset-id "$DATASET_ID"

Additional resources

• Full CLI command reference
• HoneyHive documentation
• TypeScript API SDK — the programmatic counterpart to this CLI