CLI

SurrealDB Agent Memory ships two binaries:

The spectron CLI is what integrators install locally. spectrond is operated via Docker, Kubernetes, or your platform team.

Installing the CLI

Prebuilt spectron binaries for macOS, Linux, and Windows are published to download.surrealdb.com under a version path. On macOS and Linux the install script resolves the latest version, verifies the checksum, and installs to /usr/local/bin (or ~/.local/bin when that is not writable):

curl -fsSL https://download.surrealdb.com/spectron/install.sh | sh

Set SPECTRON_INSTALL_DIR to install somewhere else. Once installed, the CLI updates itself in place, so you do not need to re-run the script:

spectron upgrade

Manual download

To install by hand, resolve the current version from the pointer file, then download the archive for your platform:

VERSION=$(curl -fsSL https://download.surrealdb.com/spectron/latest.txt)
BASE="https://download.surrealdb.com/spectron/${VERSION}/spectron-${VERSION}"

# macOS (Apple Silicon)
curl -fsSL "${BASE}.darwin-arm64.tgz" | tar -xz && sudo mv spectron /usr/local/bin/

# macOS (Intel)
curl -fsSL "${BASE}.darwin-amd64.tgz" | tar -xz && sudo mv spectron /usr/local/bin/

# Linux (x86_64)
curl -fsSL "${BASE}.linux-amd64.tgz" | tar -xz && sudo mv spectron /usr/local/bin/

# Linux (arm64)
curl -fsSL "${BASE}.linux-arm64.tgz" | tar -xz && sudo mv spectron /usr/local/bin/

On Windows, download spectron-<version>.windows-amd64.zip from https://download.surrealdb.com/spectron/<version>/ (use latest.txt for <version>), extract it, and put the folder containing spectron.exe on PATH. spectron upgrade works on Windows once a first install is on PATH.

Verifying the download

Each archive has a .sha256 sidecar next to it:

shasum -a 256 -c spectron-*.tgz.sha256   # macOS / Linux

The binaries are unsigned. Downloading with curl avoids the macOS Gatekeeper quarantine flag that a browser download adds; if you did download through a browser, clear it first with xattr -d com.apple.quarantine ./spectron.

Connection flags (client)

Most spectron subcommands accept:

spectron login --url http://localhost:9090 \
  --api-key "$SPECTRON_API_KEY" \
  --context-id dev

Stores a named profile for later commands.

Local config and secrets

spectron login and spectron config set write profiles to ~/.config/spectron/config.toml with owner-only permissions (0600 on Unix). config set prints the key name, never the value. To display a stored secret:

spectron config get api_key --reveal

Without --reveal, api_key is shown as <hidden>.

spectrond - server (operators)

Run inside the SurrealDB Agent Memory container or host image.

bootstrap

One-time control-plane initialisation. Prints management and context API keys. Fails if the Context already exists.

docker compose exec spectron spectrond bootstrap \
  --connection-string "ws://surrealdb:8000;root;root"

Pin a stable Context API key (instead of a random mint) with --context-api-key or SPECTRON_API_KEY, mirroring how --management-api-key / SPECTRON_MANAGEMENT_API_KEY pins the management key. Validate the value with spectrond generate-key first.

Development runtime

Local bring-up runs api + worker + scheduler in one process (not for production). Pass --bootstrap to seed the Context on an empty database, print the keys, then serve - on later restarts against the same database the seed is a no-op (logs and skips) instead of erroring:

spectrond dev start --bootstrap \
  --connection-string "$SURREALDB_CONNECTION" \
  --bind-address 0.0.0.0:9090 \
  --context-api-key "$SPECTRON_API_KEY"

Without --bootstrap, run standalone spectrond bootstrap once, then dev start as before.

spectrond dev start \
  --connection-string "$SURREALDB_CONNECTION" \
  --bind-address 0.0.0.0:9090

Export LLM provider keys before dev start if you need extraction or chat (infer: full is not embeddings-only). A bare spectrond start alias exists for older single-process layouts but is hidden from --help - prefer dev start or the split production roles below.

For a full provisioning walkthrough (bootstrap, scopes, principals, keys, upload, query), follow the Hosted quickstart and CLI reference below.

Production roles

spectrond api start …          # REST + MCP
spectrond worker start …       # job queue consumer
spectrond scheduler start …    # periodic background work
spectrond management start …   # management REST only

Common flags:

spectron - data plane

Unified verbs

forget supports --dry-run to preview matches without expiring records.

remember flags: --infer full|triples|preview|none, --from-file, --transcript, --scope org/acme/user/alice, --extract whole_conversation|per_message (batch).

recall flags: --limit, --mode hybrid|vector|bm25|graph, --include facts,passages. Pass scope on the REST /query body - the CLI does not expose --scope on recall today.

Unsupported CLI flags (rejected with a clear error): remember --confidence, --trust, --location; recall --min-trust; spectron lifecycle expire --older-than (expiry thresholds are configured per Context, not per CLI invocation). Use REST or management API where those controls exist.

Documents

spectron documents upload ./manual.pdf --scope org/acme/team/eng --label team=eng
spectron ingest ./folder --scope org/acme/team/eng --label team=eng
spectron documents list
spectron recall "return policy" --include passages

--scope on upload narrows tagging to a path within the caller's memory:write region (same semantics as remember --scope). --label may be repeated for key=value tags stamped on the document and chunks. Omit --scope to use the full write region.

Sessions, entities, traces

spectron sessions list
spectron entities show Person/alice
spectron traces show <trace_id>

MCP server

The MCP server is served at /mcp on the same host and port as the REST API - no CLI step is needed. Point your client at that endpoint, or run install-mcp. See the MCP server install guide.

Operator provisioning

spectrond contexts create …
spectrond keys generate-key …
spectrond keys rotate <context_id> <key_name> [--expires-in <seconds>]

Create principals (management API - not the data-plane Context key). The two
binaries reach the control plane over different transports, so each takes its own
URL:

export SPECTRON_MANAGEMENT_GRPC_URL=http://127.0.0.1:9091   # spectrond speaks gRPC
export SPECTRON_MANAGEMENT_URL=http://127.0.0.1:9090        # spectron speaks REST
export SPECTRON_MANAGEMENT_API_KEY=sp-…

spectrond principals create demo "Planner bot" \
  --kind agent \
  --grant memory:read=team/eng \
  --grant memory:write=team/eng \
  --url "$SPECTRON_MANAGEMENT_GRPC_URL" \
  --api-key "$SPECTRON_MANAGEMENT_API_KEY"

# thin client (reads SPECTRON_MANAGEMENT_* + SPECTRON_CONTEXT_ID from env)
spectron principals create "Planner bot" --kind agent -c demo \
  --grant memory:read=team/eng --grant memory:write=team/eng

Prints the server-minted principal id. Mint an agent key for that principal via the management API or spectrond keys generate-key.

The management REST default (9090) is the same port the end-user API server
uses. When you run both on one host, override one of them - for example
--bind-address 0.0.0.0:9095 --grpc-bind-address 0.0.0.0:9096 on
spectrond management start - and use the ports you chose in the variables
above.

Terminal workbench

Scope in the REPL and TUI uses slash paths (org/acme/user/alice), matching the wire ScopeSet.

REPL triple syntax

Interactive mode supports structured triple writes:

/fact entity=Person/Alice attr=role val=CTO

Uses the same triple syntax as spectron remember --triple (infer=triples).

Run spectron --help for the full command tree.