/daemons

bd daemons - Daemon Management

Manage bd daemon processes across all repositories and worktrees.

Synopsis

bd daemons <subcommand> [flags]

Description

The bd daemons command provides tools for discovering, monitoring, and managing multiple bd daemon processes across your system. This is useful when working with multiple repositories or git worktrees.

Subcommands

list

List all running bd daemons with metadata.

bd daemons list [--search DIRS] [--json] [--no-cleanup]

Flags:

• --search - Directories to search for daemons (default: home, /tmp, cwd)
• --json - Output in JSON format
• --no-cleanup - Skip auto-cleanup of stale sockets

Example:

bd daemons list
bd daemons list --search /Users/me/projects --json

health

Check health of all bd daemons and report issues.

bd daemons health [--search DIRS] [--json]

Reports:

• Stale sockets (dead processes)
• Version mismatches between daemon and CLI
• Unresponsive daemons

Flags:

• --search - Directories to search for daemons
• --json - Output in JSON format

Example:

bd daemons health
bd daemons health --json

stop

Stop a specific daemon gracefully.

bd daemons stop <workspace-path|pid> [--json]

Arguments:

• <workspace-path|pid> - Workspace path or PID of daemon to stop

Flags:

• --json - Output in JSON format

Example:

bd daemons stop /Users/me/projects/myapp
bd daemons stop 12345
bd daemons stop /Users/me/projects/myapp --json

restart

Restart a specific daemon gracefully.

bd daemons restart <workspace-path|pid> [--search DIRS] [--json]

Stops the daemon gracefully, then starts a new one in its place. Useful after upgrading bd or when a daemon needs to be refreshed.

Arguments:

• <workspace-path|pid> - Workspace path or PID of daemon to restart

Flags:

• --search - Directories to search for daemons
• --json - Output in JSON format

Example:

bd daemons restart /Users/me/projects/myapp
bd daemons restart 12345
bd daemons restart /Users/me/projects/myapp --json

logs

View logs for a specific daemon.

bd daemons logs <workspace-path|pid> [-f] [-n LINES] [--json]

Arguments:

• <workspace-path|pid> - Workspace path or PID of daemon

Flags:

• -f, --follow - Follow log output (like tail -f)
• -n, --lines INT - Number of lines to show from end (default: 50)
• --json - Output in JSON format

Example:

bd daemons logs /Users/me/projects/myapp
bd daemons logs 12345 -n 100
bd daemons logs /Users/me/projects/myapp -f
bd daemons logs 12345 --json

killall

Stop all running bd daemons.

bd daemons killall [--search DIRS] [--force] [--json]

Uses escalating shutdown strategy:

1. RPC shutdown (2 second timeout)
2. SIGTERM (3 second timeout)
3. SIGKILL (1 second timeout)

Flags:

• --search - Directories to search for daemons
• --force - Use SIGKILL immediately if graceful shutdown fails
• --json - Output in JSON format

Example:

bd daemons killall
bd daemons killall --force
bd daemons killall --json

Common Use Cases

Version Upgrade

After upgrading bd, restart all daemons to use the new version:

bd daemons health  # Check for version mismatches
bd daemons killall # Stop all old daemons
# Daemons will auto-start with new version on next bd command

# Or restart a specific daemon
bd daemons restart /path/to/workspace

Debugging

Check daemon status and view logs:

bd daemons list
bd daemons health
bd daemons logs /path/to/workspace -n 100

Cleanup

Remove stale daemon sockets:

bd daemons list  # Auto-cleanup happens by default
bd daemons list --no-cleanup  # Skip cleanup

Multi-Workspace Management

Discover daemons in specific directories:

bd daemons list --search /Users/me/projects
bd daemons health --search /Users/me/work

Troubleshooting

Stale Sockets

If you see stale sockets (dead process but socket file exists):

bd daemons list  # Auto-cleanup removes stale sockets

Version Mismatch

If daemon version != CLI version:

bd daemons health  # Identify mismatched daemons
bd daemons killall # Stop all daemons
# Next bd command will auto-start new version

Daemon Won't Stop

If graceful shutdown fails:

bd daemons killall --force  # Force kill with SIGKILL

Can't Find Daemon

If daemon isn't discovered:

bd daemons list --search /path/to/workspace

Or check the socket manually:

ls -la /path/to/workspace/.beads/bd.sock

See Also

• bd daemon - Start a daemon manually
• AGENTS.md - Agent workflow guide
• README.md - Main documentation