# CLI (/cli)



`sondo` does from a terminal what the dashboard does in a browser: read the inbox, reply to a
visitor, load the Knowledge Base, change settings, print the embed snippet.

```bash
npm install -g @usesondo/cli

# or, without installing it
npx @usesondo/cli status
```

It needs Node 20 or newer.

## Sign in [#sign-in]

Issue an API key on the Integrations page in your dashboard, then:

```bash
sondo login --key sondo_sk_…
```

The key is saved under a profile named after the workspace it opens, in
`~/.config/sondo/config.json`, readable only by you.

A key opens exactly one workspace. Run `sondo login` once per workspace, then switch with
`sondo workspace use <slug>`, or aim a single command somewhere else with `--workspace <slug>`.

For continuous integration, set `SONDO_API_KEY` and `SONDO_URL` instead. They override the saved
profiles, so nothing has to be signed in on the machine.

## Three things to try [#three-things-to-try]

```bash
# what came in while you were away
sondo inbox --unread --detail summaries

# load a folder of notes, a PDF and a page into the Knowledge Base
sondo kb add ./docs ./handbook.pdf https://example.com/pricing

# reply to a visitor
sondo conversation reply <id> "Thanks, I have sent you a booking link."
```

## Flags every command takes [#flags-every-command-takes]

| Flag                 | What it does                                                         |
| -------------------- | -------------------------------------------------------------------- |
| `--json`             | Print the answer exactly as Sondo returned it, for piping into `jq`. |
| `--workspace <slug>` | Run this one command against another saved workspace.                |
| `--profile <slug>`   | The same thing, under its other name.                                |

Errors go to standard error and the command exits 1, so a failure is visible to a script and not
just to a reader.

## Adding to the Knowledge Base [#adding-to-the-knowledge-base]

`sondo kb add` takes files, folders and addresses in one go, and decides what each one is.

A Markdown, text or HTML file is sent as text. Its title is its frontmatter `title` if it has one,
then its first `#` heading, and otherwise its filename. A PDF is uploaded. An `http` or `https` address is fetched by Sondo
rather than by your machine. A folder is walked for those file types, skipping dotfiles and
`node_modules`.

Every source gets its own line of output. One failure does not stop the rest, and the command exits
1 if anything failed at all. A file over 2 MB, or a text file over 200,000 characters, is skipped
rather than truncated, because a silently half-loaded document is worse than one you were told
about. With `--json` you get a single array of per-source outcomes instead of the lines.

## Changing settings [#changing-settings]

`settings set` and `widget set` take `key=value` pairs. Each value is parsed as JSON, and falls back
to the raw string when that fails. So `starters='["Pricing?"]'` is an array and `showHeader=false` is
a boolean, while `headerTitle=Ask us` is the string you typed. Mind the ones that look like text:
`headerTitle=true` is the boolean, not the word.

```bash
sondo settings set timezone=Europe/Amsterdam resumeWindowHours=24
sondo widget set headerTitle="Ask us" starters='["Pricing?","Book a call"]'
```

One rejected key fails the whole command, so a half-applied change cannot happen.

## How it works [#how-it-works]

The CLI speaks nothing but Sondo's [MCP endpoint](/mcp), calling the same tools an AI client would,
with your API key as a bearer token. That is the point of it: anything the CLI can do, an agent can
do, and the reverse.

Most commands are one call. A few are not. `logout`, `workspace list` and `workspace use` only touch
the config file on your machine and reach Sondo not at all. `kb add` makes one call per source, which
is why one failing source does not stop the others. `widget snippet` makes the same call as
`widget get` and prints one field of the answer.

## Command reference [#command-reference]

Generated from the tool itself. `sondo --help`, and `sondo <noun> --help`, list the commands in
your terminal.

The CLI has 37 commands.

### Signing in [#signing-in]

One key opens one workspace, so sign in once per workspace and switch between them.

#### `sondo login` [#sondo-login]

Save an API key as a workspace profile. The profile is named after the workspace.

