fix(docs): update command syntax from '--' to single argument format for start, stop and status. (#1086)

claude-plugin/commands/daemon.md

@@ -1,6 +1,6 @@
 ---
 description: Manage background sync daemon
-argument-hint: [--start] [--stop] [--status] [--health]
+argument-hint: [start] [stop] [status] [--health]
 ---
 
 Manage the per-project background daemon that handles database connections and syncs with git.
@@ -39,9 +39,9 @@ Each project runs its own daemon at `.beads/bd.sock` for complete database isola
 
 ## Common Operations
 
-- **Start**: `bd daemon --start` (or auto-starts on first `bd` command)
+- **Start**: `bd daemon start` (or auto-starts on first `bd` command)
-- **Stop**: `bd daemon --stop`
+- **Stop**: `bd daemon stop`
-- **Status**: `bd daemon --status`
+- **Status**: `bd daemon status`
 - **Health**: `bd daemon --health` - shows uptime, cache stats, performance metrics
 - **Metrics**: `bd daemon --metrics` - detailed operational telemetry
 

claude-plugin/skills/beads/resources/TROUBLESHOOTING.md

@@ -6,7 +6,7 @@ Common issues encountered when using bd and how to resolve them.
 
 **MCP tools (local environment):**
 - MCP tools require bd daemon running
-- Check daemon status: `bd daemon --status` (CLI)
+- Check daemon status: `bd daemon status` (CLI)
 - If MCP tools fail, verify daemon is running and restart if needed
 - MCP tools automatically use daemon mode (no --no-daemon option)
 

cmd/bd/daemon.go

@@ -153,7 +153,7 @@ Run 'bd daemon --help' to see all subcommands.`,
 					// If we can check version and it's compatible, exit
 					if healthErr == nil && health.Compatible {
 						fmt.Fprintf(os.Stderr, "Error: daemon already running (PID %d, version %s)\n", pid, health.Version)
-						fmt.Fprintf(os.Stderr, "Use 'bd daemon --stop' to stop it first\n")
+						fmt.Fprintf(os.Stderr, "Use 'bd daemon stop' to stop it first\n")
 						os.Exit(1)
 					}
 
@@ -167,7 +167,7 @@ Run 'bd daemon --help' to see all subcommands.`,
 				} else {
 					// Can't check version - assume incompatible
 					fmt.Fprintf(os.Stderr, "Error: daemon already running (PID %d)\n", pid)
-					fmt.Fprintf(os.Stderr, "Use 'bd daemon --stop' to stop it first\n")
+					fmt.Fprintf(os.Stderr, "Use 'bd daemon stop' to stop it first\n")
 					os.Exit(1)
 				}
 			}

cmd/bd/daemon_autostart.go

