Metadata-Version: 2.4
Name: n0brains-cli
Version: 1.0.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 |
| `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).
