CLI

Spectron ships two binaries:

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

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-.windows-amd64.zip` from `https://download.surrealdb.com/spectron//` (use `latest.txt` for ``), 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 ``.

spectrond — server (operators)

Run inside the Spectron 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 documents query "return policy"

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

spectron 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):

export SPECTRON_MANAGEMENT_URL=http://localhost:9095
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_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.

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.