CLI Reference

Complete reference for every OpalServe CLI command. All commands support --help for inline documentation.

Global Options

These options are available on every command:

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

`opalserve init`

Interactive setup wizard. Creates a configuration file and optionally registers your first MCP server.

Usage:

bash

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

Options:

Option	Description
`--config <path>`	Where to write the config file
`--mode <mode>`	Skip the mode prompt: `local`, `team-server`, `team-client`

Example:

bash

$ opalserve init
  Welcome to OpalServe v3.0.0

  ? Where should we store your config? ~/.opalserve/config.json
  ? Select mode: local
  ? HTTP API port: 3456
  ? Add a starter MCP server? filesystem
  ? Directory to expose: /home/user/projects

  Configuration written to ~/.opalserve/config.json

`opalserve start`

Start the registry server. Connects to all configured MCP servers, indexes their tools, and starts the HTTP API.

Usage:

bash

opalserve start
opalserve start --port 8080 --host 0.0.0.0
opalserve start --mode team-server
opalserve start --mcp

Options:

Option	Description
`-p, --port <port>`	Override HTTP API port
`-h, --host <host>`	Override HTTP API host
`--mode <mode>`	Override operating mode
`--mcp`	Start in MCP gateway mode (stdio transport for MCP clients)
`--no-dashboard`	Disable the web dashboard

`opalserve status`

Show current registry status: server count, tool count, connection states, uptime, and mode.

Usage:

bash

opalserve status

Example output:

  OpalServe v3.0.0 — running (team-server mode)

  Uptime:   4h 23m
  Servers:  3 connected, 0 errored
  Tools:    28 indexed
  Users:    5 active
  API:      http://0.0.0.0:3456

`opalserve server list`

List all registered MCP servers with their status, tool count, and transport type.

Usage:

bash

opalserve server list
opalserve server list --json

Options:

Option	Description
`--json`	Output as JSON

`opalserve server add`

Usage:

bash

# Interactive
opalserve server add

# Stdio server
opalserve server add --name my-files --stdio "npx -y @modelcontextprotocol/server-filesystem /home"

# Remote SSE server
opalserve server add --name remote --url https://mcp.example.com/sse --transport sse

# With environment variables
opalserve server add --name github \
  --stdio "npx -y @modelcontextprotocol/server-github" \
  --env GITHUB_TOKEN=ghp_xxx

# With tags and description
opalserve server add --name github \
  --stdio "npx -y @modelcontextprotocol/server-github" \
  --env GITHUB_TOKEN=ghp_xxx \
  --tags code,github \
  --description "GitHub repositories"

Options:

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

`opalserve server remove <name>`

Remove a registered server and its indexed tools.

Usage:

bash

opalserve server remove my-github
opalserve server remove my-github --force

Options:

Option	Description
`--force`	Skip confirmation prompt

`opalserve tools list`

List all discovered tools grouped by server.

Usage:

bash

opalserve tools list
opalserve tools list --server github
opalserve tools list --json

Options:

Option	Description
`-s, --server <names>`	Filter by server (comma-separated)
`--json`	Output as JSON

`opalserve tools search <query>`

Full-text search across all indexed tools.

Usage:

bash

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

Options:

Option	Description
`-l, --limit <n>`	Max results (default: 10)
`-s, --server <names>`	Filter by server (comma-separated)
`--json`	Output as JSON

Example:

bash

$ opalserve tools search "create issue"
  Search results for "create issue" (2 matches)

  github:create_issue       Create a new issue in a repository
  github:create_pull_request Create a new pull request

`opalserve health`

Run health checks on all registered servers. Shows connection status, latency, and tool count.

Usage:

bash

opalserve health
opalserve health --server my-github

Options:

Option	Description
`-s, --server <name>`	Check a specific server

Authentication Commands

These commands manage your identity when connecting to a team server.

`opalserve login <url>`

Authenticate with a team server. Stores credentials in your local config.

Usage:

bash

opalserve login https://opalserve.company.com
opalserve login https://opalserve.company.com --api-key osk_abc123

Options:

Option	Description
`--api-key <key>`	Authenticate with an API key instead of email/password

Example:

bash

$ opalserve login https://opalserve.company.com
  ? Email: alice@company.com
  ? Password: ********
  Logged in as alice@company.com
  Syncing servers... 3 servers available

`opalserve logout`

Clear stored credentials and disconnect from the team server.

Usage:

bash

opalserve logout

`opalserve whoami`

Display the current authenticated user, team, and role.

Usage:

bash

opalserve whoami

Example:

bash

$ opalserve whoami
  User:   alice@company.com
  Team:   Acme Engineering
  Role:   developer
  Server: https://opalserve.company.com

Sync Commands

`opalserve sync`

Synchronize your local tool index with the team server. Downloads the latest server list and tool definitions.

Usage:

bash

opalserve sync
opalserve sync --force

Options:

Option	Description
`--force`	Force a full re-sync (ignores cache)

Context / Knowledge Base Commands

Manage the shared knowledge base that AI tools can query.

`opalserve context add <path>`

Add a document or directory to the knowledge base.

Usage:

bash

# Add a single file
opalserve context add ./docs/architecture.md

# Add a directory (recursively)
opalserve context add ./docs/

# Add with metadata
opalserve context add ./runbook.md --tags ops,runbook --title "Incident Runbook"

Options:

