Skip to content

wbuddy CLI

The wbuddy shell CLI: bootstrap, provisioning, app launch, harness surface sync, sidecar lifecycle, and the deliberately scoped local Truth consumer surface. The wb_* gateway remains the agent operations surface.

When to use

user or agent needs to manage the local runtime from the shell, or a user needs to capture, review, query, confirm, or migrate a scoped Truth Store locally

Directions

wbuddy is work-buddy's shell command-line interface: the bootstrap and sidecar-lifecycle ramp. It is for the user (and for setup), not the agent's general operations surface. State operations go through the wb_* MCP gateway (see operations/mcp-gateway), except for the deliberately narrow wbuddy truth local-store consumer surface.

Installed as a console script (wbuddy) via pyproject, also runnable as python -m work_buddy.cli.

Verbs

  • wbuddy start [--foreground] -- start the sidecar. Detached by default (no console window), --foreground runs it in the current terminal. Never starts a second sidecar: if one holds the single-instance lock (running, booting, or wedged), it is reported instead, and a wedged one is replaced with wbuddy restart, not start. A successful detached start then attempts the trusted dashboard-identity recovery described below.
  • wbuddy stop -- stop the running sidecar and its child services, then confirm that no sidecar still holds the single-instance lock. It fails, naming any surviving processes, if one does.
  • wbuddy restart -- stop then start, then attempt trusted dashboard-identity recovery after the app is ready.
  • wbuddy status [--json] -- sidecar liveness, uptime, and per-service health, read from the sidecar state file. Distinguishes booting from wedged, and exits non-zero when not running or wedged. Prints a Runtime: line with the interpreter the daemon runs on, its console, and the interpreter its services run on, and warns when the daemon has no console on Windows, when services would run on pythonw.exe, or when the interpreter pin points outside the project (see architecture/process-execution). Also reports the daemon's dispatch loop: a phase busy past ~2 minutes prints as busy with the running job's name (scheduled work is queued behind it, supervision unaffected), otherwise the time since the last completed dispatch cycle.
  • wbuddy doctor [<component>] [--json] -- render the setup wizard's status, or one component's diagnosis: bootstrap, requirements, health.
  • wbuddy setup -- run bootstrap checks, print the gateway MCP config, and point to the selected harness's generated wb-setup command or skill for interactive feature selection.
  • wbuddy mcp print -- emit the gateway MCP config (HTTP, the gateway port) to stdout.
  • wbuddy harness list [--json] -- list supported agent-host harnesses (claudecode, codexcli), their rulesync target ids, feature projection, browser surface, and selection state.
  • wbuddy harness enable <id> / disable <id> / primary <id> -- update the local harness: selection in config.local.yaml. The harness selection is local-machine state, not a workflow operation.
  • wbuddy harness sync [--target <id> ...] [--dry-run] [--check] [--json] [--output-root <path>] [--no-install-toolchain] -- generate or check agent-host artifacts through pinned rulesync. Ordinary sync and provision install the checksum-verified standalone binary when needed; the opt-out is for controlled development environments. Sync previews paths, backs up existing generated files, rolls back on failure, and projects owned local Codex overrides without clobbering unrelated files. Reports include the pinned rulesync version and the Playwright MCP version when projected. Codex receives rules,mcp,skills,hooks; Claude Code receives rules,mcp,commands,skills,hooks.
  • wbuddy harness doctor [--json] -- report configured, PATH, managed, or pinned-npx rulesync availability and exact-version agreement.
  • wbuddy hook {session-start,user-prompt-submit,post-tool-use,stop} --harness <id> -- internal JSON stdin/stdout lifecycle bridge used by generated native hook files. Users normally do not invoke it directly.
  • wbuddy dashboard [--open] -- print (or open) the dashboard URL.
  • wbuddy dashboard --read-only --port <port> -- serve a separate foreground dashboard on loopback for inspection. The explicit port must be outside the normal service ports (5124, 5126, 5127). This mode installs the process read-only guard before loading the dashboard; it does not open a browser automatically. See services/dashboard for the guard and supported inspection behavior.
  • wbuddy launch -- the terminal/admin form of the shared app-launch operation. It idempotently starts or recovers the sidecar, best-effort ensures the tray when enabled, waits until the React dashboard at /app/ returns successfully, then focuses an existing matching browser tab or opens one. It fails instead of opening a dead page when the app does not become ready. Installed Windows shortcuts, Linux .desktop entries, and Work Buddy.app on macOS reuse this operation through the console-less work_buddy.desktop_launcher, which records <data_root>/logs/desktop_launcher.log and presents a native error surface when available.
  • wbuddy provision [--home ...] [--data-dir ...] [--vault-root ...] [--repos-root ...] [--timezone ...] [--anthropic-key ...] [--harness <id>] [--no-harness] [--allow-experimental-harness] [--no-start] -- the native installer's one-shot entry point. --home targets a specific install dir. It seeds config, relocates mutable state, pins the interpreter, writes secrets and MCP wiring, optionally selects one setup-ready primary harness, installs pinned rulesync, projects the native harness surface, publishes the CLI shim, runs bootstrap checks, and starts the sidecar. Harness projection failure fails provision. Idempotent.
  • wbuddy uninstall -- tear down machine integration: stop the sidecar, remove the login auto-start task, and remove the PATH shim. User data is preserved. The Windows uninstaller and the Linux/macOS artifact uninstall helpers invoke this before removing application files; their explicit remove-data modes are separate from this command.
  • wbuddy autostart {enable,disable,status} -- manage login auto-start of the detached sidecar (Windows Task Scheduler WB-Sidecar, Linux systemd --user unit, macOS launchd agent), via work_buddy/autostart/.
  • wbuddy tray {enable,disable,status,run} -- manage the system-tray icon (needs the tray extra). enable sets tray.enabled, registers the WB-Tray login item, and starts the tray; disable reverses all three; status reports enabled/registered/running; run is the foreground login-item entry point. The tray is a separate process and login item, NOT a sidecar-supervised service -- see services/tray.
  • wbuddy truth {capture,propose,query,confirm,migrate} [--store ...] [--json] -- discover or select a canonical scoped local Truth Store at .wbuddy/cowork and use the frozen consumer surface directly. capture records immutable evidence and an optional quote span, propose writes a profile-valid claim, query exposes current/as-of/review/conflict views, and confirm requires a local-human interactive TTY or an existing human gesture. migrate upgrades the schema of one selected store or every registered store. Detected agent sessions cannot mint an interactive human gesture.