@@ -495,13 +495,13 @@ func getSocketPath() string {
 func emitVerboseWarning() {
 	switch daemonStatus.FallbackReason {
 	case FallbackConnectFailed:
-		fmt.Fprintf(os.Stderr, "Warning: Daemon unreachable at %s. Running in direct mode. Hint: bd daemon --status\n", daemonStatus.SocketPath)
+		fmt.Fprintf(os.Stderr, "Warning: Daemon unreachable at %s. Running in direct mode. Hint: bd daemon status\n", daemonStatus.SocketPath)
 	case FallbackHealthFailed:
 		fmt.Fprintf(os.Stderr, "Warning: Daemon unhealthy. Falling back to direct mode. Hint: bd daemon --health\n")
 	case FallbackAutoStartDisabled:
 		fmt.Fprintf(os.Stderr, "Warning: Auto-start disabled (BEADS_AUTO_START_DAEMON=false). Running in direct mode. Hint: bd daemon\n")
 	case FallbackAutoStartFailed:
-		fmt.Fprintf(os.Stderr, "Warning: Failed to auto-start daemon. Running in direct mode. Hint: bd daemon --status\n")
+		fmt.Fprintf(os.Stderr, "Warning: Failed to auto-start daemon. Running in direct mode. Hint: bd daemon status\n")
 	case FallbackDaemonUnsupported:
 		fmt.Fprintf(os.Stderr, "Warning: Daemon does not support this command yet. Running in direct mode. Hint: update daemon or use local mode.\n")
 	case FallbackWorktreeSafety:

cmd/bd/doctor/daemon.go

@@ -235,7 +235,7 @@ func CheckDaemonAutoSync(path string) DoctorCheck {
 			Status:  StatusWarning,
 			Message: fmt.Sprintf("Daemon running without %v (slows agent workflows)", missing),
 			Detail:  "With sync-branch configured, auto-commit and auto-push should be enabled",
-			Fix:     "Restart daemon: bd daemon --stop && bd daemon --start",
+			Fix:     "Restart daemon: bd daemon stop && bd daemon start",
 		}
 	}
 

cmd/bd/test_repo_beads_guard_test.go

@@ -160,9 +160,9 @@ func stopRepoDaemon(repoRoot string) {
 		return // no daemon running
 	}
 
-	// Shell out to bd daemon --stop. We can't call the daemon functions directly
+	// Shell out to bd daemon stop. We can't call the daemon functions directly
 	// from TestMain because they have complex dependencies. Using exec is cleaner.
-	cmd := exec.Command("bd", "daemon", "--stop")
+	cmd := exec.Command("bd", "daemon", "stop")
 	cmd.Dir = repoRoot
 	cmd.Env = append(os.Environ(), "BEADS_DIR="+beadsDir)
 

docs/DAEMON.md

@@ -246,10 +246,10 @@ Event-driven mode is the **default** as of v0.21.0. No configuration needed.
 
 ```bash
 # Event-driven mode starts automatically
-bd daemon --start
+bd daemon start
 
 # Explicitly enable (same as default)
-BEADS_DAEMON_MODE=events bd daemon --start
+BEADS_DAEMON_MODE=events bd daemon start
 ```
 
 **Available modes:**
@@ -308,10 +308,10 @@ For edge cases (NFS, containers, WSL) where fsnotify is unreliable:
 
 ```bash
 # Explicitly use polling mode
-BEADS_DAEMON_MODE=poll bd daemon --start
+BEADS_DAEMON_MODE=poll bd daemon start
 
 # With custom interval
-bd daemon --start --interval 10s
+bd daemon start --interval 10s
 ```
 
 ### Troubleshooting Event-Driven Mode
@@ -380,7 +380,7 @@ bd info --json | grep daemon_running
 export BEADS_AUTO_START_DAEMON=false
 
 # Start manually
-bd daemon --start
+bd daemon start
 ```
 
 **Auto-start with exponential backoff:**

docs/PROTECTED_BRANCHES.md

@@ -69,7 +69,7 @@ The sync branch (beads-sync) will contain:
 **2. Start the daemon with auto-commit:**
 
 ```bash
-bd daemon --start --auto-commit
+bd daemon start --auto-commit
 ```
 
 The daemon will automatically commit issue changes to the `beads-sync` branch.
@@ -165,7 +165,7 @@ If you already have beads set up and want to switch to a separate branch:
 bd config set sync.branch beads-sync
 
 # Start the daemon (it will create the worktree automatically)
-bd daemon --start --auto-commit
+bd daemon start --auto-commit
 ```
 
 ### Daemon Configuration
@@ -174,10 +174,10 @@ For automatic commits to the sync branch:
 
 ```bash
 # Start daemon with auto-commit
-bd daemon --start --auto-commit
+bd daemon start --auto-commit
 
 # Or with auto-commit and auto-push
-bd daemon --start --auto-commit --auto-push
+bd daemon start --auto-commit --auto-push
 ```
 
 **Daemon modes:**
@@ -193,7 +193,7 @@ You can also configure the sync branch via environment variable:
 
 ```bash
 export BEADS_SYNC_BRANCH=beads-sync
-bd daemon --start --auto-commit
+bd daemon start --auto-commit
 ```
 
 This is useful for CI/CD or temporary overrides.
@@ -361,7 +361,7 @@ rm -rf .git/beads-worktrees/beads-sync
 git worktree prune
 
 # Restart daemon (it will recreate the worktree)
-bd daemon --stop && bd daemon --start
+bd daemon stop && bd daemon start
 ```
 
 ### "branch 'beads-sync' not found"
@@ -389,13 +389,13 @@ Check daemon status and logs:
 
 ```bash
 # Check status
-bd daemon --status
+bd daemon status
 
 # View logs
 tail -f ~/.beads/daemon.log
 
 # Restart daemon
-bd daemon --stop && bd daemon --start
+bd daemon stop && bd daemon start
 ```
 
 Common issues:
@@ -415,7 +415,7 @@ bd config get sync.branch  # Should be the same (e.g., beads-sync)
 bd sync --no-push
 
 # Check daemon is running
-bd daemon --status
+bd daemon status
 ```
 
 ## FAQ
@@ -440,7 +440,7 @@ Yes:
 
 ```bash
 bd config set sync.branch new-branch-name
-bd daemon --stop && bd daemon --start
+bd daemon stop && bd daemon start
 ```
 
 The old worktree will remain (no harm), and a new worktree will be created for the new branch.
@@ -451,7 +451,7 @@ Unset the sync branch config:
 
 ```bash
 bd config set sync.branch ""
-bd daemon --stop && bd daemon --start
+bd daemon stop && bd daemon start
 ```
 
 Beads will go back to committing directly to your current branch.
@@ -501,7 +501,7 @@ Yes, but the daemon will recreate it. If you want to clean up permanently:
 
 ```bash
 # Stop daemon
-bd daemon --stop
+bd daemon stop
 
 # Remove worktree
 git worktree remove .git/beads-worktrees/beads-sync
@@ -526,7 +526,7 @@ However, if you want fully automated sync:
 
 ```bash
 # WARNING: This bypasses branch protection!
-bd daemon --start --auto-commit --auto-push
+bd daemon start --auto-commit --auto-push
 bd sync --merge  # Run periodically (e.g., via cron)
 ```
 
@@ -672,7 +672,7 @@ If you have an existing beads setup committing to `main`:
 
 2. **Restart daemon:**
    ```bash
-   bd daemon --stop && bd daemon --start
+   bd daemon stop && bd daemon start
    ```
 
 3. **Verify:**
@@ -693,7 +693,7 @@ If you want to stop using a sync branch:
 
 2. **Restart daemon:**
    ```bash
-   bd daemon --stop && bd daemon --start
+   bd daemon stop && bd daemon start
    ```
 
 Future commits will go to your current branch (e.g., `main`).

docs/TROUBLESHOOTING.md

@@ -629,7 +629,7 @@ See [integrations/beads-mcp/README.md](../integrations/beads-mcp/README.md) for
 
 **Common symptoms:**
 - "Database out of sync with JSONL" errors that persist after running `bd import`
-- `bd daemon --stop` fails with "operation not permitted"
+- `bd daemon stop` fails with "operation not permitted"
 - Cannot kill daemon process with `kill <pid>`
 - JSONL hash mismatch warnings (bd-160)
 - Commands intermittently fail with staleness errors

docs/WORKTREES.md

@@ -77,7 +77,7 @@ bd config set sync.branch ""
 
 # Stop and restart daemon
 bd daemon stop
-bd daemon --start
+bd daemon start
 
 # Clean up existing worktrees
 rm -rf .git/beads-worktrees

examples/monitor-webui/main.go

@@ -158,7 +158,7 @@ func connectToDaemon(socketPath, dbPath string) error {
 		if health.Error != "" {
 			errMsg += fmt.Sprintf("\nError: %s", health.Error)
 		}
-		return fmt.Errorf("%s\n\nTry restarting the daemon:\n  bd daemon --stop\n  bd daemon", errMsg)
+		return fmt.Errorf("%s\n\nTry restarting the daemon:\n  bd daemon stop\n  bd daemon", errMsg)
 	}
 
 	// Set database path

examples/multi-phase-development/README.md

@@ -24,7 +24,7 @@ cd my-project
 bd init
 
 # Start daemon for auto-sync (optional)
-bd daemon --start --auto-commit --auto-push
+bd daemon start --auto-commit --auto-push
 ```
 
 ## Phase 1: Research & Planning

examples/multiple-personas/README.md

@@ -27,7 +27,7 @@ cd my-project
 bd init
 
 # Start daemon for auto-sync (optional for teams)
-bd daemon --start --auto-commit --auto-push
+bd daemon start --auto-commit --auto-push
 ```
 
 ## Persona: Architect

examples/protected-branch/README.md

@@ -52,7 +52,7 @@ bd update bd-XXXXX --status in_progress
 
 ```bash
 # Start daemon with auto-commit
-bd daemon --start --auto-commit
+bd daemon start --auto-commit
 
 # All issue changes are now automatically committed to beads-metadata branch
 ```
@@ -221,14 +221,14 @@ JSONL is append-only and line-based, so conflicts are rare. If they occur:
 The daemon creates it automatically on first commit. To create manually:
 ```bash
 bd config get sync.branch  # Verify it's set
-bd daemon --stop && bd daemon --start          # Daemon will create worktree
+bd daemon stop && bd daemon start          # Daemon will create worktree
 ```
 
 **"Changes not syncing"**
 
 Make sure:
 - `bd config get sync.branch` returns the same value on all clones
-- Daemon is running: `bd daemon --status`
+- Daemon is running: `bd daemon status`
 - Both clones have fetched: `git fetch origin beads-metadata`
 
 ## Advanced: GitHub Actions Integration

examples/team-workflow/README.md

@@ -216,7 +216,7 @@ bd close bd-abc --reason "PR #123 merged"
 Daemon commits and pushes automatically:
 
 ```bash
-bd daemon --start --auto-commit --auto-push
+bd daemon start --auto-commit --auto-push
 ```
 
 Benefits:
@@ -349,7 +349,7 @@ A: Add to your CI pipeline:
 Check daemon status:
 
 ```bash
-bd daemon --status
+bd daemon status
 bd daemons list
 ```
 
@@ -363,8 +363,8 @@ bd config get daemon.auto_push
 Restart daemon:
 
 ```bash
-bd daemon --stop
+bd daemon stop
-bd daemon --start --auto-commit --auto-push
+bd daemon start --auto-commit --auto-push
 ```
 
 ### Issue: Merge conflicts in JSONL

integrations/beads-mcp/README.md

@@ -288,7 +288,7 @@ Test daemon RPC with multiple repositories:
 ```bash
 # Start the daemon first
 cd /path/to/beads
-./bd daemon --start
+./bd daemon start
 
 # Run multi-repo test
 cd integrations/beads-mcp

integrations/beads-mcp/SETUP_DAEMON.md

@@ -28,7 +28,7 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
 In your beads project directory:
 
 ```bash
-bd daemon --start
+bd daemon start
 ```
 
 The daemon will:
@@ -108,19 +108,19 @@ If you want to temporarily use CLI mode:
 
 ```bash
 # Start daemon
-bd daemon --start
+bd daemon start
 
 # Check status
-bd daemon --status
+bd daemon status
 
 # View logs
 bd daemons logs .
 
 # Stop daemon
-bd daemon --stop
+bd daemon stop
 
 # Restart daemon
-bd daemon --stop && bd daemon --start
+bd daemon stop && bd daemon start
 ```
 
 ## Troubleshooting
@@ -130,14 +130,14 @@ bd daemon --stop && bd daemon --start
 Start the daemon in your beads project:
 ```bash
 cd ~/src/vc/adar/beads
-bd daemon --start
+bd daemon start
 ```
 
 ### Wrong database being used
 
 1. Check where daemon is running:
    ```bash
-   bd daemon --status
+   bd daemon status
    ```
 
 2. Use `set_context` tool in Claude to set workspace root:

integrations/beads-mcp/src/beads_mcp/bd_daemon_client.py

@@ -111,7 +111,7 @@ class BdDaemonClient(BdClientBase):
         
         # No socket found anywhere
         raise DaemonNotRunningError(
-            "Daemon socket not found. Is the daemon running? Try: bd daemon --start"
+            "Daemon socket not found. Is the daemon running? Try: bd daemon start"
         )
 
     async def _send_request(self, operation: str, args: Dict[str, Any]) -> Any:

internal/rpc/server_routing_validation_diagnostics.go

@@ -48,7 +48,7 @@ func (s *Server) checkVersionCompatibility(clientVersion string) error {
 		cmp := semver.Compare(serverVer, clientVer)
 		if cmp < 0 {
 			// Daemon is older - needs upgrade
-			return fmt.Errorf("incompatible major versions: client %s, daemon %s. Daemon is older; upgrade and restart daemon: 'bd daemon --stop && bd daemon'",
+			return fmt.Errorf("incompatible major versions: client %s, daemon %s. Daemon is older; upgrade and restart daemon: 'bd daemon stop && bd daemon'",
 				clientVersion, ServerVersion)
 		}
 		// Daemon is newer - client needs upgrade