CLI Reference

Every OpalServe command, every flag, every exit code. Use --help on any command for inline detail.

This page lists every command. Each section shows the canonical signature, the most common invocations, and any options worth knowing about.

Every command supports --help for inline documentation. Every command exits 0 on success and 1 on any handled error. A non-zero, non-1 exit code (for example 2) means an unhandled crash, please open an issue.

Global options

These work on every command:

Option	Description
`-c, --config <path>`	Path to config file
`-v, --version`	Print version
`-h, --help`	Show help

Setup

`opalserve init`

Interactive setup wizard. Writes a config file and optionally registers your first MCP server. See Getting Started.

opalserve init
opalserve init --config ./my-config.json --mode local

`opalserve start`

Starts the registry server. Connects to every configured MCP server, indexes their tools, exposes the HTTP API and the MCP gateway.

opalserve start
opalserve start --port 8080 --host 0.0.0.0
opalserve start --mode team-server
opalserve start --mcp           # MCP-only stdio mode
opalserve start --no-dashboard  # disable the web dashboard

`opalserve status`

Prints the current state: mode, uptime, server count, tool count, active users, API URL.

`opalserve doctor`

Diagnostic check. Reports Node version, config validity, port availability, environment variables, and, if the Team Brain is enabled, Python availability and graphiti-core import status.

Servers

`opalserve server list`

Lists registered servers with their status, transport, and tool count. --json for machine-readable output.

`opalserve server add`

Registers a new MCP server.

opalserve server add                                   # interactive
opalserve server add --name files --stdio "npx -y @modelcontextprotocol/server-filesystem /home"
opalserve server add --name remote --url https://mcp.example.com/sse --transport sse
opalserve server add --name github \
  --stdio "npx -y @modelcontextprotocol/server-github" \
  --env GITHUB_TOKEN=ghp_xxx \
  --tags code,github \
  --description "GitHub repositories"

Option	Description
`-n, --name <name>`	Server name (lowercase, hyphens)
`-s, --stdio <cmd>`	Stdio command string
`-u, --url <url>`	Remote server URL
`-t, --transport <type>`	`sse` or `streamable-http`
`-e, --env <KEY=VAL...>`	Repeatable environment variables
`--tags <tags>`	Comma-separated
`--description <text>`	Human-readable label

`opalserve server remove <name>`

Removes a server and its indexed tools. Add --force to skip the confirmation prompt.

`opalserve health`

Per-server health: connection status, latency, tool count. --server <name> to scope.

Tools

`opalserve tools list`

Lists every indexed tool grouped by server. --server <names> to filter, --json for machine output.

`opalserve tools search <query>`

Full-text search across tool names and descriptions.

opalserve tools search "create issue"
opalserve tools search "file" --limit 5 --server my-files

Editor link

`opalserve link <editor>`

Configures one editor, claude, cursor, or cline, to use OpalServe as its MCP server. Backs up the editor's existing config before writing.

opalserve link claude
opalserve link --all       # all detected editors
opalserve link --status    # show what's currently linked, no changes

The editor's command is set to npx -y opalserve mcp by default. Override with the OPALSERVE_LINK_COMMAND env var.

Drift

`opalserve drift`

Compares the local config to the team config and prints a four-state report, match, drift, missing, local-only. See Drift Detection.

Auth

`opalserve login <url>`

Authenticates against a team server. Stores credentials locally. --api-key <key> to skip the email/password prompt.

`opalserve logout`

Clears stored credentials.

`opalserve whoami`

Prints user, team, role, and connected server.

`opalserve sync`

Pulls the current server list and tool index from the team server. --force ignores the local cache.

Team Brain

`opalserve enable graph`

Wizard that detects Python 3.10+, asks you to pick an LLM provider (OpenAI / Anthropic / Ollama / skip), optionally pip-installs graphiti-core[kuzu], and writes the config to ~/.opalserve/graph/config.json.

`opalserve disable graph`

Stops the Graphiti sidecar. Data is preserved.

`opalserve graph status`

Sidecar PID, LLM provider, configured backend, episode count.

`opalserve graph spawn`

Manual sidecar restart (useful after editing config).

`opalserve graph reset`

Wipes graph data after a confirmation prompt.

`opalserve graph add <text>`

Adds a free-form episode to the graph. Useful for marking decisions explicitly.

`opalserve graph search <query>`

Hybrid (BM25 + vector + traversal) graph search. The same operation that linked editors call via the graph_search MCP tool.

Admin (team-server only)

These require the admin role.

`opalserve admin init`

Initializes a team-server install: creates the first admin account, generates the JWT secret, switches mode to team-server.

`opalserve admin stats`

Usage statistics, total requests, tool calls, active users, top tools. --period 1h | 24h | 7d | 30d (default 24h).

`opalserve admin users`

Lists every registered user with role and last activity. --json for machine output.

`opalserve admin invite <email>`

Creates an invitation link.

opalserve admin invite alice@company.com --role developer --expires 7d

Roles: admin, developer, viewer.

`opalserve admin permissions`

Set or inspect a user's role and per-server access list.

`opalserve admin limits`

View or set rate limits, globally or per-user.

`opalserve admin audit`

Tail the audit log, every tool call, every auth event, every config change with timestamp and actor.

PreviousArchitecture NextConfiguration