A fast, full-featured terminal interface for the CoinGecko API, built in Go. Includes an interactive TUI with 7-day price charts, CSV export, 50+ currency symbols, 500+ categories, and more than 10 years of historical data.
Note
CoinGecko CLI is currently in Beta. We're constantly improving, and your feedback is crucial. Please share your feedback via this form, or submit a PR.
- 🎮 Interactive TUI — Full-screen terminal dashboard with live navigation and 7-day braille price charts
- ⚡ Real-Time Prices — Current prices by CoinGecko ID or ticker symbol, with 50+ currency symbols
- 📅 Deep Historical Data — Snapshots, OHLC, and custom date ranges with CSV export
- 🏷️ Category Filtering — Filter by 500+ categories including AI, Layer-2, Tokenized Stocks, Gold, and Silver
- 📊 Unlimited Markets — Fetch 1,000+ coins with automatic pagination
- 🔥 Trending & Top Movers — Real-time trending coins, NFTs, and categories
- 📥 CSV Export — Export any market or history query for analysis in Excel or Python
- 📡 Live WebSocket Streaming — Real-time price updates via
cg watchwith NDJSON output for piping - ⌨️ JSON Output — Machine-readable
-o jsonfor scripting and pipelines - 🤖 Agent/LLM Friendly —
--dry-runmode andcg commandsfor tool integration
brew install coingecko/coingecko-cli/cgOr tap first, then install:
brew tap coingecko/coingecko-cli
brew install cgcurl -sSfL https://raw.githubusercontent.com/coingecko/coingecko-cli/main/install.sh | shgo install github.com/coingecko/coingecko-cli@latestDownload the binary for your platform from Releases, extract, and place cg in your $PATH.
Get a free API key at coingecko.com/en/api, then run:
# Interactive setup (recommended — input is masked)
cg auth
# Or via environment variables (avoids shell history exposure)
CG_API_KEY=YOUR_API_KEY CG_API_TIER=demo cg auth
# Or with flags (note: key may be visible in shell history and process listings)
cg auth --key YOUR_API_KEY --tier demoTiers: demo (free, public API), paid (pro API with full historical data and extra endpoints)
# Verify configuration
cg status# JSON output (for scripting and automation)
cg price --ids bitcoin -o json
cg markets --total 10 -o json | jq '.[0].name'
# Dry-run mode (shows the API request without executing it)
cg price --ids bitcoin --dry-runAll data commands support -o json / --output json for machine-readable output. Diagnostics and warnings are written to stderr, so stdout is always clean data.
Fetch the current price of one or more coins. Supports both CoinGecko IDs and ticker symbols.
Tip: Find coin IDs by browsing the respective CoinGecko coin page and copying the 'API ID'. You can also get the full list of coin IDs via this endpoint or Google Sheet.
# By CoinGecko ID
cg price --ids bitcoin,ethereum
# By ticker symbol (for coins that share the same symbol, the coin with highest market cap will be prioritised)
cg price --symbols btc,eth
# Different target currency
cg price --ids bitcoin --vs eurFor --vs currency, refer below for the full supported currency IDs. By default, it will always lookup by usd
| IDs | Currency Name | Type |
|---|---|---|
usd |
US Dollar | Fiat |
eur |
Euro | Fiat |
eth |
Ether | Crypto |
xau |
Gold - Troy Ounce | Commodity |
Click to see full list of supported IDs
| IDs | Currency Name | Type |
|---|---|---|
bch |
Bitcoin Cash | Crypto |
bnb |
Binance Coin | Crypto |
eos |
EOS | Crypto |
xrp |
XRP | Crypto |
xlm |
Stellar | Crypto |
link |
Chainlink | Crypto |
dot |
Polkadot | Crypto |
yfi |
yearn.finance | Crypto |
sol |
Solana | Crypto |
usd |
US Dollar | Fiat |
aed |
UAE Dirham | Fiat |
ars |
Argentine Peso | Fiat |
aud |
Australian Dollar | Fiat |
bdt |
Bangladeshi Taka | Fiat |
bhd |
Bahraini Dinar | Fiat |
bmd |
Bermudian Dollar | Fiat |
brl |
Brazil Real | Fiat |
cad |
Canadian Dollar | Fiat |
chf |
Swiss Franc | Fiat |
clp |
Chilean Peso | Fiat |
cny |
Chinese Yuan | Fiat |
czk |
Czech Koruna | Fiat |
dkk |
Danish Krone | Fiat |
eur |
Euro | Fiat |
gbp |
British Pound Sterling | Fiat |
gel |
Georgian Lari | Fiat |
hkd |
Hong Kong Dollar | Fiat |
huf |
Hungarian Forint | Fiat |
idr |
Indonesian Rupiah | Fiat |
ils |
Israeli New Shekel | Fiat |
inr |
Indian Rupee | Fiat |
jpy |
Japanese Yen | Fiat |
krw |
South Korean Won | Fiat |
kwd |
Kuwaiti Dinar | Fiat |
lkr |
Sri Lankan Rupee | Fiat |
mmk |
Burmese Kyat | Fiat |
mxn |
Mexican Peso | Fiat |
myr |
Malaysian Ringgit | Fiat |
ngn |
Nigerian Naira | Fiat |
nok |
Norwegian Krone | Fiat |
nzd |
New Zealand Dollar | Fiat |
php |
Philippine Peso | Fiat |
pkr |
Pakistani Rupee | Fiat |
pln |
Polish Zloty | Fiat |
rub |
Russian Ruble | Fiat |
sar |
Saudi Riyal | Fiat |
sek |
Swedish Krona | Fiat |
sgd |
Singapore Dollar | Fiat |
thb |
Thai Baht | Fiat |
try |
Turkish Lira | Fiat |
twd |
New Taiwan Dollar | Fiat |
uah |
Ukrainian Hryvnia | Fiat |
vef |
Venezuelan Bolívar Fuerte | Fiat |
vnd |
Vietnamese Dong | Fiat |
zar |
South African Rand | Fiat |
xdr |
IMF Special Drawing Rights | Other |
xag |
Silver - Troy Ounce | Commodity |
xau |
Gold - Troy Ounce | Commodity |
bits |
Bits (Bitcoin) | Unit |
sats |
Satoshis (Bitcoin) | Unit |
Output columns: Coin | Price | 24h Change
Fetch ranked market data with automatic pagination. The API is queried in 250-coin pages, so --total 1000 makes exactly 4 API calls.
cg markets
cg markets --total 100
cg markets --total 500 --vs eur
cg markets --total 250 --order gecko_desc
cg markets --total 250 --export data.csv| Flag | Default | Description |
|---|---|---|
--total |
100 |
Number of coins to fetch |
--vs |
usd |
Quote currency |
--order |
market_cap_desc |
Sort order (e.g. volume_desc, gecko_desc) |
--category |
— | Filter by category ID (e.g. layer-2, decentralized-finance-defi) |
--export |
— | Export to CSV file path |
Output columns: # | Name | Symbol | Price | Market Cap | Volume | 24h Change
Search for any coin by name or symbol. Returns the top matches with their CoinGecko coin IDs.
cg search solana
cg search dog --limit 5| Flag | Default | Description |
|---|---|---|
--limit |
10 |
Max results to show |
Output columns: Rank | Name | Symbol | ID
Shows the three trending tables in one view:
cg trending- Top 15 trending coins — with market cap rank
- Top 7 trending NFTs — with floor price change
- Top 6 trending categories — with market cap change
Three modes for querying historical data. All modes support --vs currency and --export.
Single date snapshot:
cg history bitcoin --date 2024-01-15
cg history ethereum --date 2024-06-01 --vs eurPast N days (price data):
cg history bitcoin --days 7
cg history bitcoin --days 30 --export btc_30d.csv
cg history bitcoin --days 7 --ohlc # OHLC candle data insteadCustom date range:
cg history bitcoin --from 2024-01-01 --to 2024-06-30
cg history bitcoin --from 2024-01-01 --to 2024-03-31 --export q1.csv
cg history bitcoin --from 2024-01-01 --to 2024-06-30 --ohlc # OHLC output| Flag | Description |
|---|---|
--date YYYY-MM-DD |
Single-day snapshot (price, market cap, volume) |
--days N |
Past N days of price data (any integer, or max) |
--from / --to YYYY-MM-DD |
Inclusive date range (price data) |
--ohlc |
Switch --days or --from/--to to OHLC output |
--vs |
Quote currency (default: usd) |
--interval |
Data granularity: daily, hourly, or 5m |
--export |
Export to CSV file path |
Note: hourly and 5m interval data are only available from February 2, 2018 onwards. 5m interval is exclusive for Enterprise plan only.
cg top-gainers-losers — Top Movers (Exclusive for Analyst plan & above)
cg top-gainers-losers
cg top-gainers-losers --losers --duration 7d
cg top-gainers-losers --top-coins 300 --export gainers.csv| Flag | Default | Description |
|---|---|---|
--vs |
usd |
Quote currency |
--duration |
24h |
Time window (1h, 24h, 7d, 14d, 30d, 60d, 1y) |
--top-coins |
1000 |
Pool size (300, 500, 1000, all) |
--losers |
false |
Show losers instead of gainers |
--export |
— | Export to CSV file path |
cg watch — Live Price Streaming (Exclusive for Analyst plan & above)
Stream real-time price updates via CoinGecko's WebSocket API. USD prices only.
cg watch --ids bitcoin,ethereum # Live updating table
cg watch --symbols btc,eth # Resolve symbols, then stream
cg watch --ids bitcoin -o json # NDJSON output (pipe-friendly)
cg watch --ids bitcoin -o json | jq .price # Stream prices with jq
cg watch --ids bitcoin --dry-run # Show WebSocket request info| Flag | Default | Description |
|---|---|---|
--ids |
— | Comma-separated coin IDs |
--symbols |
— | Comma-separated symbols (resolved to IDs) |
Table mode (default): clears screen and re-renders on each update. Press Ctrl+C to quit.
JSON mode (-o json): one JSON object per line per update to stdout. Exits cleanly on broken pipe.
CoinGecko tracks 500+ categories including Real World Assets, commodities, and tokenized stocks. Use the --category flag to filter:
cg markets --category tokenized-gold # Gold & Silver pegged assets
cg markets --category real-world-assets-rwa # Real Estate & T-Bills
cg markets --category artificial-intelligence # Top AI coins
cg markets --category layer-2 --export l2.csv # Export all L2 tokens
cg tui markets --category solana-meme-coins # Browse in TUI modeThe --category flag works in both cg markets and cg tui markets. In TUI mode, the active category is displayed in the header.
Tip: Find category IDs by browsing the CoinGecko categories page and copying the ID from the URL. You can also get the full list via this endpoint or Google Sheet.
markets and history commands can export raw data to CSV for analysis in Excel, Python, etc.
cg markets --total 500 --export top500.csv
cg history bitcoin --days 30 --export btc_30d.csv
cg history bitcoin --from 2024-01-01 --to 2024-12-31 --export btc_2024.csv
cg top-gainers-losers --export gainers.csvCSV files contain raw numbers (not formatted strings), making them directly usable in data pipelines.
cg tui markets
cg tui markets --category layer-1Launches a live interactive table of the top 50 coins by market cap.
cg tui trendingLaunches a live interactive table of the top 15 trending coins (up to 30 on paid plans).
| Key | Action |
|---|---|
j / ↓ |
Move selection down |
k / ↑ |
Move selection up |
Enter |
Open detail view |
Esc / Backspace |
Back to list |
q / Ctrl+C |
Quit |
Pressing Enter on any coin opens a split-panel detail view:
Left panel — Key metrics: price, 24h change, high/low, market cap, volume, ATH/ATL, circulating and total supply.
Right panel — 7-day price chart rendered as a braille-dot line graph in the terminal.
cg [command]
Commands:
auth Save your CoinGecko API key and tier (demo/paid)
status Show current auth configuration
price Get the current price of one or more coins
markets List top coins by market cap
search Search for coins by name or symbol
trending Show trending coins, NFTs, and categories (24h)
history Get historical price data for a coin
top-gainers-losers Show top gaining and losing coins (paid plans only)
watch Stream live coin prices via WebSocket (analyst or above)
tui Interactive terminal UI (markets, trending)
commands List all commands with API metadata (for agents/LLMs)
help Print help for a command
Global Flags:
-o, --output string Output format: table, json (default "table")
--dry-run Show the API request without executing it
-h, --help Print help
-v, --version Print version
For per-command help:
cg price --help
cg markets --help
cg history --help# Build
make build
# Test
make test
# Lint (requires golangci-lint)
make lint| Package | Purpose |
|---|---|
| cobra | CLI framework and command routing |
| viper | Configuration management |
| bubbletea | Interactive TUI framework |
| lipgloss | Terminal styling and layout |
| huh | Interactive auth prompts |
| ntcharts | Braille terminal charts |
| gorilla/websocket | WebSocket client for live price streaming |
| goreleaser | Cross-platform release builds |
MIT — see LICENSE.