muster deploy

Deploy services defined in muster.json. Executes hooks, runs health checks, and provides interactive failure recovery.

Quick Start

bash

muster deploy              # interactive: pick all or select services
muster deploy api          # deploy one service
muster deploy --dry-run    # preview deploy plan without executing
muster deploy --json       # stream deploy events as NDJSON
muster deploy --force      # override an existing deploy lock

Flags

Name	Type	Description
`--dry-run`	boolean	booleanPreview the deploy plan without executing any hooks or acquiring a lock.
`--json`	boolean	booleanStream deploy events as newline-delimited JSON (NDJSON). Disables interactive prompts.
`--force`	boolean	booleanOverride an existing deploy lock and proceed with the deploy.

Deploy Flow

Every deploy follows the same sequence:

Load config

Reads muster.json and auto-loads .env from the project root.

Acquire deploy lock

Prevents concurrent deploys (skip with --force).

Deploy password gate

If configured, prompts for deploy password.

Resolve services

Reads deploy_order from config, filters out skip_deploy: true services.

Interactive selection

If more than one service in a TTY, prompts “All services” or “Select services”.

Pre-authenticate SSH

Collects SSH passwords for remote services up front.

For each service

Run pre-deploy skill hooks, auto git pull, security check, execute deploy.sh, verify output, run post-deploy hooks, execute health.sh.

Release deploy lock

Lock is released whether deploy succeeds or fails.

Interactive Service Selection

When deploying all services in a TTY with more than one service, muster shows a menu: All services | Select services | Back.

In non-interactive mode (CI, scripts, --json), all services deploy without prompting.

bash

# Deploy a specific service directly (no menu)
muster deploy api

# Interactive selection when multiple services exist
muster deploy

Dry-Run Mode

muster deploy --dry-run previews the deploy plan without executing. It shows:

Hook file path
Credential key names
Health check status
Remote deploy target
Git pull configuration

Tip

Use --dry-run before your first deploy to verify that hooks, credentials, and remote targets are configured correctly.

Deploy Failure Recovery

When a deploy hook exits non-zero, muster:

Shows the last 5 log lines
Runs K8s diagnostics (if applicable)
Fires post-deploy skill hooks with MUSTER_DEPLOY_STATUS=failed
Presents an interactive recovery menu

Recovery options

Name	Type	Description
`Retry`	action	actionRe-run the deploy hook for the failed service.
`Rollback & restart`	action	actionRoll back to the previous version and restart (K8s only).
`Rollback <name>`	action	actionRoll back the named service to its previous version.
`Skip and continue`	action	actionSkip the failed service and continue deploying remaining services.
`Abort`	action	actionStop the deploy immediately. Already-deployed services remain deployed.

Warning

In non-interactive mode, deploy aborts immediately on failure (exit code 1). There is no recovery menu outside of a TTY.

Timeout

The default deploy timeout is 120 seconds. You can override it per-service via the deploy_timeout field in muster.json.

Name	Type	Description
`deploy_timeout`	number	numberSeconds before the deploy hook is killed. Exported as the `MUSTER_DEPLOY_TIMEOUT` environment variable. Produces exit code 124 on timeout. Default: `120`

muster.json

{
  "services": {
    "api": {
      "deploy_timeout": 300
    }
  }
}

JSON Mode

muster deploy --json streams newline-delimited JSON (NDJSON) events to stdout. This is useful for CI pipelines, custom dashboards, or programmatic consumption.

Event types

Name	Type	Description
`start`	event	eventEmitted when a service deploy begins.
`git_pull`	event	eventEmitted when an auto git pull is performed before deploying.
`log`	event	eventStreamed log lines from the deploy hook as they are produced.
`done`	event	eventEmitted when a service deploy finishes (success or failure).
`health`	event	eventResult of the health check for a service.
`verify_warning`	event	eventNon-blocking verification warning (empty logs, fast deploy, missing markers).
`dry_run`	event	eventPlan details emitted during a dry-run instead of executing.
`complete`	event	eventFinal event emitted when the entire deploy run finishes.

Muster acquires a deploy lock before executing hooks to prevent concurrent deploys against the same project. The lock is automatically released when the deploy completes (whether it succeeds or fails).

If another deploy is already running, muster will exit with an error. Use --force to override the lock and proceed anyway.

bash

# Override a stale deploy lock
muster deploy --force

Deploy Verification

After each successful deploy, muster runs three non-blocking checks. These produce warnings but do not fail the deploy:

Verification checks

Name	Type	Description
`Empty log`	warning	warningThe deploy hook produced no output. This may indicate the script did not run as expected.
`Fast deploy`	warning	warningThe deploy completed in less than 1 second. This may indicate the hook exited early without doing work.
`Missing markers`	warning	warningThe deploy output did not contain expected success markers. Review the logs to confirm the deploy succeeded.

Tip

These verification warnings help catch silent failures. If you see them consistently, inspect your deploy hook to make sure it is producing output and running the expected commands.

muster setup muster status