---
title: 'Tutorial: Query crypto data from the terminal'
lastUpdated: '2026-06-22'
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 375 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