Soma CLI

Install

macOS / Linux
Windows

curl -fsSL https://staging.soma.evarist.com/install.sh | sh

Installs ~/.local/bin/soma (change it with SOMA_INSTALL_DIR).

irm https://staging.soma.evarist.com/install.ps1 | iex

Installs soma.exe in %LOCALAPPDATA%\Programs\soma and adds it to your PATH.

Run the same command again to update.

Chat session

Run soma alone in a terminal: it signs you in the first time, lets you pick a workspace, then answers your questions in one conversation.

In the session
`/workspace [name]`	Switch workspace
`/new`	Start a new conversation
`/exit`	Quit (or Ctrl+D)

Commands

Command
`soma ask <question> [-c] [--thread <id>]`	An answer with sources; `-c` continues your last conversation
`soma search <query> [-n 10] [--scope <name>]`	The most relevant passages
`soma docs [-q <title>]`	The workspace’s documents
`soma read <document-id>`	A whole document, in order (tables included)
`soma entities [-q <search>] [--type <type>]`	Entities of the knowledge graph
`soma entity <entity-id> [--depth 2]`	An entity and its relations
`soma upload <files…> [--no-wait]`	Add files; waits until they are searchable
`soma workspaces`	List workspaces
`soma workspaces create <name>` / `rename <ws> <name>` / `delete <ws> --yes`	Manage workspaces
`soma use <workspace>`	Choose the default workspace
`soma login [--read-only]` / `soma logout` / `soma whoami`	Your session

-w <workspace> (a name or an id) works on any command; soma <command> --help gives details.

Documents

soma workspaces create "Pump study"
soma upload specs/*.pdf -w "Pump study"
soma ask "Which seal type is specified for P-101?" -w "Pump study"

PDF, Word, PowerPoint, Excel, CSV, Markdown, text and images.

Options and environment


`--json`	Machine-readable output (the API’s JSON) on stdout
`--host <url>` / `SOMA_HOST`	The Soma server
`SOMA_TOKEN`	An API key or access token, instead of `soma login`
`SOMA_WORKSPACE`	The workspace, instead of `soma use`

Exit codes: 0 ok, 1 failed, 2 bad usage, 3 sign-in needed. soma login opens your browser on Soma’s sign-in page and receives the result on a local address (OAuth 2.1 with PKCE). The session is stored in ~/.config/soma/credentials.json (readable only by you) and renewed automatically. By default the CLI may also create workspaces and add documents; --read-only asks only for reading.

Get started

Connect your agents

CLI

API

MCP

Install

Chat session

Commands

Documents

Options and environment

​Install

​Chat session

​Commands

​Documents

​Options and environment

​Sign-in

Install

Chat session

Commands

Documents

Options and environment

Sign-in