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. Pass JSON literals for JSON-shaped flags and plain shell values for scalar flags. 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.8.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. Each command selects its credential:

Key	Environment variable	Root-level flag	Used for
Data plane fine-grained	`HH_DATA_PLANE_API_KEY`	`--data-plane-api-key`	Supported project-scoped commands
Ingestion	`HH_INGESTION_API_KEY`	`--ingestion-api-key`	Creating sessions and writing events
Classic project	`HH_PROJECT_API_KEY`	`--project-api-key`	Other data plane operations, and ingestion when no ingestion key is set
Control plane fine-grained	`HH_CONTROL_PLANE_API_KEY`	`--control-plane-api-key`	Managing projects, alerts, workspaces, and virtual data planes

See API Keys to create the credentials your commands need.

Data plane API key

Set HH_DATA_PLANE_API_KEY to a complete hh_fgdp_ key. For supported commands, pass --project-id even if the key is rooted at that project. This example requires project.chart.list:

export HH_DATA_PLANE_API_KEY="your-data-plane-key"
export PROJECT_ID="your-project-id"
honeyhive charts list --project-id "$PROJECT_ID"

Copy the project ID and data plane URL from Settings > Project > API Keys > Data Plane. Set HH_DATA_PLANE_URL if the URL differs from the default. You can also supply the key with honeyhive --data-plane-api-key "$MY_DATA_PLANE_KEY" charts list --project-id "$PROJECT_ID". For commands with both legacy and scoped routes, --project-id selects the scoped route and data plane key. Without it, the command selects the legacy route and project key. Legacy chart, dataset, and datapoint calls are deprecated. Configuring a data plane key does not change calls that omit --project-id, and a project key cannot substitute for a data plane key. See the credential matrix. The data-plane-api-keys create and ingestion-api-keys create commands also use this credential and require --project-id. They need an organization-rooted key with key-creation permissions. See How to create API keys programmatically.

Project API key

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

An ingestion API key (hh_ingst_) can be supplied alongside the other keys, 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. Other commands never use 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 key it needs and the flag or variable to supply it in. A wrong key type or incomplete value in a typed key option is rejected, naming its source 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 for the command’s required credential before sending the request. Typed options validate the key type, while the classic project-key option forwards its value without that check.

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)
# Data plane API key: (none)
# Package: @honeyhive/cli vX.Y.Z

Output is written to stderr and only fires once per invocation. An explicit --verbose flag matches the precedence of the other flags. Data plane commands log all three data plane credential slots, including (none) for unset keys. Control plane commands log only the control plane URL and key. Keys are masked. A classic project API key shows a recognized prefix and the last 4 characters. Ingestion and fine-grained keys show their prefix and key id with the secret replaced by ******: hh_ingst_<key id>_******, hh_fgdp_<key id>_******, or hh_fgcp_<key id>_******. These match the masked forms shown in the HoneyHive app. A typed key with a missing or malformed key id is replaced entirely with 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

Keep evaluators, datasets, charts, and alerts in your repo and apply them with the CLI.

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

​Data plane API key

​Project API key

​Environment variable (recommended)

​—project-api-key flag

​Ingestion API key

​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

Data plane API key

Project API key

Environment variable (recommended)

—project-api-key flag

Ingestion API key

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