> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sovseal.com/llms.txt
> Use this file to discover all available pages before exploring further.
# sovseal CLI: Terminal Memory, Diagnostics & Device Linking
> Reference for the sovseal binary — memory commands, doctor diagnostics, the --json agent envelope, exit codes, and the sovseal login device handshake.
The `sovseal` binary ships **inside `@sovseal/mcp-server`** — there is no separate CLI package to install or keep in sync. The CLI, the MCP server, the native messaging host, and the SDK are one build reading and writing the same on-device vault at `~/.sovseal`, so the CLI can never end up reading a schema a different version wrote.
```bash theme={null}
npx -y --package=@sovseal/mcp-server sovseal doctor
```
**No account or API key is required.** Storing and recalling work entirely offline. Linking an account only adds multi-device sync, team seats, and the audit ledger.
## Quick start
```bash theme={null}
# Write a memory
sovseal store "We standardised on pnpm workspaces, not npm"
# Pipe anything into memory
git log -n 20 --oneline | sovseal store
# Semantic search, entirely on-device
sovseal recall "which package manager did we pick?"
# What has it actually learned?
sovseal mind
# Is the install healthy?
sovseal doctor
```
## Commands
| Group | Commands |
| --------------- | ----------------------------------------------------------------------------------- |
| **Memory** | `store` (`add`), `recall` (`search`), `list` (`ls`), `get`, `delete` (`rm`), `mind` |
| **Diagnostics** | `doctor`, `status` |
| **Account** | `login`, `logout`, `whoami`, `open` |
| **Setup** | `onboard` (`init`), `config` |
| **Meta** | `help`, `version` |
Run `sovseal help ` for the full flag list of any one of them.
### `store`
Embeds text on-device and writes it to the encrypted LanceDB store. High-risk PII is redacted **before** the text is embedded or stored, and near-duplicate content reinforces the existing memory instead of creating a second row — so piping the same log twice is safe.
Content to remember. Omit it to read from stdin or `--file`.
Read the content from a file instead of an argument.
How the memory was obtained: `explicit`, `observed`, or `synthesized`. Recall trusts `explicit` most.
### `recall`
Embeds the query on-device and ranks memories by a composite of cosine similarity, recency decay, and how often the fact has been restated. **0 RTT** — the same path the `recall_memory` MCP tool takes.
Number of results to return (1–20).
Drop results below this raw cosine similarity.
Print each memory in full instead of truncating to one line.
### `doctor`
Runs nine probes in one pass and streams each finding with a concrete fix:
1. Node.js runtime version
2. Config directory existence and permissions
3. Encryption key custody (OS keychain reachable, subkeys derive)
4. Project identity
5. Local vector store (row count, schema version, replication backlog)
6. On-device embedding model
7. Chrome native-messaging bridge
8. MCP client registration
9. Sync endpoint reachability (skip with `--offline`)
`doctor` exits **5** only when a check **fails**. Warnings — an unregistered browser bridge, an unreachable sync endpoint — leave it at **0**, because memory still works local-first. That makes it safe as a CI or post-install gate.
### `open`
Jumps straight to a dashboard page instead of making you find the URL:
```bash theme={null}
sovseal open plan # subscription and billing
sovseal open proof # audit ledger
sovseal open devices # paired devices and project tokens
sovseal open --print # print the URL instead of launching a browser
```
Known pages: `home`, `plan`, `proof`, `devices`, `settings`, `auth`, `docs`.
## Use from an AI agent
`--json` (alias `--agent`) switches every command to a structured envelope on stdout, with no colour, spinners, or prompts:
```bash theme={null}
sovseal --json recall "deploy runbook" | jq -r '.data[].text'
```
```json theme={null}
{
"status": "success",
"command": "recall",
"duration_ms": 12,
"scope": { "query": "deploy runbook", "top_k": 5, "threshold": 0 },
"count": 2,
"data": [
{ "id": "7b3c1a2e-…", "text": "Deploys run canary at 5% for 10 minutes", "score": 0.81, "similarity": 0.74 }
]
}
```
Failures use the same envelope shape:
```json theme={null}
{
"status": "error",
"command": "get",
"duration_ms": 4,
"error": { "code": "NOT_FOUND", "message": "No memory with id …" }
}
```
Discover the whole surface as data rather than scraping help text:
```bash theme={null}
sovseal help --json
```
`--json` is accepted before or after the command name, so `sovseal --json recall "x"` and `sovseal recall "x" --json` are equivalent.
## Exit codes
Exit codes are part of the public surface — scripts branch on them.
| Code | Meaning |
| ---- | ------------------------------------------------- |
| `0` | Success |
| `1` | Runtime error |
| `2` | Usage error (unknown flag, missing argument) |
| `3` | Not found |
| `4` | Authentication required |
| `5` | `doctor` completed with at least one failed check |
## `sovseal login` — linking a device
```bash theme={null}
sovseal login # opens the dashboard, waits on a loopback listener
sovseal login --no-browser # print the URL instead of opening it
sovseal login --token … # non-interactive, for CI and headless hosts
```
The CLI binds an ephemeral port on `127.0.0.1` and sends you to `/connect/cli` on the dashboard. The dashboard derives your account master **in the browser**, derives the deterministic project token (`sov_proj_…`) from it, and redirects that token back to the local listener.
Your passphrase, account master, and encryption keys never leave the browser — the master is zeroed as soon as the token is derived. Only the project token moves, and it moves over loopback.
The dashboard refuses any `redirect_uri` that is not `http` + a loopback host + exactly `/callback`, so a crafted "connect sovseal" link cannot redirect your project token to a remote server. The CLI independently compares the returned `state` in constant time and rejects requests whose `Host` header is not loopback.
`sovseal logout` clears the token and account fields. Your memories and encryption keys are untouched — recall keeps working offline, replication just stops.
## Configuration
`sovseal config` operates on `~/.sovseal/config.json` (mode `0600`). Secrets are redacted on read, and only a whitelist of keys is writable — the rest are runtime-owned, and hand-editing them would break your vault.
```bash theme={null}
sovseal config show # secrets redacted
sovseal config get endpoint
sovseal config set default_top_k 10
sovseal config path
```
| Writable key | Purpose |
| --------------- | ---------------------------------------------------- |
| `endpoint` | Sync endpoint the replication worker posts blocks to |
| `api_key` | Project token (prefer `sovseal login`) |
| `dashboard_url` | Base URL used by `sovseal open` |
| `default_top_k` | Default result count for `sovseal recall` |
| `device_label` | Human-readable device name shown on the dashboard |
## Guarantees
* **No telemetry.** The CLI reports nothing, anywhere, and has no flag to disable because there is nothing to disable.
* **Secrets are never printed in full** — project tokens are redacted in every output mode, including `--json`.
* **Destructive commands refuse to run unattended.** `delete --all` requires `--force`, and a non-interactive shell can never be prompted into a yes.
* **Fast by default.** Commands that do not touch the vector engine (`help`, `open`, `config`, `whoami`, `version`) skip loading it entirely.