> ## Documentation Index > Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt > Use this file to discover all available pages before exploring further. # Getting Started > Install and authenticate the HoneyHive CLI, then run your first commands to manage projects, traces, datasets, evaluators, and more from the terminal. 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 --help` to discover commands, or `honeyhive --help` to discover flags. ## Installation ### macOS (Homebrew) ```sh theme={null} 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. ```sh theme={null} curl -fsSL https://github.com/honeyhiveai/honeyhive-cli/releases/download/v1.4.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. ### Environment variable (recommended) Set the `HH_API_KEY` environment variable. The CLI reads it automatically when no `--api-key` flag is provided: ```sh theme={null} 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. ```sh theme={null} 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`: ```sh theme={null} 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?". ```sh theme={null} 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](#using-a-file-for-upload-arguments) for the file format. * `--show-argument-schema `: 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: ```json theme={null} { "inputs": { "question": "What is the capital of France?" }, "ground_truth": { "answer": "Paris" } } ``` Create the dataset, append the datapoint, then clean up: ```sh theme={null} # 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: ```sh theme={null} honeyhive datapoints create --filename datapoint.json ``` You can get the JSON Schema for the file by running: ```sh theme={null} 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](/v2/sdk-reference/openapi-sdks), so top-level properties use `snake_case` or `camelCase`, not `--kebab-case` like the CLI flags. ## Related Define evaluators and datasets in your repo and apply them with `--filename`. Combine the CLI with HoneyHive Skills and Docs MCP. Browse the full auto-generated command reference. The programmatic counterpart to the CLI for TypeScript/Node.js.