honeycomb

# Honeycomb CLI ## Auth Three key types, stored in the OS keyring per profile: | Type | Used For | |------|----------| | `config` | Management API (boards, SLOs, triggers, columns, queries) | | `ingest` | Sending events (`X-Honeycomb-Team` header) | | `management` | Same as config, kept separate for granular access | ```bash honeycomb auth login # interactive key setup honeycomb auth status # verify stored key honeycomb auth status --offline # check keyring without API call ``` ## Query Requires a `config` key with query permissions. ```bash # from a file honeycomb query run --dataset my-dataset --file query.json # from stdin echo '{"calculations":[{"op":"COUNT"}],"time_range":3600}' | honeycomb query run --dataset my-dataset --file - # list/view saved queries honeycomb query annotation list --dataset my-dataset honeycomb query annotation view <id> --dataset my-dataset ``` ## Raw API Requests `honeycomb api` makes authenticated requests to any Honeycomb API endpoint. Useful for endpoints without dedicated subcommands (events, query results, service maps). ```bash honeycomb api /1/events/my-dataset -X POST --input events.json --key-type ingest honeycomb api /1/query_results/my-dataset/abc123 # poll query results honeycomb api /1/maps/dependencies/requests -q '.results' honeycomb api /2/teams -q '.[].name' --paginate # v2 with jq + pagination ``` Flags: `-X` method, `-f` string fields, `-F` typed fields, `-H` headers, `-q` jq filter, `--paginate`, `--input` body file, `--key-type` override, `--raw` skip JSON:API unwrapping (v2 paths). ## Global Flags | Flag | Purpose | |------|---------| | `--format json\|table` | Output format (default: `table` in TTY, `json` in CI/agent) | | `--profile` | Configuration profile | | `--no-interactive` | Disable prompts | | `--api-url` | Override Honeycomb API URL | ## Patterns - **CRUD convention**: most resources support `list`, `get`, `create`, `update`, `delete` subcommands - **Scoping**: use `--dataset` for dataset-scoped resources (columns, markers, queries), `--environment` where applicable - **Agent auto-detection**: when `CLAUDE_CODE` is set, the CLI forces `--no-interactive` and defaults to `--format json` - **Commands**: `auth`, `query`, `dataset`, `board`, `column`, `marker`, `slo`, `trigger`, `environment`, `key`, `recipient`, `mcp`, `api` ## MCP Server vs CLI `mcp` Subcommand This plugin configures the Honeycomb MCP server (`.mcp.json`) for direct tool access via OAuth. Use its tools (`run_query`, `get_dataset_columns`, `find_columns`) when you need query results in context. The CLI's `mcp` subcommand is a separate MCP *client* that authenticates with a config key (Bearer token). Use it when you need to write MCP results to disk: ```bash honeycomb mcp call run_query -f dataset=prod -q '.content[].text' > results.json honeycomb mcp tools # list available MCP tools ```