> ## Documentation Index
> Fetch the complete documentation index at: https://shumi.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install the shumi command, sign in, create API keys and pull market data into scripts and agents.

`shumi` puts every Shumi data route in your terminal. It prints readable text for you and JSON for scripts and agents.

## Install and sign in

**1. Install**

Needs Node 22 or later.

```bash theme={"dark"}
npm install -g shumi
```

**2. Sign in**

```bash theme={"dark"}
shumi login
```

This opens your browser. If the browser shows a connection error after you signed in, run `shumi login --paste` and paste that page's URL. `shumi logout` clears the stored credentials.

**3. Check the setup**

```bash theme={"dark"}
shumi init
```

It checks your login and the network and suggests the next commands.

## Get data

| You want | Command |
| - | - |
| A verdict on one coin, with evidence | `shumi BTC` or `shumi signal BTC` |
| Risk context for one coin | `shumi coin risk BTC` |
| Which asset a ticker points to | `shumi resolve GOLD` |
| Trend counts UP, [HODL](https://shumi.mintlify.site/research/market-health.md#count-the-coins-trending-up-sideways-or-down) and DOWN | `shumi market health` |
| Live prices | `shumi market prices --symbols BTC,ETH,SOL` |
| Today's biggest movers | `shumi scan --sort change24h --limit 10` |
| Coins that match a filter | `shumi scan --category Meme --trend UP --limit 20` |
| Where funding is hot or cold | `shumi funding momentum [--symbol ETH]` |
| Sentiment on one coin | `shumi sentiment coin BTC` |
| Two coins to trade against each other | `shumi pairs suggestions` |
| A stock, metal or commodity perp | `shumi rwa lookup AAPL` |
| A coin's next token unlock | `shumi unlocks coin ARB` |
| The biggest unlocks coming up | `shumi unlocks calendar --days 30` |
| A question in plain words | `shumi ask "is BTC funding crowded?"` |

Run `shumi version` to see yours: `shumi scan --sort` needs 0.9.1 or later, the current trend on `shumi coin lookup` needs 0.9.0 and `shumi unlocks` needs 0.10.0. [Market Screener](https://shumi.mintlify.site/research/market-screener.md) covers every scan flag.

`shumi help` prints the full grouped list and every command takes `--help`. On the Free plan each data command counts as one question: 10 to start, then 1 per day, resetting at 00:00 UTC. Paid plans are in [Plans and Quotas](https://shumi.mintlify.site/platform/access.md).

## Use it in scripts and agents

Output switches to JSON on its own when you pipe it, so `shumi market health | jq .data.trends` works with no flag. The JSON is the same envelope the [API](https://shumi.mintlify.site/api-reference/introduction.md) returns.

| Flag or variable | What it does |
| - | - |
| `--json` | Force JSON on stdout |
| `--agent` | JSON, no spinner, no colour, no update notice. Errors go to stderr as JSON |
| `--fields <list>` | Keep only these top-level keys, comma separated |
| `--top <n>` | Keep the first N items when the response is a list |
| `--auto-pay` | Pay a [per-call price](https://shumi.mintlify.site/agents/payments.md) without asking, up to `SHUMI_MAX_PRICE_USDC` (0.10 by default) |
| `SHUMI_TOKEN` | An API key, created with `shumi keys create` on a machine with a browser and copied to one without |

```bash theme={"dark"}
shumi funding momentum --agent | jq '.data.assets[] | select(.tier == "hot")'
```

`shumi commands --json` prints a manifest of every command with its arguments, so an agent can discover what it can call.

## Run a bot or dashboard

For a script, bot or dashboard that checks Shumi on a timer, poll the data commands for the numbers. Ask Shumi only when something changes.

```bash theme={"dark"}
# On every tick: price, funding, trend and sentiment for each coin, as JSON
shumi coin risk PAXG BTC ETH --json

# Only when a trend flips, funding moves or price leaves your range
shumi ask "BTC's daily trend just turned DOWN. What changed?"
```

* On Plus, these commands never use a question: `coin risk`, `market health`, `market prices`, `funding momentum` and `scan`. Poll them as often as you like. Anything that writes a fresh AI answer or reading can use one. That covers `ask`, `coin` with only a ticker (`shumi coin BTC`), `search`, `tweets`, and the sentiment, signal, narrative and watch commands.
* On Free every call counts, and `coin risk` with three coins is three calls. With several coins, also check each row for `error`. On Pro nothing counts.
* `shumi ask` writes a full answer. It takes longer and uses one question on Free and Plus.
* Exit code 3 means out of quota (`429` or `402`) and 5 means a server error. On either, wait before trying again and double the wait each time it fails. Retrying on the next tick hits the same limit.

## Create an API key

A server, a bot or an [MCP client](https://shumi.mintlify.site/agents/mcp.md) needs a key instead of your login.

```bash theme={"dark"}
shumi keys create my-bot
shumi keys list
shumi keys revoke <prefix>
```

Keys start with `shumi_sk_`. `keys list` shows each key's prefix, and that is what `revoke` takes. A key carries the plan of the account that created it.

## Fix a problem

```bash theme={"dark"}
shumi doctor
```

It checks the config file, the login token and its expiry, the network, the API and whether your version is current. `shumi billing tier` shows the plan the API applies to you. Both work when you are out of quota.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.