CLI overview

The CLI installs as worktable, with wtb as a shorthand — every example below works with either. Bare worktable runs launch: start (or reuse) the server and open the app.

This page is the guided tour; the CLI command reference lists every command and flag, generated from the CLI itself.

Run it

worktable                      # start or reuse, open the browser
worktable launch --foreground  # run in this terminal, Ctrl+C to stop
worktable launch --background  # run as a managed background service
worktable --version

Set it up

worktable setup            # interactive: workspace, run mode, agents
worktable setup --yes      # accept defaults, no prompts

Setup is re-runnable. It’s also where reachability lives — worktable setup --reachable binds all interfaces, protects the web app with an owner password, and mints a bearer token for MCP.

Inspect it

worktable status   # server, workspace, service, and agent state
worktable doctor   # diagnose install problems (--check for scripts)
worktable paths    # resolved runtime paths (--json available)

status also reports which local surface currently owns the server: Desktop, the managed service, or a foreground CLI session. Desktop and the CLI use the same canonical workspace selection and stable endpoint. If Desktop finds an existing CLI installation, it offers to attach or start it instead of creating a second local server. doctor reports an interrupted workspace handoff and the authority paths needed for repair.

Connect agents

worktable mcp setup            # auto-detect and connect installed clients
worktable mcp setup codex      # connect one client
worktable mcp status           # per-client connection state
worktable mcp test             # is the endpoint reachable
worktable mcp repair           # re-apply config for connected clients
worktable mcp print-config vscode

Automatic setup supports Claude Code, ChatGPT / Codex, Cursor, OpenCode, and VS Code. Goose uses mcp print-config; Claude Desktop uses the extension download and guided setup in Settings → Agents → Desktop apps.

For an agent on another machine, worktable agent invite prints a one-line command to run over there, and worktable agent connect <code> redeems a pairing code on the machine running it. See Connect your agent for the walkthrough and Remote access for the pairing flow.

The binary also exposes a hidden provider-facing transport command:

worktable mcp bridge [--url <mcp-url>] [--token-env <name>]

It proxies a Worktable Streamable HTTP MCP server to stdio using the same bridge bundled in the Claude Desktop extension. The URL can come from WORKTABLE_MCP_URL; the token environment variable defaults to WORKTABLE_MCP_TOKEN. Raw tokens are never accepted on the command line. The existing worktable mcp stdio and worktable --mcp contracts are unchanged.

Manage the service

worktable service status
worktable service restart
worktable service logs -f

install, start, stop, and uninstall complete the set. Service start/restart refuses to run beside a Desktop-owned or foreground CLI host. Desktop can adopt an installed service, switch its workspace transactionally, restart it, and reveal these same logs.

Export or import a workspace

worktable workspace export backup.wtb             # all available history
worktable workspace export backup.wtb --history none
worktable workspace import backup.wtb ~/Restored  # new, independent workspace

Export writes a standard compressed ZIP package with an offline browser (--force replaces an existing regular file). History can be all, age, count, or none; age and count have matching limit flags. Import creates a fresh workspace in a missing or empty directory. Owner-facing replacement lives in Settings → Import & Export. Neither path merges or starts sync. See Import and export a workspace.

Update and remove

worktable update           # update to the latest release
worktable update --check   # just tell me if one exists
worktable uninstall        # remove Worktable; your workspace folder stays

uninstall --purge also deletes the workspace folder — the only command that touches your files.

Shell completion

The installer sets up tab completion by default (bash, zsh, fish). If you skipped it or want it later:

worktable completion install        # detects your shell, places the files
worktable completion zsh            # or print the script to wire up yourself