Skip to main content

​
Overview

The cleanup command removes stale session files, kills orphaned daemon processes, and optionally terminates Chrome instances. Use this to recover from crashed sessions or clean up after abnormal termination.

​
Syntax

bdg cleanup [options]

​
Options

​
--force
boolean
default:"false"
Force cleanup even if session appears active (removes files but doesn’t kill processes)
bdg cleanup --force
​
--remove-output
boolean
default:"false"
Also remove the session.json output file
bdg cleanup --remove-output
​
--aggressive
boolean
default:"false"
Kill orphaned daemon processes and all stale Chrome instances
bdg cleanup --aggressive
​
--json
boolean
default:"false"
Output as JSON for programmatic use
bdg cleanup --json

​
Examples

​
Basic Cleanup

bdg cleanup
Output: 
Session files cleaned up

Session directory is now clean

​
No Stale Files

bdg cleanup
Output: 
No session files found. Session directory is already clean

​
Force Cleanup (Active Session)

bdg cleanup --force
Output: 
Session files cleaned up
Warning: Session process (PID 12345) is still running

Session directory is now clean
--force removes session files but does NOT kill the running daemon or Chrome. Use bdg stop for graceful shutdown or --aggressive to kill processes.

​
Aggressive Cleanup

bdg cleanup --aggressive
Output: 
Session files cleaned up
Killed Chrome (PID 12346)
Cleaned up 2 orphaned daemon processes

Session directory is now clean

​
Remove Output File

bdg cleanup --remove-output
Output: 
Session files cleaned up
Session output file removed

Session directory is now clean

​
JSON Output

bdg cleanup --json
Output: 
{
  "version": "0.5.1",
  "success": true,
  "data": {
    "cleaned": {
      "session": true,
      "output": false,
      "chrome": false,
      "daemons": false
    },
    "message": "Session directory is now clean"
  }
}

​
What Gets Cleaned Up

​
Session Files (Default)

  • ~/.bdg/daemon.pid
  • ~/.bdg/daemon.sock
  • ~/.bdg/session.meta.json
  • ~/.bdg/chrome-profile/ (temporary Chrome profile)

​
Output File (--remove-output)

  • ~/.bdg/session.json

​
Processes (--aggressive)

  • Orphaned bdg daemon processes (PIDs from stale daemon.pid files)
  • All Chrome instances launched by bdg (uses chrome-launcher killAll)
--aggressive uses chrome-launcher’s killAll() which terminates ALL Chrome instances on the system, not just bdg-launched ones. Use with caution.

​
Use Cases

​
Recover from Crashed Session

# Daemon crashed or was killed
bdg status
# Error: Daemon not running

# Clean up stale files
bdg cleanup

# Start fresh session
bdg example.com

​
Reset After Abnormal Termination

# System reboot, force quit, etc.
bdg cleanup --aggressive

# Verify cleanup
bdg status
# No active session.

​
Clean Slate for Testing

# Remove all session data including output
bdg cleanup --remove-output

# Start fresh test
bdg localhost:3000

​
CI/CD Cleanup

# Ensure clean state before test run
bdg cleanup --aggressive

# Run tests
bdg https://staging.example.com --headless
# ... test commands ...
bdg stop

# Cleanup after (removes output too)
bdg cleanup --remove-output

​
Kill All Chrome Instances

# Nuclear option: kill everything
bdg cleanup --aggressive

# Or combine with stop
bdg stop --kill-chrome
bdg cleanup --aggressive  # Also kills orphaned daemons

​
Error Handling

​
Session Still Active (No Force)

# Session is running
bdg cleanup
Output: 
Error: Session is still active (PID 12345)
Suggestion: Stop gracefully: bdg stop
           Force cleanup: bdg cleanup --force
Warning: Force cleanup will remove session files but will NOT kill the running process
Exit Code: 85 (RESOURCE_BUSY)

​
Permission Denied

If session files are not writable: 
bdg cleanup
Output: 
Error: Permission denied
Suggestion: Check file permissions in ~/.bdg/
Exit Code: 82 (PERMISSION_DENIED)

​
Cleanup vs Stop

CommandPurposeSession DataChromeGraceful
bdg stopEnd active session✅ Saved to disk⚠️ Keeps running✅ Yes
bdg stop --kill-chromeEnd session + kill Chrome✅ Saved to disk✅ Terminated✅ Yes
bdg cleanupRemove stale files❌ Lost if not saved⚠️ Keeps running⚠️ If session dead
bdg cleanup --forceForce remove files❌ Lost⚠️ Keeps running❌ No
bdg cleanup --aggressiveNuclear cleanup❌ Lost✅ Terminated❌ No
Always prefer bdg stop for graceful shutdown. Use cleanup only for stale sessions or recovery scenarios.

​
Exit Codes

​
0
SUCCESS
Cleanup completed successfully
​
82
PERMISSION_DENIED
Insufficient permissions to remove session files
​
85
RESOURCE_BUSY
Session is active and --force not specified
​
110
SOFTWARE_ERROR
Unexpected error during cleanup

bdg stop

Gracefully stop session and save data

bdg status

Check if cleanup is needed

bdg start

Start fresh session after cleanup

​
Tips

When to Use Cleanup: Run cleanup when bdg status shows no session but you can’t start a new one, or after crashes/force quits.
Stale Detection: If a session appears active but you force cleaned it, the running daemon will continue operating but be inaccessible. Use --aggressive to kill it.
CI/CD Best Practice: Always run bdg cleanup --aggressive before AND after test runs to ensure clean state.
Data Loss: Cleanup removes session files without saving data. If you need the data, use bdg stop instead.
Aggressive Mode Danger: --aggressive kills ALL Chrome instances on the system using chrome-launcher.killAll(). Don’t use if you have other Chrome windows open.
Force Cleanup Limitation: --force removes files but doesn’t terminate processes. The orphaned daemon/Chrome may consume resources until killed manually or with --aggressive.

Build docs developers (and LLMs) love

Get started for freeTalk to us