sovseal CLI: Terminal Memory, Diagnostics & Device Linking

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.

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

# 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 <command> 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.

string

Content to remember. Omit it to read from stdin or --file.

path

Read the content from a file instead of an argument.

string

default:"explicit"

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.

integer

default:"5"

Number of results to return (1–20).

number

default:"0"

Drop results below this raw cosine similarity.

boolean

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:

Node.js runtime version
Config directory existence and permissions
Encryption key custody (OS keychain reachable, subkeys derive)
Project identity
Local vector store (row count, schema version, replication backlog)
On-device embedding model
Chrome native-messaging bridge
MCP client registration
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:

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:

sovseal --json recall "deploy runbook" | jq -r '.data[].text'

{
  "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:

{
  "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:

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

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.

Get Started

Platform

Agent Plugins

Self-Hosted

Integrations

Cookbooks

API Reference

Release Notes

sovseal CLI: Terminal Memory, Diagnostics & Device Linking

Quick start

Commands

`store`

`recall`

`doctor`

`open`

Use from an AI agent

Exit codes

Configuration

Guarantees

​Quick start

​Commands

​store

​recall

​doctor

​open

​Use from an AI agent

​Exit codes

​sovseal login — linking a device

​Configuration

​Guarantees

Quick start

Commands

`store`

`recall`

`doctor`

`open`

Use from an AI agent

Exit codes

`sovseal login` — linking a device

Configuration

Guarantees