A portable CLI tool that fetches live cryptocurrency data, computes high-signal market regime metrics, and outputs clean JSON — optimized for AI agents, LLM tool-calling, and MCP workflows.
Grab the latest release for your OS from the Releases page, extract it, and run:
# Linux (amd64)
tar xzf cryptospect-cli_*_linux_amd64.tar.gz
cd cryptospect-cli_*_linux_amd64
./cryptospect-cli list-metrics
# macOS (Apple Silicon)
tar xzf cryptospect-cli_*_darwin_arm64.tar.gz
cd cryptospect-cli_*_darwin_arm64
./cryptospect-cli list-metrics
# Windows (amd64 — PowerShell)
Expand-Archive cryptospect-cli_*_windows_amd64.zip -DestinationPath .
cd cryptospect-cli_*_windows_amd64
.\cryptospect-cli.exe list-metricsSee Install below for build-from-source instructions.
No API keys required — all metrics work on free public tiers. But if you provide a (free) Coingecko api key, it'll work better!
Get the macro picture in one command — no API key needed:
cryptospect-cli market-regime --detail extendedThis returns the structural regime label (Institutional Build, Alt-Season, Flight to Safety, etc.), BTC dominance trend, breadth snapshot, and conviction level. It is always the right first call — everything else is context layered on top of it.
For a complete daily checkup with no prior thesis, run the canonical four-command sequence and feed the output to an LLM:
cryptospect-cli market-regime --detail extended
cryptospect-cli stablecoin-power --detail extended
cryptospect-cli flow-tension --detail extended
cryptospect-cli fear-greed-indexThese four cover the four primary axes: structural regime, available fuel, whether capital is moving and in what direction, and crowd sentiment. See DAILY_BRIEF.md for the full reading guide, including how to assemble a daily brief from the output and how to reason when one or more metrics return status: "degraded".
For scenario-driven analysis — diagnosing a rally, measuring fuel, reading a selloff — see examples.md. Each example shows exact command sequences, interpretation notes, and ready-to-paste LLM prompts.
For signal pattern recognition and synthesis rules — Named Signal Combinations, the signal hierarchy, and per-metric gotchas — see agents.md.
All 10 metrics work without any API key on free public tiers. However, CoinGecko is the primary data source for most metrics, and the free tier is rate-limited. A free CoinGecko Demo API key is strongly recommended for regular use — it relaxes rate limits and unlocks more reliable data on especially the flow-tension metric.
Get a free key at coingecko.com/en/developers, then set it one of three ways:
# Environment variable (recommended for agent/MCP use)
export CRYPTOSPECT_COINGECKO_KEY=your_key_here
# CLI flag (per-call)
cryptospect-cli liquidity-pulse --api-key your_key_here
# Config file (~/.cryptospect.yaml)
apis:
coingecko:
api_key: your_key_hereTen signals, each answering a different question about current market conditions:
| Metric | Alias | What it tells you |
|---|---|---|
liquidity-pulse |
lp |
Is money actively moving, or is the market thin and idle? |
stablecoin-power |
sp |
How much dry powder is sitting on the sidelines? |
flow-tension |
ft |
Are buyers or sellers winning right now? |
market-breadth |
mb |
Is a move broad-based or driven by a handful of large caps? |
momentum-divergence |
md |
Where is capital rotating across large-, mid-, and small-cap tiers? |
market-regime |
mr |
What is the overall market state? Aggregates all signals into a single regime label with a confidence score. |
dominance |
dom |
Is capital rotating into or out of BTC and ETH? |
volatility |
vol |
Are markets calm or turbulent? |
fear-greed-index |
fgi |
What is the current crowd sentiment — fear or greed? |
china-m2 |
cnm2 |
Is China loosening or tightening monetary conditions? |
Good starting point: run market-regime, fgi, and cnm2 together for a macro picture, then drill into individual metrics.
git clone https://github.com/afshinator/cryptospect-cli
cd cryptospect-cli
make build
./bin/cryptospect-cli list-metricsFor build details, Go version requirements, and development setup, see DEVELOPMENT.md.
Every invocation writes exactly one JSON object to stdout. Diagnostic logs go to stderr only. This makes cryptospect-cli easy to wrap as an LLM tool or MCP resource.
Example tool definition for an agentic workflow:
{
"name": "crypto_market_regime",
"description": "Get the current overall crypto market state — regime label, confidence score, and contributing signals",
"parameters": {},
"command": "cryptospect-cli market-regime --detail full --output json"
}Use --detail full when feeding output to an LLM — it includes metric descriptions and thresholds that help the model interpret the data. Use --detail basic (the default) for lightweight agent loops where token economy matters.
See agents.md for the reasoning guide: the universal metric interpretation loop, which metrics to run for a given question, 16 named cross-metric signal patterns to recognize, and rules for turning metric output into grounded answers. See DAILY_BRIEF.md for the canonical cold-start sequence and degraded-data handling.
{
"status": "ok",
"ts": 1744444800,
"results": [
{
"metric": "liquidity-pulse",
"version": "v1.0.0",
"namespace": "cryptospect",
"status": "ok",
"data": { "..." : "..." },
"meta": { "..." : "..." }
}
]
}{
"status": "error",
"ts": 1744444800,
"error": {
"code": 429,
"msg": "rate_limited",
"retry_after_sec": 60,
"source": "coingecko"
}
}| Flag | meta contents |
Best for |
|---|---|---|
--detail basic (default) |
omitted | lightweight agent loops |
--detail extended |
cache hit, TTL remaining, source timestamps | debugging / monitoring |
--detail full |
+ thresholds and metric description | LLM tool input |
Exit code is 0 for both success and handled errors (e.g. degraded data); non-zero only for unrecoverable failures.
cryptospect-cli liquidity-pulse # alias: lp [--detail basic|extended|full]
cryptospect-cli stablecoin-power # alias: sp [--detail basic|extended|full] [--top N]
cryptospect-cli flow-tension # alias: ft [--detail basic|extended|full]
cryptospect-cli market-breadth # alias: mb [--detail basic|extended|full] [--top N]
cryptospect-cli momentum-divergence # alias: md [--detail basic|extended|full] [--segments N]
cryptospect-cli market-regime # alias: mr [--detail basic|extended|full]
cryptospect-cli dominance # alias: dom [--detail basic|extended|full]
cryptospect-cli volatility # alias: vol [--detail basic|extended|full]
cryptospect-cli fear-greed-index # alias: fgi [--detail basic|extended|full]
cryptospect-cli china-m2 # alias: cnm2 [--detail basic|extended|full]
cryptospect-cli list-metrics # list all metrics and aliases
cryptospect-cli cache-clear # clear the local API response cache--output, -o Output format: json (default)
--verbose, -v Enable debug logging on stderr
--detail Detail level: basic (default), extended, full
--api-key CoinGecko API key (per-call override)
--config Config file path (default: ~/.cryptospect.yaml)
The tool caches API responses to disk so that running multiple metrics back-to-back stays fast and rate-limit safe. The cache is shared — a market-regime call reuses the same CoinGecko response that liquidity-pulse fetched moments earlier. Running all ten metrics typically triggers only 3–4 actual API calls.
Cache location: ~/.cryptospect-cli/cache/ (override with cache.dir in config).
cryptospect-cli cache-clear # force fresh data after a market event or key changeIf an API is unreachable and a cached response exists, the tool uses it and reports status: degraded. If there's no cache at all, it reports status: unavailable.
Config file lives at ~/.cryptospect.yaml. Must have permissions 0600 or stricter.
apis:
coingecko:
api_key: "" # or set CRYPTOSPECT_COINGECKO_KEY env var
cache:
enabled: true
dir: "" # default: ~/.cryptospect-cli/cache/
ttl:
coingecko.global_market: 300
binance.spot_cvd_btc_1h: 60
output:
format: json
pretty: false # set true for indented JSON outputKey precedence (highest → lowest): CLI flag --api-key → environment variable → config file.
| Source | Used for |
|---|---|
| CoinGecko (free tier) | Global market, stablecoins, derivatives, coin markets — primary source |
| Binance US (free tier) | Spot CVD klines, hourly volatility candles |
| alternative.me (free tier) | Fear & Greed Index |
| DBnomics (free tier) | China M2 money supply |
| DefiLlama (free tier) | Stablecoin data |
MIT — see LICENSE.