For detached CLI and tray start/restart, identity recovery waits for the React app and has the trusted host mint a fresh one-use dashboard bootstrap. The browser extension first updates an existing app tab without activating it and preserves that tab's document route and query; a correlated response prevents unrelated shared Chrome output from being reported as success. If no handoff is confirmed—including when an already-running older extension worker does not support the path-preserving mutation—Work Buddy uses a fresh grant with the normal browser launch. It never falls back through the older navigation mutation, which could replace a live Co-work document route with the app root, and it never replays a possibly consumed credential. Sidecar lifecycle success remains separate from this best-effort browser handoff: CLI writes an explicit reconnect warning and tray results include identity_reconnect when recovery cannot be confirmed.

When to use

  • First-run bootstrap before MCP is wired: wbuddy setup, wbuddy mcp print.
  • Sidecar lifecycle from the shell instead of python -m work_buddy.sidecar: wbuddy start / stop / restart / status.
  • Terminal launch of the complete local app: wbuddy launch. Installed Windows Start/Desktop shortcuts, Linux application entries, and the macOS app bundle use the console-less wrapper around the same operation.
  • Interactive, domain-by-domain feature selection stays in the generated wb-setup command/skill inside the selected harness because that walk needs an agent. wbuddy setup is its pre-MCP shell-side complement.
  • Local Truth capture, proposal, query, human review, and schema migration: wbuddy truth .... Agents should use the corresponding truth_* MCP skills for lifecycle operations and per-invocation confirmation authority.