> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soma.evarist.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Soma CLI

> Ask, search and add documents from your terminal; built for people and agents.

## Install

<Tabs>
  <Tab title="macOS / Linux">
    ```bash theme={null}
    curl -fsSL https://staging.soma.evarist.com/install.sh | sh
    ```

    Installs `~/.local/bin/soma` (change it with `SOMA_INSTALL_DIR`).
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    irm https://staging.soma.evarist.com/install.ps1 | iex
    ```

    Installs `soma.exe` in `%LOCALAPPDATA%\Programs\soma` and adds it to your PATH.
  </Tab>
</Tabs>

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

```bash theme={null}
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.

## Sign-in

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.