B9 BS9 Docs

BS9 CLI Commands Documentation

Overview

BS9 (Bun Sentinel 9) provides 39 CLI commands for managing Bun and polyglot applications. Commands support automatic platform detection (Linux systemd, macOS launchd, and Windows services/watchdog) and standard configuration workflows.

📑 Command Categories

Core Process Lifecycle

1. bs9 start - Start Applications

Starts single-process or clustered services with a pre-start security pattern audit and automatic process supervision.

# Basic start (defaults to localhost:3000, HTTP)
bs9 start app.ts

# Cluster Mode (Bun reusePort kernel load balancing)
bs9 start app.ts -i 4 --port 3000
bs9 start app.ts -i max --name api-service

# Polyglot Multi-Runtime: Python, Go, Binaries, Shell scripts
bs9 start worker.py                                 # Auto-detected Python runtime
bs9 start main.go                                   # Auto-detected Go runtime
bs9 start service.exe                               # Native executable binary
bs9 start task.sh                                   # Shell script
bs9 start app.rb --interpreter ruby                 # Explicit custom runtime

# Import supported ecosystem configuration fields
bs9 start ecosystem.config.js
bs9 start bs9.config.json

# Multi-service batch starts
bs9 start [app1, app2, app3]
bs9 start [worker-*]
bs9 start all

# Production features: memory limits, file watching, auto-restart
bs9 start app.ts --watch --max-memory-restart 500M --time
bs9 start app.ts --cron "0 4 * * *"                 # Daily restart at 4 AM

Options:

2. bs9 stop - Stop Applications

Stops running services gracefully with bounded drain timeouts or forceful termination.

# Stop a specific service
bs9 stop my-app

# Stop multiple services
bs9 stop [app1, app2]
bs9 stop [worker-*]
bs9 stop app1 app2 app3

# Stop all managed services
bs9 stop all

# Force immediate termination
bs9 stop my-app --force

Options:

3. bs9 restart - Restart Applications

Restarts running services while preserving configuration and runtime metadata.

# Restart a specific service
bs9 restart my-app

# Restart multiple services or patterns
bs9 restart [web-1, web-2]
bs9 restart [api-*]
bs9 restart all

# Force restart without confirmation
bs9 restart my-app --force

Options:

4. bs9 reload - Zero-Downtime Rolling Reload

Performs a replace-first, zero-downtime rolling reload across all worker slots in a cluster.

# Reload a clustered service with zero downtime
bs9 reload my-api

# Reload all clustered services
bs9 reload all

# Force reload
bs9 reload my-api --force

Guarantees:

5. bs9 delete - Delete Services

Removes managed services from supervision and optionally purges configuration files.

# Delete a specific service
bs9 delete my-app

# Delete and clean up configuration files
bs9 delete my-app --remove

# Batch deletion with patterns
bs9 delete [test-*]
bs9 delete all --force

# Custom graceful shutdown timeout before SIGKILL
bs9 delete my-app --timeout 60

Options:

6. bs9 scale - Dynamic Cluster Scaling

Scales the number of worker instances in an active cluster up or down without service downtime.

# Scale to a fixed target worker count
bs9 scale my-api 8

# Scale up by 2 workers
bs9 scale my-api +2

# Scale down by 1 worker
bs9 scale my-api -1

7. bs9 reset - Reset Restart Counters & Circuit Breaker

Resets restart attempt counters, exponential backoff delays, and crash loop circuit breaker states.

# Reset a specific service
bs9 reset my-app

# Reset all services
bs9 reset all

8. bs9 sendSignal - Send OS Signals

Sends POSIX signals directly to application processes across platforms.

# Send SIGUSR2 for user reload
bs9 sendSignal SIGUSR2 my-app

# Graceful interrupt
bs9 sendSignal SIGINT my-app

# Force termination
bs9 sendSignal SIGKILL my-app

9. bs9 ping - Daemon Healthcheck

Verifies the responsiveness of the persistent BS9 Controller & Hub daemon.

bs9 ping
# Outputs:
# 🏓 Pong! BS9 Controller & Hub daemon is alive and operational.
# Platform: Linux (systemd user supervisor)
# Socket: /run/user/1000/bs9/ctrl.sock

📊 Status, Inspection & Observability

10. bs9 status / list / ls / ps - Process Status Dashboard

Displays real-time status, PIDs, memory, CPU, uptime, and health indicators across services.

# Display all running services
bs9 status
bs9 ls
bs9 ps

