Getting Started - HoneyHive AI Docs

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, experiments, and trace events 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.7.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. Which key a command needs depends on what it does: most data plane commands take a project API key, the ingestion commands also accept an ingestion key, and the control plane commands take a fine-grained key. Each can be supplied by environment variable or by flag.

Environment variable (recommended)

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

export HH_PROJECT_API_KEY=...
honeyhive datasets list

—project-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 --project-api-key "$MY_HONEYHIVE_KEY" datasets list

The --api-key flag and the HH_API_KEY environment variable are deprecated and will be removed in the next major version. Using either logs a deprecation warning to stderr. Migrate to --project-api-key / HH_PROJECT_API_KEY.

—ingestion-api-key flag

An ingestion API key (hh_ingst_) can be supplied alongside the project key, in the HH_INGESTION_API_KEY environment variable or with --ingestion-api-key. The commands that create sessions and create or update events send it when it is set, and fall back to the project key otherwise. Every other command uses the project key and never the ingestion key.

export HH_INGESTION_API_KEY=...
export HH_PROJECT_API_KEY=...

# Sends the ingestion key
honeyhive sessions create --filename session.json

# Sends the project key
honeyhive datasets list

A run that has only an ingestion key works for those ingestion commands. Any other command exits before sending the request, with a message naming the project API key it needs and the flag or variable to supply it in. A value in HH_INGESTION_API_KEY or --ingestion-api-key that is not an hh_ingst_ key is rejected the same way, naming where the value came from and the expected prefix.

Control plane commands

honeyhive projects, honeyhive alerts, honeyhive workspaces, and honeyhive virtual-dataplanes talk to the HoneyHive control plane, which accepts only a fine-grained API key (hh_fgcp_) created at workspace or organization scope. Supply it in the HH_CONTROL_PLANE_API_KEY environment variable or with --control-plane-api-key. A project key is not accepted there, and the data plane commands never use this key, so you only need it for the commands you run.

export HH_CONTROL_PLANE_API_KEY=...
honeyhive alerts list

The CLI checks which kind of key a command needs before sending the request. A control plane key given to a data plane command, or the reverse, fails immediately with a message naming the kind the command requires and the flag or variable the wrong key came from, rather than with a 404 from the server.

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.

Control plane URL

The control plane commands talk to https://api.cp.us.honeyhive.ai by default. To point them at a self-hosted deployment, set the HH_CONTROL_PLANE_URL environment variable or pass --control-plane-url:

export HH_CONTROL_PLANE_URL=https://cp.honeyhive.example.com
honeyhive alerts list

Verbose logging

Pass --verbose (or set HH_VERBOSE=true) to log the resolved URL for the command’s plane, its masked API keys, and the CLI version on startup. Useful when debugging “is this hitting prod or staging?” or “did the right HH_PROJECT_API_KEY get picked up?”.

honeyhive --verbose datasets list
# Data plane URL: https://api.dp1.us.honeyhive.ai
# Project API key: hh_****XXXX
# Ingestion API key: (none)
# Package: @honeyhive/cli vX.Y.Z

Output is written to stderr and only fires once per invocation. The masked project API key keeps the recognized prefix (hh_ for a project key, hh_ro_ for a read-only project key) and the last 4 characters; anything else renders as 8 fixed-width asterisks. An ingestion key renders as hh_ingst_<key id>_******, showing its id and none of its secret. For the control plane commands, the output reports the control plane URL and masks the fine-grained key the same way, as hh_fgcp_<key id>_******.

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.

​Installation

​macOS (Homebrew)

​Linux/WSL (install script)

​Authorization

​Environment variable (recommended)

​—project-api-key flag

​—ingestion-api-key flag

​Control plane commands

​Data plane URL

​Control plane URL

​Verbose logging

​Schema introspection

​Example: Creating and deleting a dataset

​Using a file for upload arguments

​Related

Config as Code

Use with Coding Agents

CLI Reference

TypeScript API SDK

Installation

macOS (Homebrew)

Linux/WSL (install script)

Authorization

Environment variable (recommended)

—project-api-key flag

—ingestion-api-key flag

Control plane commands

Data plane URL

Control plane URL

Verbose logging

Schema introspection

Example: Creating and deleting a dataset

Using a file for upload arguments

Related