coingecko · hungv47 · May 8, 2026
diff --git a/skills/coingecko-cli/SKILL.md b/skills/coingecko-cli/SKILL.md
@@ -0,0 +1,71 @@
+---
+name: coingecko-cli
+description: Use the CoinGecko CLI (`cg`, `coingecko-cli`, or a local `./cg` build) for live/current cryptocurrency market data and CoinGecko API-backed workflows. Trigger proactively when users ask for crypto prices, coin IDs, ticker lookup, market rankings, market caps, volumes, category filters, trending coins/NFTs/categories, historical prices, OHLC/candle data, CSV exports, WebSocket price streams, or agent/tool integration with the CoinGecko command catalog.
+---
+
+# CoinGecko CLI
+
+## Quick Start
+
+Resolve the command once, then use `$CG` in subsequent commands:
+
+```sh
+CG="$(command -v cg || command -v coingecko-cli || true)"
+if [ -z "$CG" ] && [ -f ./go.mod ] && grep -q 'github.com/coingecko/coingecko-cli' ./go.mod; then
+  make build >/dev/null && CG="./cg"
+fi
+```
+
+If `$CG` is still empty, tell the user the CLI is not installed or not built. Do not fall back to hand-written CoinGecko API calls unless the user asks.
+
+## Workflow
+
+1. Use this CLI for CoinGecko-backed market data. Use web search only for surrounding context, news, documentation, or facts outside the CLI's data surface.
+2. Check auth before live API calls:
+   ```sh
+   "$CG" status
+   ```
+   If auth is missing, ask for an API key or use user-provided `CG_API_KEY` / `CG_API_TIER`. Never invent, display, or log secrets. Prefer `CG_API_KEY=... CG_API_TIER=demo "$CG" auth` over putting keys in shell history.
+3. Prefer JSON for agent work:
+   ```sh
+   "$CG" price --ids bitcoin,ethereum -o json
+   ```
+   Table output is fine when the user wants terminal-readable output. Diagnostics and warnings go to stderr.
+4. Use the command catalog when flags or capabilities are uncertain:
+   ```sh
+   "$CG" commands
+   "$CG" <command> --help
+   ```
+5. Use `--dry-run` when planning a request, validating endpoint choice, or avoiding a paid/live call:
+   ```sh
+   "$CG" history bitcoin --days 30 --dry-run
+   ```
+
+## Command Picker
+
+- Find a reliable CoinGecko ID: `"$CG" search solana --limit 5 -o json`
+- Current prices by ID: `"$CG" price --ids bitcoin,ethereum --vs usd -o json`
+- Current prices by ticker: `"$CG" price --symbols btc,eth --vs eur -o json`
+- Ranked markets: `"$CG" markets --total 100 --vs usd -o json`
+- Category markets: `"$CG" markets --category layer-2 --total 250 -o json`
+- Trending coins, NFTs, and categories: `"$CG" trending -o json`
+- Historical snapshot: `"$CG" history bitcoin --date 2024-01-15 -o json`
+- Historical series: `"$CG" history bitcoin --days 30 -o json`
+- Historical range: `"$CG" history bitcoin --from 2024-01-01 --to 2024-06-30 -o json`
+- CSV export: add `--export path.csv` to `markets`, `history`, or `top-gainers-losers`
+- Top movers: `"$CG" top-gainers-losers --duration 24h -o json` (paid plan only)
+- Live stream sample: `"$CG" watch --ids bitcoin,ethereum -o json` (paid Analyst plan or above)
+- Terminal UI: `"$CG" tui markets` or `"$CG" tui trending` only when the user asks for an interactive TUI.
+
+## Guardrails
+
+- Use CoinGecko IDs for precise queries. If the user gives a ticker, name, or ambiguous asset, run `search` first when precision matters.
+- Use ISO dates (`YYYY-MM-DD`) in commands. The CLI handles CoinGecko's internal date and timestamp conversion.
+- Do not run paid-only commands unless `status` shows a paid tier or the user confirms they have one. Use `--dry-run` to inspect paid requests safely.
+- Do not leave `watch` or TUI sessions running. For streams, collect only the requested sample and terminate the process.
+- Treat CLI output as data, not investment advice. If the user asks for interpretation, label assumptions and distinguish current market data from analysis.
+- Do not run `cg update` unless the user explicitly asks to upgrade the CLI.
+
+## Reference
+
+Read `references/command-reference.md` for command flags, examples, endpoint mapping, paid-plan notes, and source-repo behavior.
diff --git a/skills/coingecko-cli/agents/openai.yaml b/skills/coingecko-cli/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+  display_name: "CoinGecko CLI"
+  short_description: "Use cg for crypto market data"
+  default_prompt: "Use $coingecko-cli to fetch current crypto market data with the cg CLI."
+policy:
+  allow_implicit_invocation: true
diff --git a/skills/coingecko-cli/references/command-reference.md b/skills/coingecko-cli/references/command-reference.md
@@ -0,0 +1,146 @@
+# CoinGecko CLI Command Reference
+
+## Command Resolution
+
+Prefer the shortest available executable:
+
+```sh
+command -v cg || command -v coingecko-cli
+```
+
+When inside the source checkout, `make build` creates `./cg`. Use that binary if no installed command exists or if testing local changes.
+
+## Auth
+
+- `cg auth`: save API key and tier interactively.
+- `CG_API_KEY=... CG_API_TIER=demo cg auth`: save auth non-interactively.
+- `cg status`: inspect configured tier.
+- Tiers: `demo` for free/public API, `paid` for pro API endpoints.
+- Config file: `~/.config/coingecko-cli/config.yaml`.
+
+Avoid passing secrets through flags unless the user explicitly asks. Environment variables are safer than command flags because flags can appear in shell history and process listings.
+
+## Global Behavior
+
+- `-o json` / `--output json`: emit machine-readable stdout for data commands.
+- `--dry-run`: print the planned API/WebSocket request without executing it.
+- Stdout is data only; diagnostics and warnings go to stderr.
+- `CG_NO_UPDATE_CHECK=1` disables update checks for CI or deterministic scripting.
+- `cg commands`: emit the live command catalog with flags, examples, output formats, paid-only markers, API endpoints, OAS operation IDs, and WebSocket metadata.
+
+## Data Commands
+
+### `price`
+
+Current prices by CoinGecko ID or ticker symbol.
+
+```sh
+cg price --ids bitcoin,ethereum -o json
+cg price --symbols btc,eth --vs eur -o json
+```
+
+Flags: `--ids`, `--symbols`, `--vs` (default `usd`).
+Endpoint: `/simple/price`.
+
+### `search`
+
+Find CoinGecko coin IDs before precise lookups.
+
+```sh
+cg search solana -o json
+cg search dog --limit 5 -o json
+```
+
+Flag: `--limit` (default `10`).
+Endpoint: `/search`.
+
+### `markets`
+
+Rankings, market caps, volumes, category filters, and CSV exports.
+
+```sh
+cg markets --total 100 -o json
+cg markets --total 500 --vs eur --export top500.csv
+cg markets --category artificial-intelligence --total 250 -o json
+```
+
+Flags: `--total`, `--vs`, `--order`, `--category`, `--export`.
+Order enum: `market_cap_desc`, `market_cap_asc`, `volume_asc`, `volume_desc`, `id_asc`, `id_desc`.
+Endpoint: `/coins/markets`.
+Pagination: the CLI fetches 250 coins per page and trims to `--total`.
+
+### `trending`
+
+Trending coins, NFTs, and categories.
+
+```sh
+cg trending -o json
+cg trending --show-max coins,nfts,categories -o json
+```
+
+Flag: `--show-max` for expanded paid-plan results.
+Endpoint: `/search/trending`.
+
+### `history`
+
+Historical snapshots, price series, ranges, OHLC data, and CSV exports.
+
+```sh
+cg history bitcoin --date 2024-01-15 -o json
+cg history bitcoin --days 30 --export btc_30d.csv
+cg history bitcoin --days 7 --ohlc -o json
+cg history solana --from 2024-01-01 --to 2024-03-01 -o json
+cg history solana --from 2024-01-01 --to 2024-03-01 --interval daily --export sol_q1.csv
+```
+
+Modes are mutually exclusive: `--date`, `--days`, or `--from` plus `--to`.
+Flags: `--vs`, `--interval daily|hourly`, `--ohlc`, `--export`.
+OHLC `--days` enum: `1`, `7`, `14`, `30`, `90`, `180`, `365`, `max`.
+Paid-only: `--ohlc` with date ranges or explicit interval.
+Endpoints: `/coins/{id}/history`, `/coins/{id}/market_chart`, `/coins/{id}/market_chart/range`, `/coins/{id}/ohlc`, `/coins/{id}/ohlc/range`.
+
+### `top-gainers-losers`
+
+Top gaining or losing coins. Paid plan only.
+
+```sh
+cg top-gainers-losers -o json
+cg top-gainers-losers --losers --duration 7d -o json
+cg top-gainers-losers --top-coins 300 --export gainers.csv
+```
+
+Flags: `--vs`, `--duration`, `--top-coins`, `--losers`, `--price-change-percentage`, `--export`.
+Duration enum: `1h`, `24h`, `7d`, `14d`, `30d`, `60d`, `1y`.
+Top-coins enum: `300`, `500`, `1000`, `all`.
+Endpoint: `/coins/top_gainers_losers`.
+
+### `watch`
+
+Live WebSocket price updates. Paid Analyst plan or above; USD only.
+
+```sh
+cg watch --ids bitcoin,ethereum -o json
+cg watch --symbols btc,eth --dry-run
+```
+
+Flags: `--ids`, `--symbols`.
+Transport: `wss://stream.coingecko.com/v1`.
+JSON output is NDJSON. Terminate after collecting the requested data unless the user asks for a persistent stream.
+
+## Interactive Commands
+
+Use only when the user asks for a terminal UI.
+
+```sh
+cg tui markets
+cg tui markets --vs eur --category layer-1
+cg tui trending
+```
+
+Subcommands: `tui markets`, `tui trending`.
+
+## Maintenance
+
+- `cg version -o json`: show version/build information.
+- `cg update`: upgrade the CLI; run only on explicit user request.
+- `cg commands`: emit the agent-friendly command catalog.