Skip to main content
The HoneyHive CLI (@honeyhive/cli) is a single-binary client that maps one-to-one to the HoneyHive REST API. Use it to script datasets, runs, and projects from your terminal, CI, shell pipelines, or AI coding agents like Cursor and Claude Code. The CLI is organized into namespaces: honeyhive datasets, honeyhive datapoints, honeyhive experiments, etc. JSON-shaped flags accept JSON literals; scalar flags take their natural shell type. Run honeyhive --help to discover namespaces, honeyhive <namespace> --help to discover commands, or honeyhive <namespace> <command> --help to discover flags.

​
Installation

​
macOS (Homebrew)

brew tap honeyhiveai/tap
brew install honeyhive

​
Linux/WSL (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.3.0/install.sh | sh
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. 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

​
Data plane URL

By default the CLI talks to https://api.dp1.us.honeyhive.ai. To point at a self-hosted deployment or a staging environment, set the HH_DATA_PLANE_URL environment variable or pass --data-plane-url: 
export HH_DATA_PLANE_URL=https://honeyhive.example.com
honeyhive datasets list

# Or per-invocation:
honeyhive --data-plane-url https://honeyhive.example.com datasets list
The --base-url flag and the HH_API_URL environment variable are deprecated and will be removed in the next major version. Using either logs a deprecation warning to stderr. Migrate to --data-plane-url / HH_DATA_PLANE_URL.

​
Verbose logging

Pass --verbose (or set HH_VERBOSE=true) to log the resolved data plane 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
# Data plane URL: https://api.dp1.us.honeyhive.ai
# API Key: hh_****XXX
# Package: @honeyhive/cli vX.Y.Z
Output is written to stderr and only fires once per invocation. 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.

​
Schema introspection

Every command that takes arguments supports two read-only flags for tooling and AI agents:
  • --show-file-schema: print the JSON Schema for the full request object (the same shape --filename accepts). See Using a file for upload arguments for the file format.
  • --show-argument-schema <flag-name>: print the JSON Schema for a single argument’s value (e.g., honeyhive sessions create --show-argument-schema user-properties). Pass the kebab flag name without the leading --.
Both write pure JSON to stdout and never call the API. They cannot be combined with any other command-specific flag.

​
Example: Creating and deleting a dataset

Given a datapoint.json file: 
{
  "inputs": { "question": "What is the capital of France?" },
  "ground_truth": { "answer": "Paris" }
}
Create the dataset, append the datapoint, then clean up: 
# 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. Delete the dataset.
honeyhive datasets delete --dataset-id "$DATASET_ID"

​
Using a file for upload arguments

Instead of passing data via command line arguments, you can read from a file using the --filename/-f flag: 
honeyhive datapoints create --filename datapoint.json
You can get the JSON Schema for the file by running: 
honeyhive datapoints create --show-file-schema
The file contains the entire request (request body + URL params + query params) flattened into a single object. Properties follow the format of the OpenAPI spec, so top-level properties use snake_case or camelCase, not --kebab-case like the CLI flags.

Config as Code

Define evaluators and datasets in your repo and apply them with --filename.

Use with Coding Agents

Combine the CLI with HoneyHive Skills and Docs MCP.

CLI Reference

Browse the full auto-generated command reference.

TypeScript API SDK

The programmatic counterpart to the CLI for TypeScript/Node.js.