# CoinMarketCap CLI

Use the CoinMarketCap CLI when you want stable, shell-native access to CoinMarketCap data for scripts, automation, and terminal workflows.

## When to use CMC CLI

- Choose **CMC CLI** when you want terminal-native workflows, machine-readable output, CSV export, and repeatable commands that fit well into shell scripts or agent runs.

## Prerequisites

- A CoinMarketCap API key from [pro.coinmarketcap.com](https://pro.coinmarketcap.com/login)
- A supported install path such as Homebrew or the shell installer
- Optional: `jq` if you want to inspect JSON examples in the terminal

## Install and authenticate

1. **Install CMC CLI**

   Use the install path that best fits your environment:

   ```bash
   brew install coinmarketcap-official/CoinMarketCap-CLI/cmc
   ```

   Or use the shell installer:

   ```bash
   curl -sSfL https://raw.githubusercontent.com/coinmarketcap-official/CoinMarketCap-CLI/main/install.sh | sh
   ```

1. **Authenticate**

   The simplest path is interactive auth:

   ```bash
   cmc auth
   ```

   For automation or ephemeral environments, you can also use environment variables:

   ```bash
   CMC_API_KEY=your-key cmc price --id 1 -o json
   ```

1. **Verify the setup**

   Check the active config and then fetch a live quote:

   ```bash
   cmc status -o json
   cmc price --id 1 -o json
   ```

## Quick start

Use these commands to see the CLI value quickly:

```bash
cmc resolve --id 1
cmc price --id 1 --with-info --with-chain-stats -o json
cmc search --chain ethereum --address 0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2
cmc history --id 1 --days 30 --dry-run -o json
```

## What you can do

| Need | Use | Notes |
|---|---|---|
| Exact asset lookup | `resolve` | Prefer `--id` or `--slug` when determinism matters. |
| Quotes and enrichments | `price` | Add `--with-info` or `--with-chain-stats` when you need more context. |
| Search and discovery | `search` | Works for name, symbol, and chain-scoped address discovery. |
| Market scans | `markets`, `metrics`, `pairs` | Good for list views, rankings, and broader market context. |
| Time series | `history` | Supports daily plus selected paid-plan intervals. |
| Trends and content | `trending`, `top-gainers-losers`, `news` | Useful for narratives, movers, and recent coverage. |
| Live monitoring | `monitor` | Polling only, not websocket streaming. |
| Interactive inspection | `tui` | Built for human terminal workflows rather than scripting. |

## Output and automation

- Most data commands default to compact JSON.
- Use `-o table` when you want human-readable terminal output.
- Use `--dry-run` on data commands to preview the upstream request without sending it.
- Selected commands support CSV export when you want a file artifact instead of JSON.
- For deterministic automation, resolve once and reuse canonical IDs downstream.

```bash
cmc price --id 1 --dry-run -o json > price.json 2> price.log
cmc markets --limit 100 --export top100.csv
```

## Interactive terminal workflows

The CLI also supports terminal-native monitoring and TUI flows:

```bash
cmc monitor --id 1,1027 --interval 60s
cmc tui
```

Use these for live human inspection. For scripts, automation, or agent runs, prefer the non-interactive data commands.

## Notes

- Prefer explicit IDs or slugs over shorthand symbols in high-trust workflows.
- Historical hourly and 5-minute intervals may require a paid CoinMarketCap plan.
- `monitor` is polling-based, not streaming.

## Source

- GitHub: [coinmarketcap-official/CoinMarketCap-CLI](https://github.com/coinmarketcap-official/CoinMarketCap-CLI)