Metadata-Version: 2.4
Name: n0brains-cli
Version: 1.3.0
Summary: Token-efficient CLI for the n0brains crypto intelligence API — built for trading agents.
Author: n0brains
License: MIT
Project-URL: Homepage, https://n0brains.com
Project-URL: API, https://api.n0brains.com
Keywords: crypto,trading,signals,agent,intelligence,mcp
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: stream
Requires-Dist: websockets>=12.0; extra == "stream"

# n0brains CLI

Token-efficient command-line access to the [n0brains](https://n0brains.com) crypto
intelligence API — built for trading agents, scripts, and humans. Every command
prints raw JSON to stdout, so it composes with `jq`, pipes into an LLM, or feeds a
bot directly. Zero third-party dependencies (Python 3.8+ stdlib only); the optional
`stream` command needs `websockets`.

## Why a CLI (vs the MCP server)

n0brains also ships an [MCP server](https://api.n0brains.com/mcp) for Claude /
Cursor / Cline. The CLI is the better fit when you're driving a **bot or shell
pipeline**: plain JSON with no protocol envelope is more token-efficient, it
composes with Unix tools, and it runs anywhere `curl` does. Same data, both
surfaces.

## Install

```bash
pip install n0brains-cli          # once published
# or run the single file directly:
python3 n0brains_cli.py --help
```

## Auth

```bash
export N0BRAINS_API_KEY=intel_sk_...   # get one at https://n0brains.com
# or pass --api-key on any command. Public endpoints (proof) work without a key.
```

## Commands

| Command | What it returns |
|---|---|
| `signals [--proven-only] [--asset BTC] [--type hack] [--limit N]` | Active classified signals |
| `signal <id>` | One signal with full context |
| `similar <query>` | Semantic similarity search (pro) |
| `levels <coin>` | Support/resistance levels |
| `liquidation-map <coin>` | Estimated liquidation-cluster zones |
| `correlation [coin] [--vs BTC] [--coins BTC,ETH,SOL]` | Correlation matrix or one coin's corr+beta |
| `rotation` | Altseason/rotation read (into_alts / into_btc / neutral) |
| `macro` | Daily BTC/ETH macro bias |
| `narrative <coin>` | Narrative context |
| `trust <coin>` | Trust/rug score |
| `manipulation <coin>` | Manipulation score |
| `proof [--equity]` | Live forward-return proof per signal type (+ equity curve) |
| `performance [--days 30] [--tier N]` | Backtest stats |
| `plan <coin>` | Assembled trade plan — direction, entry, strongest target, stop, R:R, options context + warnings (pro) |
| `rank [--coins BTC,ETH,SOL]` | Cross-asset ranking — which coin is the best trade now (pro) |
| `state [coin]` | One-call per-coin snapshot (price + market-state + levels + regime); omit coin for the unified market state (pro) |
| `regime` | Market regime read — risk-on/off score (pro) |
| `liquidity` | Liquidity map — net liq, stablecoin dry powder, OI, taker flow (pro) |
| `flows` | Capital-flow map — rotation, cross-asset OI, institutional posture (pro) |
| `market-map` | One-call cross-asset market map (regime + liquidity + flows) (pro) |
| `discovery` | Emergent-edge discovery — corroboration patterns with live forward-return edge (pro) |
| `stream` | Live signal stream over WebSocket (pro) |

## Examples

```bash
# Only proven-edge signals, as JSON
n0brains signals --proven-only --limit 10

# Is it altseason? one-line answer
n0brains rotation | jq -r .regime

# Where are BTC liquidation magnets?
n0brains liquidation-map BTC | jq '.densest_long_liq_zone, .densest_short_liq_zone'

# Feed proven-edge signals into a bot loop
while n0brains signals --tradeable-only --limit 5 | jq -c '.signals[]'; do sleep 60; done

# Live stream (needs: pip install websockets)
N0BRAINS_API_KEY=... n0brains stream | jq -c 'select(.conviction=="strong")'
```

Exit code is `2` on an API error (so scripts can detect failures), `0` on success.

## For agent frameworks

See [`SKILL.md`](SKILL.md) for a capability description you can drop into an agent
framework (the same tools are also exposed via MCP and REST).
