---
title: 'Tutorial: Query Crypto Data from the Terminal'
lastUpdated: '2026-06-06'
byline: founder
nextjs:
  metadata:
    title: CLI Tutorial | Hive Intelligence
    description: Step-by-step guide to using the Hive CLI (hive-intelligence package, hive binary) to explore, query, and automate crypto data from the terminal.
    alternates:
      canonical: https://www.hiveintelligence.xyz/tutorials/cli
---

{% ai-doc-actions path="/tutorials/cli" title="CLI Tutorial" /%}

## What you'll build

A terminal workflow that lists available tools, checks Bitcoin's price, and outputs a daily crypto briefing — all from the command line.

By the end of this tutorial you will be able to:

- Install and authenticate the Hive CLI
- Browse and search the full tool catalog from your terminal
- Call any Hive tool via its domain subcommand
- Pipe JSON output into `jq` for scripting
- Assemble a reusable daily briefing script

---

## Prerequisites

- Node.js 20+ installed
- A Hive Intelligence API key ([get one from the dashboard](/dashboard))
- `jq` installed for JSON filtering (`brew install jq` on macOS, `apt install jq` on Debian/Ubuntu)

---

## Step 1: Install the CLI

The CLI is shipped in the **`hive-intelligence`** npm package — the same package that provides Hive's local MCP stdio wrapper, so installing it once gives you the local terminal and stdio surfaces. The CLI executable inside the package is **`hive`**. Because the package name and the bin name differ, npx needs `-p` to pick the package and then the binary name on its own:

```bash
npx -y -p hive-intelligence@latest hive doctor
```

`hive doctor` is the built-in health check — it verifies Node, network access, and authentication.

For frequent use, install globally so you can drop the `npx …` prefix:

```bash
npm install -g hive-intelligence
```

After a global install, everything below works with a bare `hive`:

```bash
hive doctor
```

> The rest of this tutorial uses the short `hive …` form. If you haven't installed globally, prepend `npx -y -p hive-intelligence@latest` to each command.

---

## Step 2: Authenticate

Two options — pick whichever fits your environment.

### Interactive login (stores the key locally)

```bash
hive auth login
```

The CLI stores the credential so every subsequent command picks it up automatically.

### Environment variable (one-shot or scripted)

```bash
export HIVE_API_KEY=hive_live_…
```

Or per command:

```bash
HIVE_API_KEY=hive_live_… hive status
```

Verify auth either way:

```bash
hive status
```

`status` prints your plan, recent usage, and confirms the credential.

---

## Step 3: Explore available tools

Hive currently exposes 369 callable tools across market data, DeFi, DEX analytics, NFTs, on-chain data, and Hive-native stateful workflows. The CLI lets you browse them without leaving the terminal.

### List all tools

```bash
hive tools list
```

### Search by keyword

```bash
hive tools search price
```

### Inspect a specific tool

```bash
hive tools info get_price
```

Prints the full input schema: required args, optional args, types, and return-value description. Always check `info` before calling a tool for the first time.

---

## Step 4: Make your first call

Domain subcommands are auto-generated from Hive's category namespace, so you get ergonomic flags instead of a generic `call` with a JSON blob. For market prices:

```bash
hive market price --ids bitcoin,ethereum --vs usd
```

You'll see JSON output like:

```json
{
  "bitcoin": { "usd": 84521.0 },
  "ethereum": { "usd": 3412.18 }
}
```

For DeFi TVL:

```bash
hive defi tvl --protocol aave
```

Every `--flag` maps directly to an argument on the underlying tool.

---

## Step 5: Pipe output for scripting

Hive CLI output is designed for shell pipelines. Pipe JSON output into `jq` to extract the exact value you need:

```bash
hive market price --ids bitcoin --vs usd | jq '.bitcoin.usd'
```

Output:

```text
84521.0
```

A few more examples:

```bash
# Ethereum price only
hive market price --ids ethereum --vs usd | jq '.ethereum.usd'

# Name of the top DeFi protocol by TVL
hive defi protocols | jq '.[0].name'

# Count tools matching "defi"
hive tools search defi --format json | jq 'length'
```

---

## Step 6: Build a daily briefing script

Combine several calls into a morning crypto briefing. Create `briefing.sh`:

```bash
#!/bin/bash
set -euo pipefail

echo "=== Daily Crypto Briefing ==="
echo ""
echo "--- Prices ---"
hive market price --ids bitcoin,ethereum,solana --vs usd \
  | jq -r 'to_entries[] | "\(.key): $\(.value.usd)"'

echo ""
echo "--- Top Gainers ---"
hive market gainers --vs usd --duration 24h \
  | jq '.top_gainers[:5]'

echo ""
echo "--- DeFi TVL Leaders ---"
hive defi protocols \
  | jq '.[:5] | .[] | "\(.name): $\(.tvl / 1000000 | floor)M"'
```

Make it executable and run it:

```bash
chmod +x briefing.sh
./briefing.sh
```

Sample output:

```text
=== Daily Crypto Briefing ===

--- Prices ---
bitcoin: $84521
ethereum: $3412.18
solana: $178.92

--- Top Gainers ---
[{ "symbol": "XYZ", "price_change_percentage_24h": 42.1 }]

--- DeFi TVL Leaders ---
Lido: $32451M
AAVE: $18923M
EigenLayer: $15102M
Maker: $9823M
Uniswap: $6421M
```

---

## Comparison with curl

The CLI wraps the Hive REST API. Here's the same `get_price` call with `curl` so you can see what the CLI handles for you:

```bash
curl -X POST https://mcp.hiveintelligence.xyz/api/v1/execute \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_HIVE_API_KEY" \
  -d '{
    "tool": "get_price",
    "args": {
      "ids": "bitcoin,ethereum",
      "vs_currencies": "usd"
    }
  }'
```

And listing tools:

```bash
curl -X GET "https://mcp.hiveintelligence.xyz/api/v1/tools?search=price&limit=10" \
  -H "Authorization: Bearer YOUR_HIVE_API_KEY"
```

The CLI eliminates the boilerplate: no manual headers, no JSON-body construction, no per-request key management. For one-off debugging `curl` is fine; for anything repeated, the CLI is faster and less error-prone.

---

## Tips

- **Use `--format json`** on any command when you plan to pipe the output. It suppresses human-friendly formatting and returns clean JSON.
- **Pipe to `jq`** for filtering, transformation, and pretty-printing.
- **`hive watch`** tails a command on an interval — useful for keeping a price on screen without a custom loop:

  ```bash
  hive watch 'market price --ids bitcoin --vs usd' --interval 30
  ```

- **Combine with `cron`** for scheduled briefings:

  ```bash
  # Run at 8:00 AM every day
  0 8 * * * /path/to/briefing.sh >> /var/log/crypto-briefing.log 2>&1
  ```

- **`hive tools info <tool>`** before calling anything new — it prints the exact arguments and types expected.
- **`hive doctor`** first when anything breaks — it tells you whether the problem is Node, network, auth, or upstream.

---

## Next steps

- [CLI Reference](/cli) — every top-level command and domain namespace
- [MCP Integration Tutorial](/tutorials/mcp-integration) — connect Hive to Claude, Cursor, and supported MCP clients
- [REST API Tutorial](/tutorials/rest-api) — use the HTTP API directly from any language
- [Tools Reference](/tools) — browse the full catalog with schemas and examples