Command Reference

Complete reference for all bosun CLI commands.

Global Flags

Setup Commands

init

Interactive setup wizard to configure your yacht.

bosun init

Creates a bosun.yaml configuration file in the current directory.

update

Check for or install the latest stable Bosun release.

bosun update
bosun update --check
bosun selfupdate

The install path requires checksums.txt from the same GitHub release and verifies the selected compressed archive before extraction or executable replacement. Missing or invalid selected checksum data, asset download failure, and digest mismatch return an error without changing the installed executable. There is no unchecked fallback or automatic retry; rerunning the command starts a fresh verified attempt.

--check validates only that the selected platform archive and checksums.txt are advertised by the same release. It downloads neither asset.

Same-release SHA-256 verification is an integrity control, not independent publisher authentication: replacing both release assets remains outside this control. Bosun releases do not currently publish checksum signature assets.

Alias: selfupdate

Flags:

Yacht Commands

Manage Docker Compose services (the whole fleet).

yacht up

Start the yacht (docker compose up -d).

bosun yacht up
bosun yacht up [services...]

Examples:

bosun yacht up                    # Start all services
bosun yacht up traefik authelia   # Start specific services

Automatically checks if Traefik is running before starting other services.

yacht down

Dock the yacht (docker compose down).

bosun yacht down

Stops and removes all services defined in the compose file.

yacht restart

Quick turnaround (docker compose restart).

bosun yacht restart
bosun yacht restart [services...]

Examples:

bosun yacht restart              # Restart all services
bosun yacht restart myapp        # Restart specific service

yacht status

Check if we’re seaworthy.

bosun yacht status

Shows the status of all services in the compose file.

Crew Commands

Manage individual containers.

crew list

Show all hands on deck.

bosun crew list
bosun crew list -a

Flags:

Example output:

NAME          STATUS              PORTS
traefik       Up 3 days           80/tcp, 443/tcp
authelia      Up 3 days (healthy) 9091/tcp
myapp         Up 2 hours          8080/tcp

crew logs

Tail crew member logs.

bosun crew logs <name>
bosun crew logs <name> -f
bosun crew logs <name> -n 50

Flags:

Examples:

bosun crew logs traefik           # Last 100 lines
bosun crew logs traefik -f        # Stream logs
bosun crew logs traefik -n 20     # Last 20 lines

crew inspect

Show detailed crew info.

bosun crew inspect <name>

Outputs container details as formatted JSON.

crew restart

Send crew member for coffee break.

bosun crew restart <name>

Restarts a specific container.

Manifest Commands

Render service manifests to compose/traefik/gatus configs.

provision

Render a stack or service manifest.

bosun provision <stack>
bosun provision <stack> -n
bosun provision <stack> -d
bosun provision <stack> -f prod.yaml

Flags:

Examples:

bosun provision core              # Render the 'core' stack
bosun provision core -n           # Dry run - preview output
bosun provision core -f prod.yaml # Apply production values

Output:

Creates files in the output directory:

• compose/<stack>.yml - Docker Compose file
• traefik/dynamic.yml - Traefik dynamic config
• gatus/endpoints.yml - Gatus monitoring endpoints

provisions

List available provisions.

bosun provisions

Example output:

Available provisions:
  - container
  - healthcheck
  - homepage
  - monitoring
  - postgres
  - redis
  - reverse-proxy

create

Scaffold new service from template.

bosun create <template> <name>

Templates:

Examples:

bosun create webapp myapp
bosun create api myapi
bosun create worker myworker

Creates a service manifest in manifest/services/<name>.yml.

migrate

Migrate manifests to the current schema, or convert legacy provision-based manifests to the Helm-aligned chart format. Both subcommands default to a dry-run.

bosun migrate version          # Add apiVersion/kind fields (dry-run)
bosun migrate version --write  # Apply the migration
bosun migrate helm             # Convert legacy manifests to Helm-aligned format
bosun migrate helm --force     # Overwrite existing charts

Radio Commands

Communication and connectivity commands.

radio test

Test webhook endpoint.

bosun radio test

Sends a GET request to http://localhost:8080/health to verify the webhook receiver is running.

radio status

Check Tailscale/tunnel status.

bosun radio status

Displays:

• Connection state (Running, Stopped, NeedsLogin)
• This device info (hostname, IP, DNS)
• Network info (tailnet, peer count)
• Online peers