# Filter specific services or patterns
bs9 status [web-*]
bs9 status my-app

# Continuous live refresh mode (refreshes every 2s)
bs9 status --watch

# Machine-readable JSON output
bs9 status --json
bs9 status --raw

Visual Indicators:

11. bs9 show / describe - Detailed Process Inspection

Displays comprehensive runtime metadata, filesystem paths, PIDs, generations, environment variables, and memory statistics.

bs9 show my-app
bs9 describe my-app

12. bs9 logs - View Application Logs

Views real-time aggregated or service-specific stdout and stderr streams.

# Combined real-time logs across all services
bs9 logs

# Logs for a specific service
bs9 logs my-app

# Stream logs continuously
bs9 logs my-app --follow

# Fetch specific number of lines
bs9 logs my-app --lines 100

13. bs9 flush - Empty and Truncate Logs

Empties stdout and stderr log files on disk without stopping the process.

# Flush logs for a specific service
bs9 flush my-app

# Flush logs for all services
bs9 flush

14. bs9 issues - Runtime Error & Exception Tracker

Aggregates runtime exceptions, unhandled rejections, stack traces, and crash histories across services.

# View aggregated issues across all services
bs9 issues

# View issues for a specific service
bs9 issues my-app

# Scan deeper log history
bs9 issues my-app --lines 200

# JSON output for monitoring pipelines
bs9 issues --json

# Clear issue logs and reset error state
bs9 issues --clear

Features:

15. bs9 monit - Terminal Dashboard

Interactive full-terminal dashboard displaying CPU and memory usage graphs, active PIDs, and live logs.

# Launch terminal monitor
bs9 monit

# Custom refresh interval
bs9 monit --refresh 5

16. bs9 web - Browser Monitoring Dashboard

Launches a dark glassmorphism web dashboard with WebSocket live streaming and Bearer authentication.

# Start web dashboard on port 8080
bs9 web

# Custom port and detached background mode
bs9 web --port 9000 --detach

17. bs9 advanced - Advanced Monitoring Dashboard

Launches the advanced Prometheus and SRE diagnostic interface.

bs9 advanced --port 8090

18. bs9 env - Dump Configured Environment Variables

Displays the environment variables injected into the running service.

bs9 env my-app

19. bs9 profile - CPU and Memory Profiling

Profiles runtime performance and generates sampling summaries or flamegraphs.

# 60-second sampling profile
bs9 profile --service my-app --duration 60

# Generate flamegraph artifact
bs9 profile --service my-app --flamegraph --output flame.svg

# Inspect top N CPU-heavy functions
bs9 profile --service my-app --top 15

20. bs9 deps - Dependency Visualization & Audit

Visualizes service dependencies and audits packages for security vulnerabilities.

# Visualize dependency tree
bs9 deps my-app

# Export dependency graph as Graphviz DOT or JSON
bs9 deps my-app --format dot --output deps.dot
bs9 deps my-app --format json

21. bs9 export - Export Historical Metrics

Exports persisted metrics (CPU, memory, latency, requests) to JSON or CSV.

# Export last 24 hours of metrics to JSON
bs9 export --format json --hours 24 --output metrics.json

# Export specific service metrics to CSV
bs9 export --service my-app --format csv --output app-metrics.csv

🛡️ High Availability, State & Self-Healing

22. bs9 inspect-ha - Static HA Readiness Inspection

Performs advisory AST static analysis on entry files and imports to detect unsafe in-memory state.

# Inspect application entry file
bs9 inspect-ha src/app.ts

# Machine-readable JSON output for CI pipelines
bs9 inspect-ha src/app.ts --json

Tiers Evaluated:

23. bs9 verify-ha - Isolated HA Verification & Fault Injection

Exercises rolling reloads and violent worker crash recovery under concurrent HTTP load.

# Ephemeral test on high port (default, isolated)
bs9 verify-ha src/app.ts

# High concurrency and worker count
bs9 verify-ha src/app.ts --instances 4 --concurrency 20 --json

# Test against an active running production cluster (Caution)
bs9 verify-ha my-production-service --live

Options:

24. bs9 daemon - Controller & Hub Daemon Management

Manages the background supervisor that owns topology reconciliation, cluster locks, and the durable same-host State Hub.

# Check daemon status and PID
bs9 daemon status

# Start daemon in background
bs9 daemon start

# Stop daemon
bs9 daemon stop

# Run in foreground (for systemd or Docker container supervision)
bs9 daemon start --foreground

⚙️ Production, Configuration & Automation

