cg — CoinGecko CLI

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.

Features at a Glance

• 🎮 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 watch with NDJSON output for piping
• ⌨️ JSON Output — Machine-readable -o json for scripting and pipelines
• 🤖 Agent/LLM Friendly — --dry-run mode and cg commands for tool integration

---

Install

Homebrew (macOS/Linux)

brew install coingecko/coingecko-cli/cg

Or tap first, then install:

brew tap coingecko/coingecko-cli
brew install cg

npm

npm install -g @coingecko/cg

Works on macOS, Linux, and Windows (x64 and arm64). Requires Node.js >= 20. The right native binary for your platform is fetched via npm optionalDependencies; no build step.

Shell script

curl -sSfL https://raw.githubusercontent.com/coingecko/coingecko-cli/main/install.sh | sh

Go install

go install github.com/coingecko/coingecko-cli@latest

This installs a binary named coingecko-cli (matching the module path). To use it as cg, add an alias to your shell rc:

alias cg=coingecko-cli

Or symlink it onto your $PATH:

ln -s "$(go env GOBIN 2>/dev/null ||echo"$(go env GOPATH)/bin")/coingecko-cli" /usr/local/bin/cg

Manual

Download the binary for your platform from Releases, extract, and place cg in your $PATH.

---

Setup

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 demo

Tiers: demo (free, public API), paid (pro API with full historical data and extra endpoints)

# Verify configuration
cg status

---

Global Flags

# 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-run

All data commands support -o json / --output json for machine-readable output. Diagnostics and warnings are written to stderr, so stdout is always clean data.

---

Commands

cg price — Live Coin Prices

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 eur

Supported Currencies

For --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

---

cg markets — Top Coins by Market Cap

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

---

cg search — Search Coins

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

---

cg trending — Trending (24h)

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

---

cg history — Historical Price Data

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 eur

Past 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 instead

Custom 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.

---

cg update — Upgrade the CLI

Check for a new version and upgrade in one step. Auto-detects whether you installed via Homebrew, npm, go install, or the install script, and hands off to the right tool.

cg update
# Override install method if auto-detection gets it wrong
cg update --method homebrew # or: npm, go, script

The CLI also checks for updates on launch (cached 24h) and shows a reminder if you're behind. Set CG_NO_UPDATE_CHECK=1 to disable this in CI.

---

Category Filtering

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 mode

The --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.

---

CSV Export

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.csv

CSV files contain raw numbers (not formatted strings), making them directly usable in data pipelines.

---

Interactive TUI

cg tui markets — Top Market Cap Ranked Coins

cg tui markets
cg tui markets --category layer-1

Launches a live interactive table of the top 50 coins by market cap.

cg tui trending — Trending Coins

cg tui trending

Launches a live interactive table of the top 15 trending coins (up to 30 on paid plans).

Keyboard Controls

Key	Action
j / ↓	Move selection down
k / ↑	Move selection up
Enter	Open detail view
Esc / Backspace	Back to list
q / Ctrl+C	Quit

Detail View

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.

---

Full Command Reference

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)
update Upgrade the CLI to the latest version
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

---

Development

# Build
make build
# Test
make test# Lint (requires golangci-lint)
make lint

Tech Stack

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

License

MIT — see LICENSE.