> For the complete documentation index, see [llms.txt](https://sosovalue-1.gitbook.io/sosovalue-api-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sosovalue-1.gitbook.io/sosovalue-api-doc/core-tools/cli.md).

# SoSoValue CLI

`soso` — a terminal interface for the SoSoValue Open API: crypto market data, ETF flows, news, macro indicators, and US-equity / perpetual-futures market data (v3). Human-readable tables by default, machine-readable everywhere for pipelines and AI agents.

**v0.2.0** — [download a prebuilt binary](#1-install) *(private preview; the source repository is not public yet)*

|                      |                                                                                                                   |
| -------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Query commands**   | Prices, klines, candles, quotes, ETF flows, news, macro events / rates / FOMC, analysis charts, US-equity metrics |
| **Interactive TUI**  | Full-screen live dashboard (`soso tui`) with selection, 30-day close sparklines and auto-refresh                  |
| **Live polling**     | `soso watch` — live table or NDJSON lines for piping (`--ndjson`)                                                 |
| **Machine-readable** | `--json` (raw API response) on every command, `--csv` on every table — jq- and agent-friendly                     |

## Get Started

### 1. Install

Download the archive for your platform. **Save it under the canonical filename shown below** — `SHA256SUMS.txt` lists those names, so keeping them lets `shasum -c` verify without edits.

| Platform              | Archive                    | Download                                                                                     |
| --------------------- | -------------------------- | -------------------------------------------------------------------------------------------- |
| macOS (Apple Silicon) | `soso-darwin-arm64.tar.gz` | [download](https://static.sosovalue.com/2026/09/11/90a2bc46-250c-4888-9281-0a56e9de1ed6.gz)  |
| macOS (Intel)         | `soso-darwin-amd64.tar.gz` | [download](https://static.sosovalue.com/2026/09/11/523f4542-5ce4-4f6d-8fac-86b20ca00e49.gz)  |
| Linux (x86\_64)       | `soso-linux-amd64.tar.gz`  | [download](https://static.sosovalue.com/2026/09/11/cff8645f-5727-426b-9f44-7aa7e029d450.gz)  |
| Linux (arm64)         | `soso-linux-arm64.tar.gz`  | [download](https://static.sosovalue.com/2026/09/11/4d6f25a2-2fd2-48f3-b17e-28aed1ae9f47.gz)  |
| Windows (x86\_64)     | `soso-windows-amd64.zip`   | [download](https://static.sosovalue.com/2026/09/11/183a2db7-e644-4d30-9f9d-423c1ecaa882.zip) |
| Checksums             | `SHA256SUMS.txt`           | [download](https://static.sosovalue.com/2026/09/11/75bcf5d2-2b14-40c3-87f5-e6f325ed4c47.txt) |

macOS (Apple Silicon) — adjust the first two lines for other platforms:

```bash
curl -L -o soso-darwin-arm64.tar.gz \
  https://static.sosovalue.com/2026/09/11/90a2bc46-250c-4888-9281-0a56e9de1ed6.gz
curl -L -o SHA256SUMS.txt \
  https://static.sosovalue.com/2026/09/11/75bcf5d2-2b14-40c3-87f5-e6f325ed4c47.txt

# Verify (ignore "no properly formatted lines" for the platforms you skipped)
shasum -a 256 --ignore-missing -c SHA256SUMS.txt

tar -xzf soso-darwin-arm64.tar.gz        # yields soso-darwin-arm64 + README.md
sudo install -m 755 soso-darwin-arm64 /usr/local/bin/soso
soso version                             # soso 0.2.0
```

The archive contains the binary under its **platform-suffixed name** (`soso-darwin-arm64`, `soso-linux-amd64`, …), not `soso` — hence the rename in the last step.

{% hint style="warning" %}
**macOS: unsigned binary.** The build is ad-hoc signed, with no Developer ID and no notarisation. Downloading via `curl` in a terminal is unaffected, but a copy fetched with a **browser** carries the `com.apple.quarantine` attribute and Gatekeeper will refuse to launch it — *"cannot be opened because the developer cannot be verified"*. Clear the flag once:

```bash
xattr -d com.apple.quarantine /usr/local/bin/soso
```

Signing and notarisation will land with the public release.
{% endhint %}

On Windows, unzip `soso-windows-amd64.zip` and put `soso-windows-amd64.exe` somewhere on `PATH` (renaming it to `soso.exe` is convenient); verify with `certutil -hashfile soso-windows-amd64.zip SHA256`.

### 2. Authenticate

Get an API key ([Setting Up Your API Key](https://sosovalue-1.gitbook.io/sosovalue-api-doc/setting-up-your-api-key.md)), then:

```bash
soso auth --key YOUR_API_KEY   # saved to ~/.config/soso/config.json (chmod 600)
soso status                    # verifies the key and shows rate-limit headers
```

The key can also come from the `SOSO_API_KEY` environment variable or a per-call `--api-key` flag (flag > env > config file).

### 3. Try it out

```bash
# Crypto (v1)
soso overview                          # total mcap, 24h volume, BTC/ETH gas
soso price btc eth sol                 # market snapshots
soso klines btc --limit 30             # daily klines
soso etf flows --symbol BTC --country US
soso news --limit 10                   # --hot for hot-news clusters
soso chart fgi_indicator --limit 14    # `soso charts` lists all 30 charts
soso macro events / rates sofr / fomc

# US equities & perps (v3)
soso quote AAPL.US BTC-USDT-PERP.BINANCE
soso candles AAPL.US --interval 1d --adjust back
soso metrics AAPL.US                   # latest daily metrics (P/E, mcap, ...)
soso search "apple"                    # fuzzy resolve
```

## Live Views

```bash
soso tui                               # dashboard with a default watchlist
soso tui BTC-USDT-PERP.BINANCE NVDA.US # ...or your own refs
soso watch AAPL.US NVDA.US             # live table, default every 10s
soso watch BTC-USDC-PERP.HYPERLIQUID --ndjson --interval 5s >> ticks.ndjson
```

TUI keys: `↑/↓` or `j/k` select · `enter` 30-day close chart · `r` refresh · `q` quit.

`watch` polls the [v3 batch-quote endpoint](https://sosovalue-1.gitbook.io/sosovalue-api-doc/11.-market-data-api-v3/quotes.md#batch-quotes) — one API request per tick regardless of the number of refs (max 50). Pick `--interval` with your plan's [rate limit](https://sosovalue-1.gitbook.io/sosovalue-api-doc/rate-limit.md) in mind.

## For Pipelines & AI Agents

```bash
soso quote AAPL.US --json | jq '.data.quotes["AAPL.US"].last'
soso klines btc --limit 90 --csv > btc.csv
soso watch BTC-USDT-PERP.BINANCE --ndjson | jq -r '[.ts,.last] | @tsv'
```

`--json` returns the raw API response including `meta` / `warnings` — the same contracts documented in this book, so everything on the endpoint pages (percentage conventions, decimal-string prices, `adjust` semantics) applies unchanged.

## Conventions Worth Knowing

* v3 prices and volumes are **decimal strings** — parse with a decimal type, not float ([Data Types](https://sosovalue-1.gitbook.io/sosovalue-api-doc/11.-market-data-api-v3/pagination-and-types.md#data-type-conventions-must-read)).
* Every `*_pct` field is a **percentage** (`3.03` = 3.03%) — divide by 100 for calculations.
* For perps always use the venue-qualified `full_symbol` (`BTC-USDT-PERP.BINANCE`) — bare symbols shared across venues return a 409 ([Refs](https://sosovalue-1.gitbook.io/sosovalue-api-doc/11.-market-data-api-v3/pagination-and-types.md#ref--instrument-references)).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://sosovalue-1.gitbook.io/sosovalue-api-doc/core-tools/cli.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
