Documentation Index
Fetch the complete documentation index at: https://mintlify.com/steveyegge/beads/llms.txt
Use this file to discover all available pages before exploring further.
Overview
Configure and manage Dolt database settings, server lifecycle, and version control operations. Beads uses a dolt sql-server that auto-starts transparently when needed.
Syntax
bd dolt <subcommand> [flags]
Subcommands
Server Lifecycle
start
Start the Dolt SQL server for this project:
The server runs in the background on a per-project port derived from the project path. PID and logs are stored in .beads/.
stop
Stop the Dolt SQL server:
bd dolt stop
bd dolt stop --force # Force stop even under Gas Town daemon
status
Show Dolt server status:
bd dolt status
bd dolt status --json
Configuration
show
Show current Dolt configuration with connection test:
Output:
Dolt Configuration
==================
Database: beads
Host: 127.0.0.1
Port: 3307
User: root
✓ Server connection OK
Remotes:
origin https://doltremoteapi.dolthub.com/user/repo
Config sources (priority order):
1. Environment variables (BEADS_DOLT_*)
2. metadata.json (local, gitignored)
3. config.yaml (team defaults)
set
Set a configuration value:
bd dolt set <key> <value> [--update-config]
| Key | Description |
|---|
database | Database name (default: issue prefix or “beads”) |
host | Server host (default: 127.0.0.1) |
port | Server port (auto-detected; override if needed) |
user | MySQL user (default: root) |
data-dir | Custom dolt data directory (absolute path) |
bd dolt set database myproject
bd dolt set host 192.168.1.100 --update-config
bd dolt set port 3307
bd dolt set data-dir /home/user/.beads-dolt/myproject
--update-config to also write to config.yaml for team-wide defaults.
test
Test connection to Dolt server:
Verifies:
- Server is reachable at configured host:port
- Connection can be established
- Remote connectivity (for configured remotes)
Version Control
commit
Create a Dolt commit from pending changes:
bd dolt commit # Auto-generated message
bd dolt commit -m "Batch update" # Custom message
bd commands. Also needed before push operations that require a clean working set.
push
Push commits to Dolt remote:
bd dolt push
bd dolt push --force # Overwrite remote changes
DOLT_REMOTE_USER and DOLT_REMOTE_PASSWORD environment variables.
pull
Pull commits from Dolt remote:
Merges remote changes into local database.
Remote Management
remote add
Add a Dolt remote (both SQL server and CLI):
bd dolt remote add <name> <url>
# DoltHub (recommended)
bd dolt remote add origin https://doltremoteapi.dolthub.com/user/repo
# Filesystem
bd dolt remote add backup file:///mnt/backup/beads
# SSH
bd dolt remote add origin git@github.com:user/repo.git
export DOLT_REMOTE_USER=your-username
export DOLT_REMOTE_PASSWORD=your-token
bd dolt remote add origin https://doltremoteapi.dolthub.com/user/repo
remote list
List configured Dolt remotes (SQL server + CLI):
bd dolt remote list
bd dolt remote list --json
remote remove
Remove a Dolt remote (both SQL server and CLI):
bd dolt remote remove <name>
bd dolt remote remove <name> --force # Force remove despite conflicts
Maintenance
clean-databases
Drop stale test/polecat databases from Dolt server:
bd dolt clean-databases
bd dolt clean-databases --dry-run
testdb_*, doctest_*, doctortest_*, beads_pt*, beads_vr*, beads_t*).
killall
Kill all orphan Dolt server processes:
Finds and terminates dolt sql-server processes not tracked by the canonical PID file.
Environment Variables
| Variable | Description |
|---|
BEADS_DOLT_DATABASE | Override database name |
BEADS_DOLT_HOST | Override server host |
BEADS_DOLT_PORT | Override server port |
BEADS_DOLT_USER | Override MySQL user |
BEADS_DOLT_PASSWORD | MySQL password (if needed) |
BEADS_DOLT_DATA_DIR | Override data directory |
DOLT_REMOTE_USER | Remote authentication username |
DOLT_REMOTE_PASSWORD | Remote authentication token |
Configuration Precedence
Settings are resolved in order:
- Environment variables (
BEADS_DOLT_*) - highest priority
- metadata.json - local overrides (gitignored)
- config.yaml - team defaults (committed)
Dolt Sync Workflows
Team Collaboration
Setup (once per developer):
# Configure remote
bd dolt remote add origin https://doltremoteapi.dolthub.com/team/project
# Set credentials
export DOLT_REMOTE_USER=your-username
export DOLT_REMOTE_PASSWORD=your-token
# Start day: pull latest
bd dolt pull
# Work on issues
bd update bd-42 --status in_progress
# Push changes
bd dolt push
# End day: ensure pushed
bd dolt status
Backup and Recovery
Setup backup remote:
bd dolt remote add backup https://doltremoteapi.dolthub.com/user/backup
# Push to backup remote
bd dolt push backup
# Verify backup
bd dolt remote list
# Initialize new repository
bd init
# Add backup remote
bd dolt remote add backup https://doltremoteapi.dolthub.com/user/backup
# Pull from backup
bd dolt pull backup
Multi-Machine Sync
Machine A:
# Make changes
bd create "New feature" -t feature -p 1
# Push to remote
bd dolt push
# Pull changes
bd dolt pull
# Verify sync
bd list --json
Examples
View Current Configuration
Change Database Name
bd dolt set database myproject
bd dolt set database myproject --update-config # Save to config.yaml
# For remote server
bd dolt set host 192.168.1.100 --update-config
bd dolt set port 3307
# Test connectivity
bd dolt test
Setup Custom Data Directory
# Move database to external drive
bd dolt set data-dir /mnt/external/beads-data
# Verify
bd dolt show
Batch Commit Workflow
# Configure batch mode
bd config set dolt.auto-commit batch
# Make multiple changes
bd create "Task 1" -t task
bd create "Task 2" -t task
bd update bd-42 --status closed
# Commit all at once
bd dolt commit
# Push
bd dolt push
Setup DoltHub Remote
# Configure credentials
export DOLT_REMOTE_USER=myusername
export DOLT_REMOTE_PASSWORD=my_token_abc123
# Add remote
bd dolt remote add origin https://doltremoteapi.dolthub.com/myusername/myrepo
# Push initial state
bd dolt push
# Verify
bd dolt remote list
Troubleshoot Connection Issues
# Check server status
bd dolt status
# Test connection
bd dolt test
# Restart server if needed
bd dolt stop
bd dolt start
# Verify
bd dolt status
Troubleshooting
Server Connection Failed
Cause: Server not running or wrong port
Solution:
bd dolt status # Check if running
bd dolt start # Start if stopped
bd dolt test # Test connection
Remote Not Found
Cause: Remote registered in CLI but not SQL server
Solution:
bd dolt remote list # Check both surfaces
bd dolt remote add origin <url> # Re-register
Push Failed: Uncommitted Changes
Cause: Dolt requires clean working set
Solution:
bd dolt commit # Commit pending changes
bd dolt push # Retry push
Data Directory Not Found
Cause: Custom data-dir path doesn’t exist
Solution:
mkdir -p /path/to/data-dir
bd dolt set data-dir /path/to/data-dir
Orphan Server Processes
Cause: Server crashed or PID file lost
Solution:
bd dolt killall # Kill orphan processes
bd dolt start # Start fresh
bd init - Initialize with Dolt backendbd backup - Backup operations (alternative to remotes)bd doctor - Health checks including Dolt connectivitybd compact - Includes Dolt garbage collection
See Also