# Somnia CLI > The somnia command line: spot, binary and perp order books, SomniaLend, oracle prices, the Explorer and the indexer's history, from your terminal, a script or an agent. Install it with npx, read without an account, and sign with a key from your system keychain. **Somnia Markets from your terminal.** `somnia` is the command line for Somnia Markets: the spot, binary (YES/NO) and perp order books, SomniaLend, oracle prices, the Explorer and the markets indexer's history. Every read works without an account. Every write signs with a key from the environment or your system keychain, never from a flag. At a terminal it prints text you can read; in a pipe, a script or an agent's shell it prints JSON. ## Install The CLI needs [Node.js](https://nodejs.org) 22 or newer, and says so on an older one. Run it once with `npx`, with nothing to install: ```sh npx @somnia-chain/cli --help ``` Or install it to get a `somnia` command on your path: ```sh npm install -g @somnia-chain/cli somnia --version ``` The package is one self-contained file with no runtime dependencies. The only optional one, [`@napi-rs/keyring`](https://www.npmjs.com/package/@napi-rs/keyring), stores keys in your system keychain. If your platform has no prebuilt binary for it, `somnia keys` and `SOMNIA_SIGNER=keychain:` are unavailable, and everything else still works: sign with `SOMNIA_PRIVATE_KEY` or `SOMNIA_SESSION_SEED` instead, or build unsigned transactions with `SOMNIA_SIGNER=build:

`. To update, run the same install command again. The examples below assume `somnia` is on your path; with `npx`, put `npx @somnia-chain/cli` in its place. ## Read without an account Reads need no key and no configuration, and go to mainnet unless you pick testnet: ```sh # The latest oracle price for BTC somnia prices feed BTC # Spot pools, then one pool's order book somnia catalog markets --type SPOT somnia spot book --pool 0x... # BTC binary markets trading now, soonest expiry first somnia binary markets --asset BTC --limit 5 # Perp markets, which are on testnet only somnia perp markets --network testnet # One wallet across every market: balances, orders, positions and what it can claim somnia wallet 0x... # What does this address, hash, block or id name, and which commands read it? somnia lookup 0x... # Is the indexer keeping up with the chain? somnia health sync # Follow every oracle update for ETH until you stop it somnia watch price ETH ``` ``` BTC/USDC · oracle feed · mainnet Spot 80,741.675 Mark 80,727.515 (-0.018% vs spot) Updated 20:00:17 (1s ago) · block 449,768,411 ``` ## Send your first transaction on testnet Try writes on the Global testnet first. Create a key in your system keychain, point the CLI at it and check the account: ```sh somnia keys generate testnet export SOMNIA_SIGNER=keychain:testnet somnia signer show --network testnet ``` The account needs STT for gas: request some from the [testnet faucet](/blockchain/faucet). Then mint test collateral and place an order on a binary market: ```sh # 10,000 tUSDC, the testnet binary collateral, to the signer somnia binary faucet --network testnet # Pick a binary market trading now on testnet (needs jq) MARKET=$(somnia binary markets --network testnet --limit 1 | jq -r '.[0].id') # Buy 10 YES at 0.55 somnia binary place --market $MARKET --side buy-yes --price 0.55 --quantity 10 --network testnet ``` A write approves the token it spends when the allowance is short, waits for the receipt and prints the transaction's hash, status and block, with its Explorer link at a terminal. Before it sends, it checks that the account can pay the gas: each transaction reserves its gas limit at 60 gwei, 0.6 STT at the default 10,000,000 gas. Perp margin is USDso, which has no testnet faucet. Sell STT for USDso on the SOMI/USDso spot pool, check what it brought with `somnia wallet $ADDRESS --network testnet`, then deposit at most that with `somnia perp deposit --amount 15 --network testnet`. `somnia perp --help` walks through it. ## What you can do | Command | What it does | | --- | --- | | `spot` | Spot order books: pools, orders and vaults; place, amend and cancel orders, and stop orders | | `binary` | Binary (YES/NO) markets: find markets, read books, positions and PnL; trade, mint and redeem | | `perp` | Perpetual futures (testnet only): cross-margin accounts, orders, stops, funding and liquidations | | `wallet` | One account across every market: balances, orders, positions and claimable payouts | | `lending` | SomniaLend (Aave v3): reserves and accounts; supply, withdraw, borrow and repay | | `tokens` | ERC-20, ERC-6909 and native SOMI balances, allowances and metadata | | `catalog` | Markets and pools of every kind: listings, counts, bindings and fees | | `prices` | Oracle prices: latest feeds, ticks, candles and feed health | | `watch` | Live data as it happens: blocks, logs, markets, order flow, prices, balances and positions | | `fills` | The executed-trade tape of every market | | `candles` | A pool's OHLCV candles | | `venues` | Operators and venues on MarketsCore, and the builder fees routed through their markets | | `activity` | The venue's indexed timeline, per market, transaction or block | | `fees` | Protocol, builder and settlement fee history | | `health` | Indexer lag behind the chain, and an overall venue grade | | `system` | Deployed contract wiring, the endpoints in use, and transaction summaries | | `explorer` | Explorer lookups: address, transaction, block, token, logs and search | | `lookup` | Say what an address, hash, block, id or text names, and how to read it | | `signer` | The account writes sign as, and plain SOMI or ERC-20 transfers from it | | `keys` | Signing keys in the system keychain | | `tx` | Sign and send transactions built elsewhere | | `read` | An RPC endpoint's chain id and latest block: a connectivity check | | `feedback` | Tell the Somnia team what is wrong, missing or confusing | | `telemetry` | Anonymous usage telemetry: off until you opt in | | `mcp` | The [Somnia MCP server](/build/mcp) for AI agents | `--help` on any command lists its flags, what each one means and working examples. It is written to be enough on its own, for people and coding agents alike: ```sh somnia --help somnia perp --help somnia perp place --help ``` ## Networks | Flag | Network | | --- | --- | | `--network mainnet` (default) | Global mainnet, chain `5031` | | `--network testnet` | Global testnet, chain `50312` | `SOMNIA_NETWORK` sets the default for a whole shell. `--rpc-url`, `--indexer-url`, `--oracle-url` and `--explorer-url` point a command at other endpoints than the preset's. Perp markets and `binary faucet` are on testnet only. The [Regional Subchains](/blockchain/networks) have no preset yet. ## Units and output Amounts and prices are in token units: `--price 81500`, `--quantity 0.001`, `--amount 100`. The command reads the token's decimals, and order commands refuse a price or size off the market's tick and lot, naming the nearest valid values. `--raw` takes raw on-chain integers instead (1.5 of a 6-decimal token is `1500000`). Flags typed `uint` (ids, bps, blocks) are always raw integers. Times are unix seconds unless a flag says otherwise. At a terminal, a command prints tables and labelled fields: amounts in token units, prices at the market's precision and times on your clock. Anywhere else (a pipe, a file, an agent's shell) it prints JSON on stdout, with big integers as decimal strings so nothing loses precision. Addresses are checksummed and an order's side is a `side` string (`buy`, `sell`, `buy-yes` and so on). | Want | Use | | --- | --- | | JSON at a terminal | `--json`, or `SOMNIA_FORMAT=json` for the whole shell | | Text when piped, for example into `less` | `--format text`, or `SOMNIA_FORMAT=text` | | No color | `--no-color`, or `NO_COLOR=1` | ```sh somnia binary markets --asset BTC --limit 5 | jq -r '.[].question' ``` `watch` commands run until you stop them. At a terminal each prints a timestamped line per update; anywhere else it prints one compact JSON object per line. A failure prints one `error: ` line to stderr and exits with status 1, so scripts and CI can check the exit code. ## Signing The signer always comes from the environment, never from a flag, so keys stay out of process lists. Don't type a private key into an interactive shell, which can save it in its history: keep keys in the system keychain with `somnia keys`, or inject `SOMNIA_PRIVATE_KEY` from a secret manager in CI and on servers. | Variable | Signs with | | --- | --- | | `SOMNIA_PRIVATE_KEY=0x<64 hex>` | A local key. The default source | | `SOMNIA_SIGNER=keychain[:]` | A key stored with `somnia keys` (the name defaults to `default`) | | `SOMNIA_SIGNER=build:

` | Nothing: prints the unsigned transactions from `

` | Acts as this [smart account](/blockchain/smart-accounts), owned by the key, which pays the gas | `somnia signer show` prints the account in use and its SOMI balance. ### Keys in the system keychain `somnia keys` keeps keys in the macOS Keychain, Windows Credential Manager or the Secret Service on Linux, so they never sit in a dotfile. It can `generate`, `import`, `list` and `remove` them. ```sh somnia keys generate trading SOMNIA_SIGNER=keychain:trading somnia signer show ``` ### In CI and on servers Where there is no keychain, such as a CI runner or a headless server, set `SOMNIA_PRIVATE_KEY` from a secret. Prompts never appear outside a terminal, and JSON output and exit codes make each step easy to check. ### Offline signing Build a transaction on one machine, sign it where the key lives and broadcast it from anywhere: ```sh SOMNIA_SIGNER=build:$ADDRESS somnia spot cancel --pool $POOL --order-id 42 > built.json somnia tx sign < built.json > signed.json somnia tx submit < signed.json ``` ## Use it with AI agents Agents can run the CLI from a shell, where it prints JSON, or connect to it as an MCP server with `somnia mcp`. See [Somnia MCP server](/build/mcp) for setup. ## Feedback Found a bug, or something missing or confusing? Tell the team from the terminal: ```sh somnia feedback "perp place should say which tick sizes are valid" --context "placing a BTC order on testnet" ``` It sends your message with the CLI version, Node and OS and, if a command failed in the last 24 hours, that command's name and error, never its flag values. Keys, signers and the environment are never sent. `--message-only` sends your words alone, `--email` gives the team somewhere to reply, and the command prints the reference your feedback is filed under. ## Usage telemetry Telemetry is off unless you turn it on. The first time you run a command at a terminal, `somnia` asks once whether to share anonymous usage data. The default answer is no, and the question never appears in a pipe, in CI or under `somnia mcp`. With it on, each command sends one event: the command's name, the names of its flags (never their values), the network, whether it worked and the kind of error, how long it took, the CLI version, OS, CPU architecture and Node, whether it ran in CI, and when. It never sends keys, addresses, amounts, hashes, arguments or error messages. The team uses it to see which commands people use and where they get stuck. ```sh somnia telemetry status # what is on, and exactly what is shared somnia telemetry enable somnia telemetry disable ``` `DO_NOT_TRACK=1` always turns it off, and `SOMNIA_TELEMETRY=1` or `0` overrides the saved choice. An agent should ask its user before running `somnia telemetry enable`, and say what would be shared. ## Shell completions ```sh mkdir -p ~/.zsh/completions somnia --completions zsh > ~/.zsh/completions/_somnia # in ~/.zshrc, before compinit: fpath=(~/.zsh/completions $fpath) somnia --completions bash >> ~/.bashrc ``` `fish`, `powershell` and `sh` work too. --- Every page is also Markdown: append `.md` to its URL, or ask for `text/markdown`. Found something wrong, missing or confusing in these docs? Tell us: `POST /api/feedback` on this site with JSON `{"message": "…", "context": "what you were doing and what happened", "page": "…"}`, or a plain-text body. `GET /api/feedback` gives the JSON Schema. The team reads every one.