johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Michael
2026-01-15 12:43:07 +08:00
committed by GitHub
parent 9e639da5ba
commit b9d2799d29
19 changed files with 54 additions and 54 deletions
Download Patch File Download Diff File Expand all files Collapse all files
claude-plugin/commands/daemon.md
+4 -4
View File
@@ -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)
- **Stop**: `bd daemon --stop`
- **Status**: `bd daemon --status`
- **Start**: `bd daemon start` (or auto-starts on first `bd` command)
- **Stop**: `bd daemon stop`
- **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
+1 -1
View File
@@ -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
+2 -2
View File
@@ -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
+2 -2
View File
@@ -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
+1 -1
View File
@@ -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
+2 -2
View File
@@ -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
+5 -5
View File
@@ -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
+15 -15
View File
@@ -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
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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
+3 -3
View File
@@ -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
+4 -4
View File
@@ -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 --start --auto-commit --auto-push
bd daemon stop
bd daemon start --auto-commit --auto-push
```
### Issue: Merge conflicts in JSONL
integrations/beads-mcp/README.md
+1 -1
View File
@@ -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
+7 -7
View File
@@ -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
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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