Skip to content

wbuddy CLI

The wbuddy shell CLI: bootstrap, provisioning, app launch, harness surface sync, and sidecar lifecycle (start/stop/status/doctor/setup/provision/uninstall/autostart/tray/mcp print/harness). Not the agent operations surface, the wb_* gateway stays that.

When to use

user or agent needs to start/stop/check the sidecar from the shell, run bootstrap setup, or print the MCP config

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 operations surface. Anything that acts on work-buddy state goes through the wb_* MCP gateway (see operations/mcp-gateway), and wbuddy deliberately does not duplicate it.

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. Idempotent for a healthy sidecar: an already-running (or still-booting) sidecar is reported, not duplicated, while a wedged one is taken over.
  • wbuddy stop -- stop the running sidecar and its child services.
  • wbuddy restart -- stop then start.
  • wbuddy status [--json] -- sidecar liveness, uptime, and per-service health, read from the sidecar state file. Distinguishes booting from wedged; exits non-zero when not running or wedged. 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, 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. 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 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.

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.