CLI Commands

The opentabs CLI is the single entry point for everything platform-side: starting the server, managing plugins, checking status, viewing logs, and rotating secrets. I wanted one command that handles all of it, so you never have to remember which tool does what. Install it globally:

npm install -g @opentabs-dev/cli

Global options

opentabs start

Start the MCP server in production mode.

opentabs start [options]

On first run, opentabs start auto-initializes the ~/.opentabs/ directory:

1. Creates ~/.opentabs/config.json (plugin and tool settings)
2. Generates authentication secret in ~/.opentabs/extension/auth.json
3. Installs the Chrome extension files to ~/.opentabs/extension/
4. Prints first-time setup instructions (load the extension, configure your MCP client)

On subsequent runs, the extension is updated if the CLI version has changed.

Server output is written to both the terminal and ~/.opentabs/server.log. The process exits if the port is already in use.

# Start on default port
opentabs start
 
# Custom port
opentabs start --port 3000
 
# Start in the background (use opentabs stop to stop)
opentabs start --background

opentabs stop

Stop the background MCP server.

opentabs stop [options]

Reads the PID from ~/.opentabs/server.pid (written by opentabs start --background), sends SIGTERM to the process, and waits up to 5 seconds for it to exit. The PID file is cleaned up after the server stops. If no PID file exists, falls back to a health-check probe on the configured port; if the server is running but was not started with --background, it cannot be stopped this way — use Ctrl+C in the terminal where it is running.

opentabs stop
 
opentabs stop --port 3000

opentabs status

Show MCP server status and connected plugins. Running opentabs with no subcommand is equivalent to opentabs status.

opentabs status [options]
opentabs          # same as opentabs status

Displays server version, SDK version, uptime, extension connection, MCP client count, plugin count, total tool count, and per-plugin details (tab state, tool count, source).

Tab states are color-coded: ready (green), unavailable (yellow), closed (dim). Failed plugins are listed separately with their error messages.

opentabs status
opentabs status --json
opentabs status --port 3000

opentabs audit

Show recent tool invocation history from the server's in-memory audit log.

opentabs audit [options]

Each entry shows the timestamp, tool name, success/failure status, and duration. Failed entries include the error code, category, and message when using --json.

The server maintains the last 500 tool invocations in memory. The audit log resets when the server restarts. Use --file to read from the persistent disk log at ~/.opentabs/audit.log, which survives server restarts.

# Show last 20 invocations
opentabs audit
 
# Show last 50, filtered to one plugin
opentabs audit --limit 50 --plugin slack
 
# Filter by tool name
opentabs audit --tool slack_send_message
 
# Show invocations from the last hour
opentabs audit --since 1h
 
# Combine filters
opentabs audit --tool slack_send_message --since 30m
 
# Read from persistent disk log
opentabs audit --file
 
# Raw JSON output
opentabs audit --json

opentabs doctor

Run diagnostic checks on your OpenTabs setup.

opentabs doctor [options]

Performs the following checks:

1. Runtime — reports the installed Node.js version
2. Browser — checks that a Chromium-based browser is installed (Chrome, Chromium, Edge, or Brave)
3. Config file — checks ~/.opentabs/config.json exists
4. Auth secret — verifies ~/.opentabs/extension/auth.json contains a valid secret
5. MCP server health — fetches the /health endpoint (3s timeout)
6. Extension connection — checks if the Chrome extension is connected via WebSocket
7. Extension installed — verifies ~/.opentabs/extension/manifest.json exists
8. Extension version — compares installed extension version to CLI version
9. MCP client config — checks Claude Code, Cursor, OpenCode, and Windsurf MCP configuration files for correct server entries
10. Local plugins — for each local plugin, checks that dist/tools.json and dist/adapter.iife.js exist
11. npm plugins — verifies npm-discovered plugins reported by the server are loading correctly

Results are shown as a checklist with pass (✓), warning (!), and error (✗) indicators. Exits with code 1 if any fatal check fails.

opentabs doctor
opentabs doctor --port 3000

opentabs logs

Tail the MCP server log output.

opentabs logs [options]

Reads from ~/.opentabs/server.log. By default, prints recent lines and exits. Use -f or --follow to tail the file for new output in real time. The --plugin flag filters to lines containing [plugin:<name>], showing only log entries from that plugin.

# Show recent log lines and exit
opentabs logs
 
# Follow logs in real time
opentabs logs --follow
 
# Show last 100 lines and follow
opentabs logs --lines 100 -f
 
# Show only Slack plugin logs
opentabs logs --plugin slack

opentabs plugin

Manage plugins. Has five subcommands: search, list, install, remove, and create.

opentabs plugin search

Search the npm registry for available OpenTabs plugins.

opentabs plugin search [query]

Each result shows the package name, version, description, and author. Install a found plugin globally to enable auto-discovery:

# Search for plugins
opentabs plugin search slack
 
# List all available plugins
opentabs plugin search
 
# Install a discovered plugin
npm install -g opentabs-plugin-slack

opentabs plugin create

Scaffold a new plugin project.

opentabs plugin create [name] [options]

