> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shumi.ai/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

<Steps>
  <Step title="Install">
    Needs Node 22 or later.

    ```bash theme={"dark"}
    npm install -g shumi
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="Check the setup">
    ```bash theme={"dark"}
    shumi init
    ```

    It checks your login and the network and suggests the next commands.
  </Step>
</Steps>

## 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](/research/market-health#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 question in plain words | `shumi ask "is BTC funding crowded?"` |

`shumi scan --sort` needs CLI 0.9.1 or later, and the current trend on `shumi coin lookup` needs 0.9.0. `shumi version` shows yours, and [Market Screener](/research/market-screener) 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. [Plans and Quotas](/platform/access) has the numbers.

## 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](/api-reference/introduction) 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 without asking, up to `SHUMI_MAX_PRICE_USDC` (0.10 by default). See [Pay Per Call](/agents/payments) |
| `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 <symbol>`, `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. Call it when something happens, not on a timer.
* 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](/agents/mcp) 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.