# CLI (/docs/agents/cli)

`datahop` is a small command that gives you **every** [MCP tool](/docs/agents/tools) from a shell, plus shortcuts for the common ones. Coding agents with a shell, such as Claude Code, Codex and Cursor, can use it without any MCP setup. So can scripts and CI.

<CopyPrompt preset="connect">
  Hand this to your agent. It installs the CLI (or uses MCP), logs in, learns your data and reports what's interesting.
</CopyPrompt>

## Install [#install]

Needs Node 20+ or Bun.

```bash
curl -fsSL https://app.datahop.dev/cli/install.sh | sh
```

It installs to `~/.local/bin/datahop`. You can also download [`datahop.mjs`](https://app.datahop.dev/cli/datahop.mjs) and run it with `node` or `bun`.

## Log in [#log-in]

<Tabs items={['Agents & CI', 'Interactive']}>
  <Tab value="Agents & CI">
    Set two environment variables. Nothing is written to disk.

    ```bash
    export DATAHOP_HOST=https://app.datahop.dev
    export DATAHOP_API_KEY=dh_sk_…
    ```
  </Tab>
  <Tab value="Interactive">
    ```bash
    datahop login --host https://app.datahop.dev --key dh_sk_…
    datahop whoami
    ```

    The key is saved in your user config. `datahop logout` removes it.
  </Tab>
</Tabs>

Use a project [API key](/docs/agents/api-keys). With a read-only key, you only get the read tools.

## Commands [#commands]

| Command | What it does |
| --- | --- |
| `overview` | Start here: products, top events, cohorts, insights, running experiments, recent changes |
| `events [search]` · `event <name>` | Event names and volumes · the properties seen on one event |
| `query <json\|@file\|->` | Any [query](/docs/reference/query-language) |
| `sql "<sql>"` | Read-only SQL over your events |
| `insights [search]` · `insight <id>` | Saved insights · one with fresh results |
| `dashboards` · `dashboard <id>` | Dashboards · every card's summary |
| `persons [search]` · `person <id>` | People · one profile with recent events |
| `cohorts` · `flags` · `experiments` · `activity` | Lists |
| `results <experimentId>` | Verdict, lift, segments and recommendation |
| `tools [<name>]` | Every tool, or one tool's arguments with an example |
| `call <tool> [<json>\|@file\|-] [--arg value …]` | Run any tool |

Arguments for `call` can be JSON, a file (`@args.json`), stdin (`-`) or flags. Flags use kebab-case and dots for nesting:

```bash
datahop call create_cohort --name "Power users" \
  --definition '{"criteria":[{"type":"behavior","event":"project_opened","withinDays":14,"minCount":20}]}'

datahop call create_annotation --date 2026-11-02 --content "Shipped annual discount banner to everyone"
```

## Output [#output]

| Flag | Prints |
| --- | --- |
| *(none)* | The summary, then the data |
| `--json` | Only the JSON, ready for `jq` |
| `--quiet` / `-q` | Only the summary |

The exit code is `0` on success, `1` when the call failed and `2` for usage errors. Errors suggest a fix.

```text
$ datahop results 4 -q
Experiment "Annual plan discount banner" (running). Exposures: control 1475, test 1525.
Primary: Upgraded — control: 30.8% (n=1475); test: 39.1% (n=1525) lift +26.9% [15.0%, 39.8%], P(beats control) 100.0%. Verdict: winner (test).
Recommendation: Ship "test": it is the best variant with 100.0% probability.
```

## In CI [#in-ci]

Because it fails with a non-zero exit code and `--json` output is stable, you can use it as a guardrail. For example, stop a rollout when an experiment's guardrail metric is losing:

```bash
verdict=$(datahop results 7 --json | jq -r '.secondary[0].verdict')
[ "$verdict" = "loser" ] && { echo "Guardrail metric is losing — stop the rollout"; exit 1; }
```