When run without arguments, enters interactive mode and prompts for the plugin name, domain, display name, and description. Generates a standalone npm package with TypeScript config, a scaffolded plugin class, and an example tool. The plugin is auto-registered in ~/.opentabs/config.json on first build.

The standalone @opentabs-dev/create-plugin package provides the same functionality:

npx @opentabs-dev/create-plugin my-plugin --domain .example.com --display "My App"

opentabs plugin list

List installed plugins. Works in online mode (fetches from the running server) and offline mode (reads from config and global npm packages). Alias: opentabs plugin ls

opentabs plugin list [options]

When the server is running, displays each plugin's name, display name, tab state (color-coded), tool count, source (npm or local), and SDK version. When the server is not running, falls back to scanning ~/.opentabs/config.json and global npm packages.

# List all installed plugins
opentabs plugin list
 
# Machine-readable output
opentabs plugin list --json

opentabs plugin install

Install a plugin from npm. Alias: opentabs plugin add

opentabs plugin install <name>

Shorthand names are resolved by checking the official scoped package first (@opentabs-dev/opentabs-plugin-slack), then falling back to the community unscoped package (opentabs-plugin-slack). Runs npm install -g under the hood. If the MCP server is running, it is notified via POST /reload to pick up the new plugin immediately.

# Install using shorthand
opentabs plugin install slack
 
# Install using full package name
opentabs plugin install opentabs-plugin-slack
 
# Install a scoped community plugin
opentabs plugin install @my-org/opentabs-plugin-custom

opentabs plugin remove

Remove a globally installed plugin. Alias: opentabs plugin rm

opentabs plugin remove <name>

Runs npm uninstall -g and also removes matching entries from the localPlugins array in ~/.opentabs/config.json. If the MCP server is running, it is notified via POST /reload.

# Remove using shorthand
opentabs plugin remove slack --confirm
 
# Remove using full package name
opentabs plugin remove opentabs-plugin-slack --confirm

opentabs config

View and manage configuration. Has five subcommands: show, set, path, reset, and rotate-secret.

opentabs config show

Display the current configuration (secret redacted). Alias: opentabs config get

opentabs config show [options]

opentabs config show
opentabs config show --json
opentabs config show --show-secret

opentabs config set

Set a configuration value.

opentabs config set <key> [value]

# Set a tool to auto-approve (no confirmation prompt)
opentabs config set tool-permission.slack.send_message auto
 
# Disable a tool entirely
opentabs config set tool-permission.slack.send_message off
 
# Set a plugin default to require approval for all its tools
opentabs config set plugin-permission.slack ask
 
# Change the server port
opentabs config set port 3000
 
# Register a local plugin
opentabs config set localPlugins.add /path/to/my-plugin
 
# Register a local plugin path that does not yet exist
opentabs config set localPlugins.add /future/path/my-plugin --force
 
# Unregister a local plugin
opentabs config set localPlugins.remove /path/to/my-plugin

opentabs config path

Print the config file path.

opentabs config path
# Output: /Users/you/.opentabs/config.json

opentabs config reset

Delete the config file. The server regenerates a fresh config on the next opentabs start.

opentabs config reset --confirm

The config file stores local plugin paths, tool overrides, and permissions. The authentication secret in ~/.opentabs/extension/auth.json is not affected.

opentabs config rotate-secret

Generate a new 256-bit random secret and write it to auth.json.

opentabs config rotate-secret

If the MCP server is running, it is notified via POST /reload using the old secret. The server then notifies the Chrome extension via WebSocket, and the extension auto-reconnects with the new secret — no manual reload required. MCP clients need to update their configuration with the new secret value.

# Rotate the secret
opentabs config rotate-secret --confirm

opentabs update

Update the OpenTabs CLI to the latest version.

opentabs update

Checks the currently installed version against the latest published version on npm. If an update is available, runs npm install -g @opentabs-dev/cli@<version> to perform the upgrade.

If the MCP server is running when you update, it needs to be restarted to use the new version. Use the --port global option if the server is on a non-default port.

# Update to the latest version
opentabs update
 
# Then restart the MCP server if it was running
opentabs start

Plugin Developer CLI

The opentabs-plugin CLI is for plugin developers. Install it with the plugin SDK:

npm install -g @opentabs-dev/plugin-tools

Or use it as a local dev dependency via npm run build inside your plugin project (the scaffolded project from @opentabs-dev/create-plugin includes it).

opentabs-plugin build

Build the current plugin directory — generates dist/tools.json and bundles the adapter IIFE.

opentabs-plugin build [options]

Reads plugin metadata from package.json's opentabs field and serializes tool schemas from the plugin module. On success, notifies the running MCP server via POST /reload so the updated plugin is picked up immediately without a server restart.

# Build once
opentabs-plugin build
 
# Watch and rebuild on changes
opentabs-plugin build --watch

opentabs-plugin inspect

Pretty-print the built plugin manifest (dist/tools.json). Requires opentabs-plugin build to have been run first.

opentabs-plugin inspect [options]

Displays the plugin name, version, SDK version, and tool count. For each tool, shows the display name, description, and input/output field names and types.

# Pretty-print the manifest
opentabs-plugin inspect
 
# Output raw JSON
opentabs-plugin inspect --json

Last Updated: 10 Mar, 2026