| Argument or flag | What it does                                                                |
| ---------------- | --------------------------------------------------------------------------- |
| `--key <key>`    | The sondo*sk* key. Prompted for when omitted.                               |
| `--url <url>`    | Where Sondo runs. Defaults to [https://usesondo.com](https://usesondo.com). |

```bash
sondo login --key sondo_sk_...
```

#### `sondo logout [slug]` [#sondo-logout-slug]

Forget a saved workspace. Defaults to the current one.

| Argument or flag  | What it does         |
| ----------------- | -------------------- |
| `slug` (optional) | Workspace to forget. |

```bash
sondo logout mahdif
```

#### `sondo workspace list` [#sondo-workspace-list]

The saved workspaces, with the default marked.

```bash
sondo workspace list
```

#### `sondo workspace use <slug>` [#sondo-workspace-use-slug]

Make a saved workspace the default for later commands.

| Argument or flag | What it does            |
| ---------------- | ----------------------- |
| `slug`           | Workspace to switch to. |

```bash
sondo workspace use mahdif
```

#### `sondo status` [#sondo-status]

Check the connection and report which workspace the key opens.

```bash
sondo status
```

### Conversations [#conversations]

Read the inbox, act on a thread, and take over from the assistant when you want to.

#### `sondo inbox` [#sondo-inbox]

Conversations, most recently active first.

| Argument or flag     | What it does                                |
| -------------------- | ------------------------------------------- |
| `--unread`           | Only unread conversations.                  |
| `--archived`         | Only archived conversations.                |
| `-q, --query <text>` | Search titles, messages and visitor emails. |
| `--detail <level>`   | titles (default) or summaries.              |
| `--page <n>`         | Page number, from 1.                        |

```bash
sondo inbox --unread --detail summaries
```

#### `sondo unread` [#sondo-unread]

How many conversations are unread.

```bash
sondo unread
```

#### `sondo conversation get <id>` [#sondo-conversation-get-id]

One conversation in full: transcript, visitor context and cost.

| Argument or flag | What it does                         |
| ---------------- | ------------------------------------ |
| `id`             | Conversation id, from `sondo inbox`. |

```bash
sondo conversation get 0f5c...
```

#### `sondo conversation read <id>` [#sondo-conversation-read-id]

Mark a conversation read, or pass all to clear the inbox.

| Argument or flag | What it does             |
| ---------------- | ------------------------ |
| `id`             | Conversation id, or all. |

```bash
sondo conversation read all
```

#### `sondo conversation unread <id>` [#sondo-conversation-unread-id]

Mark one conversation unread.

| Argument or flag | What it does     |
| ---------------- | ---------------- |
| `id`             | Conversation id. |

```bash
sondo conversation unread 0f5c...
```

#### `sondo conversation archive <id>` [#sondo-conversation-archive-id]

Move a conversation out of the inbox. Reversible, and it deletes nothing.

| Argument or flag | What it does     |
| ---------------- | ---------------- |
| `id`             | Conversation id. |

```bash
sondo conversation archive 0f5c...
```

#### `sondo conversation restore <id>` [#sondo-conversation-restore-id]

Bring an archived conversation back to the inbox.

| Argument or flag | What it does     |
| ---------------- | ---------------- |
| `id`             | Conversation id. |

```bash
sondo conversation restore 0f5c...
```

#### `sondo conversation star <id>` [#sondo-conversation-star-id]

Star a conversation.

| Argument or flag | What it does                         |
| ---------------- | ------------------------------------ |
| `id`             | Conversation id, from `sondo inbox`. |

```bash
sondo conversation star 0f5c...
```

#### `sondo conversation unstar <id>` [#sondo-conversation-unstar-id]

Remove the star from a conversation.

| Argument or flag | What it does                         |
| ---------------- | ------------------------------------ |
| `id`             | Conversation id, from `sondo inbox`. |

```bash
sondo conversation unstar 0f5c...
```

#### `sondo conversation pause <id>` [#sondo-conversation-pause-id]

Stop the assistant from answering in this conversation.

| Argument or flag | What it does                         |
| ---------------- | ------------------------------------ |
| `id`             | Conversation id, from `sondo inbox`. |

```bash
sondo conversation pause 0f5c...
```

#### `sondo conversation resume <id>` [#sondo-conversation-resume-id]

Let the assistant answer again.

| Argument or flag | What it does                         |
| ---------------- | ------------------------------------ |
| `id`             | Conversation id, from `sondo inbox`. |

```bash
sondo conversation resume 0f5c...
```

#### `sondo conversation block <id>` [#sondo-conversation-block-id]

Block this visitor from sending more messages.

| Argument or flag   | What it does                         |
| ------------------ | ------------------------------------ |
| `id`               | Conversation id, from `sondo inbox`. |
| `--message <text>` | What the blocked visitor sees.       |

```bash
sondo conversation block 0f5c... --message "Contact us by email."
```

#### `sondo conversation unblock <id>` [#sondo-conversation-unblock-id]

Unblock this visitor.

| Argument or flag | What it does                         |
| ---------------- | ------------------------------------ |
| `id`             | Conversation id, from `sondo inbox`. |

```bash
sondo conversation unblock 0f5c...
```

#### `sondo conversation reply <id> <text>` [#sondo-conversation-reply-id-text]

Send an operator reply into a conversation.

| Argument or flag | What it does     |
| ---------------- | ---------------- |
| `id`             | Conversation id. |
| `text`           | What to say.     |

```bash
sondo conversation reply 0f5c... "Thanks, booking a call now."
```

### Knowledge Base and sites [#knowledge-base-and-sites]

Load and maintain what the assistant answers from.

#### `sondo kb list` [#sondo-kb-list]

The documents in the Knowledge Base.

| Argument or flag | What it does         |
| ---------------- | -------------------- |
| `--page <n>`     | Page number, from 1. |

```bash
sondo kb list
```

#### `sondo kb get <id>` [#sondo-kb-get-id]

One Knowledge Base document in full.

| Argument or flag | What it does                       |
| ---------------- | ---------------------------------- |
| `id`             | Document id, from `sondo kb list`. |

```bash
sondo kb get 8b21...
```

#### `sondo kb add <sources...>` [#sondo-kb-add-sources]

Add files, folders or web pages to the Knowledge Base.

| Argument or flag  | What it does                                     |
| ----------------- | ------------------------------------------------ |
| `sources...`      | Files, folders or http(s) addresses.             |
| `--title <title>` | Title for a single source. Ignored for a folder. |

```bash
sondo kb add ./docs ./handbook.pdf https://example.com/pricing
```

#### `sondo kb update <id>` [#sondo-kb-update-id]

Change a Knowledge Base document's title or text.

| Argument or flag     | What it does                             |
| -------------------- | ---------------------------------------- |
| `id`                 | Document id.                             |
| `--title <title>`    | New title.                               |
| `--text-file <path>` | File whose contents become the new text. |

```bash
sondo kb update 8b21... --text-file ./pricing.md
```

#### `sondo kb remove <id>` [#sondo-kb-remove-id]

Delete a Knowledge Base document.

| Argument or flag | What it does |
| ---------------- | ------------ |
| `id`             | Document id. |

```bash
sondo kb remove 8b21...
```

#### `sondo kb refresh <id>` [#sondo-kb-refresh-id]

Fetch a linked page again and re-embed the document.

| Argument or flag | What it does |
| ---------------- | ------------ |
| `id`             | Document id. |

```bash
sondo kb refresh 8b21...
```

#### `sondo site list` [#sondo-site-list]

The connected sites and their sync state.

```bash
sondo site list
```

#### `sondo site connect <url>` [#sondo-site-connect-url]

Connect a site so its posts sync into the Knowledge Base.

| Argument or flag  | What it does                                         |
| ----------------- | ---------------------------------------------------- |
| `url`             | The site's root address.                             |
| `--prefix <path>` | Only sync pages under this path.                     |
| `--index <url>`   | A sitemap or index page to read instead of guessing. |

```bash
sondo site connect https://example.com --prefix /blog
```

#### `sondo site sync <id>` [#sondo-site-sync-id]

Sync a connected site now.

| Argument or flag | What it does                     |
| ---------------- | -------------------------------- |
| `id`             | Site id, from `sondo site list`. |

```bash
sondo site sync 4c90...
```

#### `sondo site remove <id>` [#sondo-site-remove-id]

Disconnect a site.

| Argument or flag | What it does |
| ---------------- | ------------ |
| `id`             | Site id.     |

```bash
sondo site remove 4c90...
```

### Configuration [#configuration]

The workspace's settings, the widget, its embed snippet, and the keys and spend.

#### `sondo settings get` [#sondo-settings-get]

The workspace settings.

```bash
sondo settings get
```

#### `sondo settings set <assignments...>` [#sondo-settings-set-assignments]

Change workspace settings. One bad key fails the whole command.

| Argument or flag | What it does                                        |
| ---------------- | --------------------------------------------------- |
| `assignments...` | key=value pairs. Values that are not text are JSON. |

```bash
sondo settings set timezone=Europe/Amsterdam resumeWindowHours=24
```

#### `sondo widget get` [#sondo-widget-get]

The widget's configuration.

```bash
sondo widget get
```

#### `sondo widget snippet` [#sondo-widget-snippet]

The embed snippet to paste into a site.

```bash
sondo widget snippet
```

#### `sondo widget set <assignments...>` [#sondo-widget-set-assignments]

Change the widget's configuration. One bad key fails the whole command.

| Argument or flag | What it does                                        |
| ---------------- | --------------------------------------------------- |
| `assignments...` | key=value pairs. Values that are not text are JSON. |

```bash
sondo widget set headerTitle="Ask us" starters='["Pricing?","Book a call"]'
```

#### `sondo keys list` [#sondo-keys-list]

The API keys for this workspace.

```bash
sondo keys list
```

#### `sondo keys revoke <id>` [#sondo-keys-revoke-id]

Revoke an API key. Issue new keys at Settings > Integrations.

| Argument or flag | What it does                    |
| ---------------- | ------------------------------- |
| `id`             | Key id, from `sondo keys list`. |

```bash
sondo keys revoke 2ad7...
```

#### `sondo usage` [#sondo-usage]

Model spend in US dollars.

| Argument or flag | What it does                  |
| ---------------- | ----------------------------- |
| `--unit <unit>`  | day (default), week or month. |

```bash
sondo usage --unit week
```