> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chainbase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Command-line interface for querying Web3 data, designed for both developers and AI agents

## Overview

The **Chainbase CLI** is a command-line tool for accessing [Chainbase Web3 API](/api-reference/overview) data directly from your terminal. It outputs JSON by default, making it ideal for scripting, automation, and AI agent integration.

* Query tokens, balances, transactions, and more across 8+ EVM chains
* JSON output by default for machine-parseable results
* Async SQL queries against Chainbase's on-chain data warehouse
* Smart contract read calls without writing code

## Installation

```bash theme={null}
# Global install
npm install -g chainbase-cli

# Or run directly with npx (no install needed)
npx chainbase-cli --help
```

<Note>
  Requires Node.js >= 18.
</Note>

## Configuration

### Set API Key

Get your API key from the [Chainbase Console](https://console.chainbase.com/), then configure:

```bash theme={null}
# Option 1: Save to config file (~/.chainbase/config.json)
chainbase config set api-key YOUR_API_KEY

# Option 2: Use environment variable
export CHAINBASE_API_KEY=YOUR_API_KEY
```

### Set Default Chain

```bash theme={null}
# Set default chain to Ethereum (default)
chainbase config set default-chain 1

# View current config
chainbase config list
```

### Supported Chains

Supports all EVM-compatible chains available on Chainbase. See the full list at [Supported Networks](/resources/platform/supported-networks/supported-networks).

## Global Options

Every command supports these options:

| Option         | Description                       | Default                       |
| -------------- | --------------------------------- | ----------------------------- |
| `--chain <id>` | Chain ID to query                 | `1` (or your `default-chain`) |
| `--pretty`     | Human-readable formatted output   | `false`                       |
| `--page <n>`   | Page number for paginated results | `1`                           |
| `--limit <n>`  | Results per page                  | `20`                          |

## Commands

### `block` — Block Queries

```bash theme={null}
# Get latest block number
chainbase block latest

# Get block details
chainbase block detail 17000000
```

### `tx` — Transaction Queries

```bash theme={null}
# Get transaction by hash
chainbase tx detail 0x...

# List transactions for an address
chainbase tx list 0x... --from-block 17000000 --to-block 17001000
```

### `token` — Token Queries

```bash theme={null}
# Get token metadata
chainbase token metadata 0xdAC17F958D2ee523a2206206994597C13D831ec7

# Get current price
chainbase token price 0xdAC17F958D2ee523a2206206994597C13D831ec7

# Get price history
chainbase token price-history 0xdAC17F958D2ee523a2206206994597C13D831ec7 \
  --from 1700000000 --to 1700086400

# Get top holders
chainbase token top-holders 0xdAC17F958D2ee523a2206206994597C13D831ec7

# Get token transfers
chainbase token transfers --contract 0x... --from-block 17000000
```

### `balance` — Balance & Portfolio

```bash theme={null}
# Native token balance (ETH, BNB, etc.)
chainbase balance native 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

# ERC-20 token balances
chainbase balance tokens 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
```

### `domain` — ENS & Space ID

```bash theme={null}
# Get ENS domains held by address
chainbase domain ens 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

# Resolve ENS domain to address
chainbase domain ens-resolve vitalik.eth

# Reverse resolve address to ENS
chainbase domain ens-reverse 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

# Space ID (BSC) resolution
chainbase domain spaceid-resolve example.bnb
chainbase domain spaceid-reverse 0x...
```

### `address` — Address Labels

```bash theme={null}
# Get labels for an address (exchange, whale, contract, etc.)
chainbase address labels 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
```

### `contract` — Smart Contract Calls

```bash theme={null}
# Call a contract read function
chainbase contract call \
  --address 0xdAC17F958D2ee523a2206206994597C13D831ec7 \
  --function "balanceOf" \
  --abi '[{"inputs":[{"name":"account","type":"address"}],"name":"balanceOf","outputs":[{"name":"","type":"uint256"}],"type":"function"}]' \
  --params '["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"]'
```

### `sql` — SQL Queries

Execute SQL queries against Chainbase's on-chain data warehouse. Queries run asynchronously — submit, check status, then retrieve results.

```bash theme={null}
# Execute a query
chainbase sql execute "SELECT * FROM ethereum.blocks LIMIT 5"

# Check execution status
chainbase sql status <execution_id>

# Get results
chainbase sql results <execution_id>
```

### `tops` — Crypto Social Intelligence

Query crypto social signals from [Tops](https://tops.chainbase.com). **No API key required.** Free to use.

**Rate limits:** 10 req/s · 60 req/min · 600 req/hour (per client IP)

```bash theme={null}
# List trending crypto topics (default: English)
chainbase tops trending
chainbase tops trending --language zh   # Chinese
chainbase tops trending --language ko   # Korean

# Get structured details for a topic
chainbase tops topic <topic_id>

# Get Twitter/X posts under a topic
chainbase tops posts <topic_id>

# Search narrative candidate topics by keyword
chainbase tops search "RWA"
chainbase tops search "AI Agent"

# Search recent Twitter/X mentions
chainbase tops mentions "Ethereum ETF"
```

| Subcommand                     | Description                                                           |
| ------------------------------ | --------------------------------------------------------------------- |
| `trending [--language <lang>]` | List trending crypto narratives ranked by heat score (`zh`/`en`/`ko`) |
| `topic <topic_id>`             | Structured details (summary, score, representative posts) for a topic |
| `posts <topic_id>`             | Raw Twitter/X posts under a topic                                     |
| `search <keyword>`             | Find narrative candidate topics by keyword                            |
| `mentions <keyword>`           | Search recent Twitter/X mentions for a keyword                        |

The `topic_id` values come from `trending` or `search` results. Use `--json` to get machine-parseable output when piping into other tools.

## AI Agent Integration

The CLI is designed for AI agent automation with predictable, machine-parseable output:

* **JSON by default** — no colors or formatting unless `--pretty` is used
* **Consistent error format** — errors output as `{"error":"message"}` to stderr
* **Discoverable** — run `--help` on any command for usage info
* **Predictable pattern** — `chainbase <group> <action> [args] [options]`

```bash theme={null}
# Parse output with jq
PRICE=$(chainbase token price 0xdAC17F958D2ee523a2206206994597C13D831ec7 | jq '.data.price')

# Use in scripts
if chainbase balance native 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 2>/dev/null; then
  echo "Query succeeded"
fi
```

## Learn More

* [Chainbase API Reference](/api-reference/overview) — Full API documentation
* [Supported Networks](/resources/platform/supported-networks/supported-networks) — Complete list of supported chains
* [GitHub Repository](https://github.com/chainbase-labs/cli) — Source code and contributions
* [npm Package](https://www.npmjs.com/package/chainbase-cli) — Package details and versions