CLI

Spectron 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; start with Docker.

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

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 Spectron container or host image.

`bootstrap`

One-time control-plane initialisation. Prints management and context API keys.

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

Development runtime

Local bring-up runs api + worker + scheduler in one process (not for production):

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

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

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

spectron mcp

Prints JSON for Claude Desktop / Cursor and a Claude Code one-liner.

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

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: `/recall`, `/inspect`, `/scope`, `/as-of`, `/upload`, `/forget`, `/record`, tab completion from prior responses.

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.