25. bs9 deploy - Zero-Config Production Deployment

Single-command production deployment with OS security sandboxing, systemd lingering, metrics, and health validation.

# Deploy with production configuration
bs9 deploy app.ts --name prod-api --port 8080 --env NODE_ENV=production

# Hot reload existing deployment with new settings
bs9 deploy app.ts --reload --env NEW_KEY=new_val

26. bs9 init / ecosystem - Generate Configuration Templates

Generates BS9 configuration templates. The ecosystem format also supports importing a documented subset of common PM2 fields.

# Generate JavaScript template (ecosystem.config.js)
bs9 init

# Generate TypeScript template (ecosystem.config.ts)
bs9 init --ts

# Generate JSON template (bs9.config.json)
bs9 init --json

27. bs9 save - Save Service Configuration Backup

Saves running service configurations and topologies to persistent JSON backups.

# Save specific service
bs9 save my-app

# Save all services
bs9 save --all

# Create timestamped versioned backup
bs9 save --all --backup

28. bs9 resurrect - Restore Services from Backup

Restores saved services and starts them after system maintenance or migration.

# Restore a specific service
bs9 resurrect my-app

# Restore all saved services
bs9 resurrect --all

# Restore from a specific backup file
bs9 resurrect --all --config backup-2026-09-17.json

29. bs9 startup & unstartup - OS Boot Resurrection

Configures system boot hooks (systemd user linger, macOS LaunchDaemons, Windows Task Scheduler/Services) to resurrect BS9 services on system boot.

# Enable auto-resurrect on OS reboot
bs9 startup

# Disable auto-resurrect on boot
bs9 unstartup

30. bs9 alert - Alert Thresholds & Webhooks

Configures alerting rules for CPU, memory, uptime, and error rate thresholds with Slack or custom webhooks.

# View active alert configuration
bs9 alert --list

# Configure thresholds and Slack webhook
bs9 alert --enable --cpu 85 --memory 90 --webhook https://hooks.slack.com/services/...

# Test webhook delivery
bs9 alert --test

31. bs9 loadbalancer - Built-in Reverse Proxy & Load Balancer

Configures a built-in reverse proxy with round-robin, least-connections, or IP-hash algorithms and health checks.

# Start load balancer on port 8080 forwarding to multiple backends
bs9 loadbalancer start --port 8080 --algorithm round-robin --backends 127.0.0.1:3001,127.0.0.1:3002

32. bs9 dbpool - Database Connection Pool Testing

Tests and benchmarks database connection pools under concurrent query stress.

bs9 dbpool test --host localhost --port 5432 --database prod --username app --max-connections 20

33. bs9 mcp - Native Model Context Protocol Server

Starts the Model Context Protocol (MCP) server over stdio for AI assistants (Claude Desktop, Cursor, Antigravity).

# Start MCP server
bs9 mcp

# Output configuration JSON for Claude Desktop / Cursor
bs9 mcp --install

34. bs9 update - Self-Update BS9

Checks for new releases and updates BS9 to the latest or specific version.

# Check for updates
bs9 update --check

# Upgrade to latest
bs9 update

# Rollback to previous version
bs9 update --rollback

35. bs9 doctor - Installation Health Check

Performs diagnostics on permissions, sockets, systemd/launchd supervisors, and Bun runtime environments.

# Run comprehensive health check
bs9 doctor

# Verbose system diagnostic report
bs9 doctor --verbose

36. bs9 inspect - Deep System Audit & Security Scan

Audits application security, static source risks (eval, child_process.exec), resource limits, and compliance.

# Complete system and security audit
bs9 inspect --full

# Deep analysis with JSON report
bs9 inspect --deep --report json

37. bs9 windows - Windows Service Management

Direct Windows service manager actions (create, start, stop, restart, delete, status).

bs9 windows create --name MyService --file C:\apps\app.ts
bs9 windows status --name MyService

38. bs9 macos - macOS launchd Service Management

Direct macOS launchd daemon actions (create, start, stop, restart, delete, status).

bs9 macos create --name com.myorg.app --file /Users/admin/apps/app.ts
bs9 macos status --name com.myorg.app

39. bs9 consul - Consul Service Discovery

Registers or deregisters BS9 services with HashiCorp Consul.

bs9 consul register --name api-service --address 127.0.0.1 --port 3000 --health-check http://localhost:3000/healthz

📝 Exit Codes

🔗 Related Documentation

Last Updated: September 17, 2026
BS9 Version: 1.6.7