Option	Description
`--tags <tags>`	Comma-separated tags for filtering
`--title <title>`	Human-readable document title
`--recursive`	Include subdirectories (default for directories)
`--pattern <glob>`	Filter files by glob pattern (e.g., `"*.md"`)

`opalserve context list`

List all documents in the knowledge base.

Usage:

bash

opalserve context list
opalserve context list --tags runbook
opalserve context list --json

Options:

Option	Description
`--tags <tags>`	Filter by tags
`--json`	Output as JSON

`opalserve context search <query>`

Search the knowledge base using full-text search.

Usage:

bash

opalserve context search "deployment process"
opalserve context search "database migration" --limit 5

Options:

Option	Description
`-l, --limit <n>`	Max results (default: 10)
`--tags <tags>`	Filter by tags

`opalserve context remove <id>`

Remove a document from the knowledge base.

Usage:

bash

opalserve context remove doc_abc123
opalserve context remove --all --tags old-docs

Options:

Option	Description
`--all`	Remove all matching documents (requires `--tags`)
`--tags <tags>`	Filter by tags when using `--all`

Admin Commands

These commands are only available to users with the admin role. In local mode, all commands are available without authentication.

`opalserve admin init`

Initialize the team server. Creates the first admin account and generates the JWT secret.

Usage:

bash

opalserve admin init

Example:

bash

$ opalserve admin init
  Initializing OpalServe team server...

  ? Admin email: admin@company.com
  ? Admin password: ********
  ? Team name: Acme Engineering

  Admin account created.
  JWT secret generated and stored.
  Config updated to team-server mode.

  Start the server with: opalserve start

`opalserve admin stats`

Display usage statistics: total requests, tool calls, active users, and top tools.

Usage:

bash

opalserve admin stats
opalserve admin stats --period 7d
opalserve admin stats --json

Options:

Option	Description
`--period <period>`	Time period: `1h`, `24h`, `7d`, `30d` (default: `24h`)
`--json`	Output as JSON

Example:

bash

$ opalserve admin stats --period 7d
  Usage Statistics (last 7 days)

  Total requests:    2,847
  Tool calls:        1,203
  Active users:      8
  Unique tools used: 15

  Top tools:
    github:create_issue          187 calls
    files:read_file              156 calls
    github:search_repositories   134 calls

`opalserve admin users`

List all registered users with their roles and last activity.

Usage:

bash

opalserve admin users
opalserve admin users --json

`opalserve admin invite <email>`

Send an invitation to join the team server.

Usage:

bash

opalserve admin invite alice@company.com
opalserve admin invite alice@company.com --role admin

Options:

Option	Description
`--role <role>`	Assign a role: `admin`, `developer`, `viewer` (default: team default)
`--expires <duration>`	Invite expiry: `1h`, `24h`, `7d` (default: `7d`)

Example:

bash

$ opalserve admin invite alice@company.com --role developer
  Invitation created.
  Share this link: https://opalserve.company.com/invite/abc123xyz
  Expires: 2026-04-19T00:00:00Z

`opalserve admin limits`

View and configure rate limits.

Usage:

bash

# View current limits
opalserve admin limits

# Set limits for a user
opalserve admin limits --user alice@company.com --max-requests 200 --tool-call-limit 100

# Set global defaults
opalserve admin limits --max-requests 100 --tool-call-limit 50

Options:

Option	Description
`--user <email>`	Target a specific user (omit for global defaults)
`--max-requests <n>`	Max requests per window
`--tool-call-limit <n>`	Max tool calls per window
`--window <ms>`	Window duration in milliseconds

`opalserve admin permissions`

Manage user roles and permissions.

Usage:

bash

# View permissions for a user
opalserve admin permissions --user alice@company.com

# Change a user's role
opalserve admin permissions --user alice@company.com --role admin

# Restrict a user to specific servers
opalserve admin permissions --user bob@company.com --servers github,files

Options:

Option	Description
`--user <email>`	Target user
`--role <role>`	Set role: `admin`, `developer`, `viewer`
`--servers <names>`	Comma-separated list of allowed servers (empty = all)

CLI Reference ​

Global Options ​

opalserve init ​

opalserve start ​

opalserve status ​

opalserve server list ​

opalserve server add ​

opalserve server remove <name> ​

opalserve tools list ​

opalserve tools search <query> ​

opalserve health ​

Authentication Commands ​

opalserve login <url> ​

opalserve logout ​

opalserve whoami ​

Sync Commands ​

opalserve sync ​

Context / Knowledge Base Commands ​

opalserve context add <path> ​

opalserve context list ​

opalserve context search <query> ​

opalserve context remove <id> ​

Admin Commands ​

opalserve admin init ​

opalserve admin stats ​

opalserve admin users ​

opalserve admin invite <email> ​

opalserve admin limits ​

opalserve admin permissions ​

CLI Reference

Global Options

`opalserve init`

`opalserve start`

`opalserve status`

`opalserve server list`

`opalserve server add`

`opalserve server remove <name>`

`opalserve tools list`

`opalserve tools search <query>`

`opalserve health`

Authentication Commands

`opalserve login <url>`

`opalserve logout`

`opalserve whoami`

Sync Commands

`opalserve sync`

Context / Knowledge Base Commands

`opalserve context add <path>`

`opalserve context list`

`opalserve context search <query>`

`opalserve context remove <id>`

Admin Commands

`opalserve admin init`

`opalserve admin stats`

`opalserve admin users`

`opalserve admin invite <email>`

`opalserve admin limits`

`opalserve admin permissions`