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.

npm install -g @usesondo/cli

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

It needs Node 20 or newer.

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

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

# 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

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

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

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.

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

The CLI speaks nothing but Sondo's MCP endpoint, 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

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

The CLI has 37 commands.

Signing in

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

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

Argument or flag	What it does
`--key <key>`	The sondosk key. Prompted for when omitted.
`--url <url>`	Where Sondo runs. Defaults to https://usesondo.com.

sondo login --key sondo_sk_...

`sondo logout [slug]`

Forget a saved workspace. Defaults to the current one.

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

sondo logout mahdif

`sondo workspace list`

The saved workspaces, with the default marked.

sondo workspace list

`sondo workspace use <slug>`

Make a saved workspace the default for later commands.

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

sondo workspace use mahdif

`sondo status`

Check the connection and report which workspace the key opens.

sondo status

Conversations

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

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

sondo inbox --unread --detail summaries

`sondo unread`

How many conversations are unread.

sondo unread

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

sondo conversation get 0f5c...

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

sondo conversation read all

`sondo conversation unread <id>`

Mark one conversation unread.

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

sondo conversation unread 0f5c...

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

sondo conversation archive 0f5c...

`sondo conversation restore <id>`

Bring an archived conversation back to the inbox.

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

sondo conversation restore 0f5c...

`sondo conversation star <id>`

Star a conversation.

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

sondo conversation star 0f5c...

`sondo conversation unstar <id>`

Remove the star from a conversation.

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

sondo conversation unstar 0f5c...

`sondo conversation pause <id>`

Stop the assistant from answering in this conversation.

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

sondo conversation pause 0f5c...

`sondo conversation resume <id>`

Let the assistant answer again.

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

sondo conversation resume 0f5c...

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

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

`sondo conversation unblock <id>`

Unblock this visitor.

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

sondo conversation unblock 0f5c...

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

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

Knowledge Base and sites

Load and maintain what the assistant answers from.

`sondo kb list`

The documents in the Knowledge Base.

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

sondo kb list

`sondo kb get <id>`

One Knowledge Base document in full.

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

sondo kb get 8b21...

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

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

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

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

`sondo kb remove <id>`

Delete a Knowledge Base document.

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

sondo kb remove 8b21...

`sondo kb refresh <id>`

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

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

sondo kb refresh 8b21...

`sondo site list`

The connected sites and their sync state.

sondo site list

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

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

`sondo site sync <id>`

Sync a connected site now.

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

sondo site sync 4c90...

`sondo site remove <id>`

Disconnect a site.

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

sondo site remove 4c90...

Configuration

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

`sondo settings get`

The workspace settings.

sondo settings get

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

sondo settings set timezone=Europe/Amsterdam resumeWindowHours=24

The widget's configuration.

sondo widget get

The embed snippet to paste into a site.

sondo widget snippet

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.

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

`sondo keys list`

The API keys for this workspace.

sondo keys list

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

sondo keys revoke 2ad7...

`sondo usage`

Model spend in US dollars.

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

sondo usage --unit week

On this page