# CLI

Command-line interface reference.

SurrealDB Agent Memory ships two binaries:

| Binary | Role |
| --- | --- |
| **`spectrond`** | Server (runs in your container or cluster): `api`, `worker`, `scheduler`, `management`, `bootstrap` |
| **`spectron`** | Client: `remember`, `recall`, `chat`, `documents`, provisioning helpers |

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

> [!NOTE]
> Both binaries carry **Spectron**, the project name SurrealDB Agent Memory was developed under. The product name changed ahead of the executables, which will be renamed in a future release.

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

```bash
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:

```bash
spectron upgrade
```

### Manual download

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

```bash
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:

```bash
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:

| Flag | Environment variable | Description |
| --- | --- | --- |
| `--url` / `-u` | `SPECTRON_URL` | Server base URL (for example `http://localhost:9090`) |
| `--api-key` / `-a` | `SPECTRON_API_KEY` | Context API key |
| `--context-id` / `-c` | `SPECTRON_CONTEXT_ID` | Context id in `/api/v1/{context_id}/...` |

```bash
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:

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

```bash
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:

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

```bash
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](/docs/agent-memory/quickstarts/hosted.md) and [CLI](#connection-flags-client) reference below.

### Production roles

```bash
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:

| Flag | Env | Default |
| --- | --- | --- |
| `--connection-string` | `SURREALDB_CONNECTION` | - |
| `--embeddings-api-key` | `SPECTRON_EMBEDDINGS_API_KEY` | - |
| `--bind-address` | `SPECTRON_BIND_ADDRESS` | `0.0.0.0:9090` |
| `--object-store-url` | `SPECTRON_OBJECT_STORE_URL` | - |

---

## `spectron` - data plane

### Unified verbs

| Command | REST equivalent |
| --- | --- |
| `spectron remember "…"` | `POST /api/v1/{ctx}/facts` |
| `spectron recall "…"` | `POST /api/v1/{ctx}/query` |
| `spectron context "…"` | `POST /api/v1/{ctx}/context` |
| `spectron chat [message]` | `POST /api/v1/{ctx}/chat` |
| `spectron reflect "…"` | `POST /api/v1/{ctx}/reflect` |
| `spectron forget "…"` | `POST /api/v1/{ctx}/forget` |

`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

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

```bash
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`](https://github.com/supermemoryai/install-mcp). See the [MCP server install guide](/docs/agent-memory/integrations/mcp-server/install.md).

### Operator provisioning

```bash
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:

| Binary | Transport | Flag reads | Default port |
| --- | --- | --- | --- |
| `spectrond` (`contexts`, `principals`, `keys`) | gRPC | `SPECTRON_MANAGEMENT_GRPC_URL` | `9091` |
| `spectron` (thin client) | REST | `SPECTRON_MANAGEMENT_URL` | `9090` |

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

> [!NOTE]
> Point `spectrond` at the REST port and the call fails with `grpc-status header
> missing, mapped from HTTP status code 404`. The endpoint is reachable; it
> speaks the other protocol. Both servers run at full parity, so the choice is
> transport only.

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

| Command | Description |
| --- | --- |
| `spectron tui` | Four-pane workbench: input, entity tree, trace timeline, inspector (`Tab` cycles panes). `--session <id>` pins a session; `--replay <path>` plays a recorded jsonl without HTTP. |
| `spectron repl` | Interactive REPL: bare lines and **`/remember`** write facts (`infer: full`); `/recall`, `/chat`, `/inspect`, `/scope`, `/as-of`, `/upload`, `/forget`, `/record`; tab completion from prior responses. Colour is on when stdout is a terminal; pass **`--ascii`** for plain output (same flag as `spectron tui`). |

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:

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