Diagnostics Commands

status

Show yacht health dashboard.

bosun status

Displays:

• Crew status (running/total containers, health)
• Infrastructure (traefik, authelia, gatus)
• Applications (all other containers)
• Resources (memory, CPU, volumes)
• Recent activity

log

Show release history.

bosun log
bosun log <n>

Arguments:

Displays:

• Recent manifest changes (git log)
• Last provisions (file timestamps)
• Deploy tags

drift

Show drift between declared services (from deploy state) and actual running containers.

By default reads cached drift status from the deploy state file. The daemon updates this automatically on a configurable interval (default: 5 minutes). Use --live to perform a fresh check against Docker.

bosun drift                    # Show last cached drift result
bosun drift --live             # Check Docker right now
bosun drift --json             # Machine-readable output
bosun drift --live --json      # Live check with JSON output
bosun drift --project core     # Filter to a specific compose project
bosun drift --target=nas       # Show drift for a specific target

Flags:

Drift types:

Container matching: Uses Docker Compose v2 labels (com.docker.compose.project, com.docker.compose.service) for authoritative matching. Falls back to name-based parsing (<project>-<service>-<replica>) for containers without labels.

Target state resolution: With one configured named target and no --target, drift reads that target’s daemon-written state file (for example, deploy-state-nas.json). With multiple targets, it reports every target. When targets are configured, an unknown --target is an error instead of probing an arbitrary state filename. An explicit --state-file always reads exactly that path, but does not make an unknown configured target valid.

If the target is unknown, the requested state is missing, or the state cannot establish a deployment, drift exits nonzero without printing command usage. JSON output keeps "status": "unknown" and includes an "error" field so automation cannot mistake unknown state for a clean deployment.

doctor

Pre-flight checks - is the ship seaworthy?

bosun doctor

Checks:

• Docker running
• Docker Compose v2 installed
• Git installed
• Project root found
• Age key present
• SOPS installed
• Manifest directory exists
• SSH deploy key is a regular, non-empty file with owner-only permissions on POSIX; Windows reports that ACLs require separate inspection
• Webhook responding
• Restart breaker sampling cadence (BOSUN_DRIFT_INTERVAL should not exceed BOSUN_RESTART_WINDOW)
• Traefik configuration (if Traefik service detected):
  • HTTPS redirect configured
  • exposedByDefault set to false
  • Security headers middleware present
  • Docker socket not mounted directly (recommends docker-socket-proxy)

lint

Validate all manifests before deploy.

bosun lint
bosun lint [target]

Validates:

• Provisions exist
• Service manifests have required fields
• Stack manifests are valid
• Dependencies are correct
• No port conflicts

breaker

View and manage the deploy circuit breaker, which stops retrying after 3 consecutive deploy failures on the same commit. A new commit resets the counter.

bosun breaker status           # Show breaker state (failure count, open/closed)
bosun breaker reset            # Clear the failure counter to allow retries
bosun breaker reset --target=nas   # Reset for a specific target

ports

List host-port allocations across all stacks (from rendered compose files) and detect conflicts.

bosun ports                    # All host-port allocations + conflict detection
bosun ports --service traefik  # Ports for a specific service
bosun ports --free 8000-9000   # Available ports in a range

Upgrade Commands

upgrade traefik

Check and apply Traefik security and performance defaults.

bosun upgrade traefik                # Show recommendations (dry-run by default)
bosun upgrade traefik --yes          # Apply all recommendations without prompting
bosun upgrade traefik --dry-run      # Explicit dry-run mode
bosun upgrade traefik --compose ./compose/core.yml  # Specify compose file
bosun upgrade traefik --dynamic ./traefik/conf.d     # Specify dynamic config dir

Flags:

Checks performed:

Auto-detection: If --compose is not specified, bosun scans the output directory, project root, and bosun/ directory for compose files containing a traefik:* image or a service named traefik. Dynamic config directory is detected from Traefik volume mounts (paths containing conf.d, dynamic, or rules).

