CLI Reference

CLI Reference

Complete reference for every strut command, flag, and subcommand. Each command supports --help for inline usage (e.g. strut my-stack backup --help).

strut <stack> <command> [--env <env>] [options]

Global Flags

Flag	Description
--env <name>	Environment name (reads .<name>.env)
--services <profile>	Service profile: messaging, ui, full
--json	JSON output (where supported)
--dry-run	Preview destructive operations without executing
--no-tui	Disable the interactive TUI (since v0.19.0)
STRUT_NO_TUI=1	Env-var equivalent of --no-tui (since v0.19.0)

Top-Level Commands

These don't require a stack name:

Command	Description
strut	Interactive TUI picker (stack → command → env) when stdin is a tty (since v0.19.0)
strut --print	Same as strut but prints the resolved command instead of running it (since v0.19.0)
strut init [--registry <type>] [--org <name>]	Initialize a new project with strut.conf
strut list	List all available stacks
strut list plugins [--json]	List discovered project plugins (since v0.17.0)
strut help <plugin>	Show a project plugin's help text (since v0.17.0)
strut scaffold <name> [--recipe <recipe>]	Create a new stack from templates (optionally from a recipe, since v0.18.0)
strut scaffold list [--json]	List available scaffold recipes (since v0.18.0)
strut upgrade	Upgrade strut to latest version
strut --version	Show installed version
strut skills [list|install] [--format <fmt>]	AI agent context management
strut audit <host> [user] [key] [port]	Audit a VPS
strut audit:list	List past audits
strut audit:generate <name> --from <dir>	Generate stack from audit
strut migrate <host> [user] [port] [key] [--yes]	Run migration wizard
strut migrate:status	Show migration status
strut monitoring <subcommand>	Monitoring stack management
strut doctor [--check-vps] [--json] [--fix]	Diagnostic environment check (includes SSH key perms)
strut status-all [--env <name>] [--json]	Dashboard showing every stack at once (since v0.11.0)
strut posture [--stack <name>] [--category <c>] [--fail-on <lvl>] [--json]	Security/ops posture check (since v0.11.0)
strut group list|show|add|remove|<name> <cmd>	Stack group dispatcher (since v0.15.0)
strut notify test <slack|discord|webhook>	Send test notification (since v0.9.0)
strut completions <bash|zsh|fish>	Print shell completion script (since v0.17.0)
strut init --completions	Auto-install completions for current shell (since v0.17.0)

Per-Stack Commands

All require: strut <stack> <command> [--env <name>]

Deployment

Command	Description
release [--services <profile>]	Full VPS release: update repo → migrate → deploy → verify
deploy [--services <profile>] [--pull-only] [--skip-validation] [--force-unlock] [--no-lock] [--blue-green|--standard] [--force-local]	Deploy stack containers (concurrency-locked since v0.13.0; blue-green since v0.20.0)
rebuild [--no-cache] [--pull]	Build images on target + deploy (since v0.22.0)
stop [--volumes] [--timeout N]	Stop running containers
update	Pull latest strut code on VPS (no container restart)
diff [--json]	Preview pending env/image changes vs VPS (since v0.13.0)
lock <status|release> [--force] [--remote|--local]	Inspect/manage deploy concurrency locks (since v0.13.0)

Monitoring & Status

Command	Description
health [--json]	Run health checks against services.conf
logs [service] [--follow] [--since <dur>]	View service logs
logs:download [service] [--since <dur>]	Download logs to local
logs:rotate	Rotate log files
status	Show container status

Database Operations

Command	Description
backup [postgres|neo4j|mysql|sqlite|all]	Create backups
backup offsite <status|sync|list|restore <file>>	Offsite backup sync to S3/R2/B2 (since v0.16.0)
restore <file>	Restore from backup file
db:pull [type] [--download-only] [--file <name>]	Pull backup from VPS, restore locally
db:push [type] [--upload-only] [--file <name>]	Push local backup to VPS, restore remotely
db:schema [apply|verify|all]	Apply or verify Postgres schema SQL
migrate [neo4j|postgres] [--status|--up|--down N]	Run database migrations

Configuration Management

Command	Description
validate	Validate all config files against expected schemas
drift [detect|report|fix|auto-fix|history]	Configuration drift detection
keys <subcommand>	Key management (SSH, API, env, db, GitHub)
volumes [status|init|config]	Volume management
domain <domain> <email> [--skip-ssl]	Configure domain and SSL
rollback [--list] [--dry-run]	Roll back to previous deploy snapshot (blue-green: flips active color, since v0.20.0)
rollback diff <ref_a> <ref_b> [--json]	Diff images between two snapshots; refs: HEAD, HEAD~N, basename (since v0.16.0)
prune [--volumes] [--all] [--no-protect]	Prune docker resources; --no-protect skips rollback-image protection (since v0.16.0)

VPS Access

Command	Description
shell	SSH to VPS (interactive)
exec <command>	Execute single command on VPS
remote:init [--host <h>] [--user <u>] [--key <k>] [--repo <url>]	Bootstrap strut on a remote VPS (since v0.21.0)

Debugging

Command	Description
debug exec <service> <command>	Execute command in container
debug shell <service>	Open interactive shell in container
debug port-forward <service> <local>:<remote>	Forward port from container
debug copy <service> <source> <dest>	Copy files to/from container
debug snapshot <service>	Create container snapshot
debug inspect-env <service>	Show environment variables
debug stats <service>	Show real-time resource usage

Local Development

Command	Description
local start [--services <profile>]	Start stack locally
local stop	Stop local stack
local reset	Reset local environment
local sync-env --from <env>	Sync env vars from production
local sync-db --from <env> [target] [--anonymize]	Sync database from production
local logs [--follow]	Tail local logs
local test	Run local smoke tests

Monitoring Commands

strut monitoring deploy                              # Deploy monitoring stack
strut monitoring add-target <stack> [env]             # Add stack to monitoring
strut monitoring remove-target <stack>                # Remove from monitoring
strut monitoring alert-channel add <type> [options]   # Configure alerts
strut monitoring alert-channel test [type]            # Test alert delivery
strut monitoring status [--json]                      # Show monitoring status

Stack Groups (since v0.15.0)

Groups are declared in groups.conf (INI-style) and run a strut command across every stack in the group.

strut group list                                           # List all groups
strut group show <name>                                    # List members of a group
strut group add <name> <stack>                             # Append a stack
strut group remove <name> <stack>                          # Remove a stack
strut group <name> <command> [--env <env>] [--stop-on-error] [--json]
strut group <name> logs [--follow] [--since <dur>] [--grep <pat>] [--service <svc>]

group <name> logs multiplexes logs across every member with a colored [stack] prefix. All other commands shell out to strut <stack> <command> per member and collect pass/fail. See Stack Groups.

Notifications (since v0.9.0)

strut notify test slack            # Send a test event to SLACK_WEBHOOK
strut notify test discord
strut notify test webhook

Providers are configured in notifications.conf at the project root. See Notifications.

Service Profiles

Profile	Description
(none)	Core services (default compose file)
gdrive	Core + Google Drive ingestion
messaging	Core + messaging service
ui	Core + UI service
full	All services

Examples

# Full production release (recommended)
strut my-app release --env prod

# Preview before deploying
strut my-app release --env prod --dry-run

# Deploy with all services
strut my-app deploy --env prod --services full

# Health check with JSON output
strut my-app health --env prod --json

# Follow logs for a specific service
strut my-app logs api --follow --env prod

# Backup all databases
strut my-app backup all --env prod

# Pull production database locally
strut my-app db:pull --env prod

# Check for config drift
strut my-app drift detect --env prod

# Rotate database passwords
strut my-app keys db:rotate postgres --env prod

# Configure domain with SSL
strut my-app domain api.example.com admin@example.com --env prod

# List all stacks
strut list

# Create a new stack
strut scaffold my-new-app

# Cross-stack dashboard
strut status-all --env prod
strut status-all --env prod --json

# Security/ops posture audit (CI-friendly exit codes)
strut posture
strut posture --category secrets --fail-on warn --json

# Preview deploy changes vs VPS
strut my-stack diff --env prod

# Blue-green deploy (zero-downtime swap)
strut my-stack deploy --env prod --blue-green
strut my-stack deploy --env prod --blue-green --dry-run
strut my-stack rollback --env prod                 # flips back to drained color

# Diff two rollback snapshots
strut my-stack rollback diff HEAD~1 HEAD
strut my-stack rollback diff 20260420-091500 HEAD --json

# Group operations
strut group list
strut group vps-1 deploy --env prod
strut group vps-1 logs --follow

# Offsite backup sync
strut my-stack backup offsite status --env prod
strut my-stack backup offsite sync --env prod
strut my-stack backup offsite list --env prod