Somnia CLI

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 22 or newer, and says so on an older one.

Run it once with npx, with nothing to install:

npx @somnia-chain/cli --help

Or install it to get a somnia command on your path:

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, stores keys in your system keychain. If your platform has no prebuilt binary for it, somnia keys and SOMNIA_SIGNER=keychain:<name> 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:<address>.

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:

# 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:

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. Then mint test collateral and place an order on a binary market:

# 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

--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:

somnia --help
somnia perp --help
somnia perp place --help

Networks

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 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).

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: <message> 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.

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.

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:

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 for setup.

Feedback

Found a bug, or something missing or confusing? Tell the team from the terminal:

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.

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

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.