Template safety: If the compose file is a Go template (.tmpl extension or contains {{), fixes are displayed but not auto-applied.

Emergency Commands

mayday

Show recent errors across all crew.

bosun mayday
bosun mayday -l
bosun mayday -r <snapshot>
bosun mayday -r interactive

Flags:

Examples:

bosun mayday                    # Show recent errors
bosun mayday -l                 # List snapshots
bosun mayday -r interactive     # Interactive rollback menu
bosun mayday -r 2024-01-15_143022  # Rollback to specific snapshot

overboard

Force remove a problematic container.

bosun overboard <name>

Forcefully removes a container. Use with caution.

Daemon Commands

Run bosun as a long-running daemon for production GitOps deployments.

daemon

Run the GitOps daemon.

bosun daemon
bosun daemon -n
bosun daemon -p 9090
bosun daemon -i 1800

Flags:

Features:

• Unix socket API at /var/run/bosun.sock (primary)
• Optional TCP API with bearer token auth
• HTTP endpoints for webhooks and health checks
• Polling-based reconciliation
• Graceful shutdown on SIGTERM/SIGINT

Endpoints:

/health is intentionally unauthenticated and never includes reconcile errors, repository paths, subsystem messages, or circuit-breaker state. Use /status over the local Unix socket or authenticated TCP API for operator diagnostics.

GitLab, Gitea, and Bitbucket are not served by the daemon directly — use the standalone bosun webhook receiver (see below), which forwards normalized triggers to the daemon.

trigger

Trigger reconciliation via the daemon.

bosun trigger
bosun trigger -s "manual"
bosun trigger --socket /tmp/bosun.sock
bosun trigger --tcp localhost:9090 --token mytoken

Flags:

daemon-status

Show daemon health and state.

bosun daemon-status
bosun daemon-status --json
bosun daemon-status --socket /tmp/bosun.sock

Flags:

Output:

=== Bosun Daemon Status ===

  ● State: idle
    Uptime: 2h30m
    Last Reconcile: 5m ago
  ✓ Health: healthy
  ✓ Ready: true

daemon-status gets last-reconcile and last-error diagnostics from /status; the bounded /health response supplies only the displayed health and readiness.

validate

Validate configuration and daemon connectivity.

bosun validate
bosun validate --full
bosun validate --socket /tmp/bosun.sock

Flags:

Checks:

1. Environment variables (REPO_URL, etc.)
2. Daemon connectivity
3. Repository access
4. Full dry-run (with --full)

When daemon health is degraded, validate reads the sanitized last error from the local /status endpoint rather than from public /health output.

webhook

Run standalone webhook receiver.

bosun webhook
bosun webhook -p 9000
bosun webhook --fetch-secret

Flags:

The webhook receiver validates signatures and forwards valid requests to the daemon’s trigger endpoint. Supports GitHub, GitLab, Gitea, and Bitbucket webhook formats.

Its GET /health endpoint proxies only status, ready, and uptime, while GET /ready retains the plain readiness response. Both endpoints reject other HTTP methods with 405 Method Not Allowed.

Daemon-Injected Secrets:

Use --fetch-secret to have the webhook server fetch the secret from the daemon at startup. This way the secret is never stored on disk in the webhook container.

init –systemd

Generate systemd unit files for daemon deployment.

bosun init --systemd

Creates files in systemd/:

Installation:

cd systemd && sudo ./install.sh

GitOps Command

reconcile

Run the GitOps reconciliation workflow (one-shot mode).

bosun reconcile
bosun reconcile -n
bosun reconcile -f
bosun reconcile -l
bosun reconcile -r user@host
bosun reconcile --target=nas

Flags:

Workflow:

1. Acquire lock (prevent concurrent runs)
2. Clone/pull repository (go-git library, in-process)
3. Decrypt secrets (go-sops library, in-process)
4. Render templates (native Go text/template + Sprig)
5. Create backup of current configs
6. Deploy (native file copy or tar-over-SSH)
7. Docker compose up
8. SIGHUP to agentgateway
9. Release lock

Environment Variables:

BOSUN_GIT_USERNAME and BOSUN_GIT_TOKEN authenticate both clone and fetch for an absolute HTTPS repository URL. Set both or neither; anonymous HTTPS is unchanged. Bosun rejects URL-embedded credentials and will not forward the pair through an HTTP downgrade or cross-origin redirect. The variables have no unprefixed aliases, follow the effective BOSUN_REPO_URL-over-REPO_URL selection, and require a process restart to rotate.

Pirate Mode (Easter Egg)

bosun yarr

Shows command aliases for true pirates.

Command Aliases

All commands have nautical aliases: