Operations and recovery

This task covers day-two operations. Labels per step: status and logs are state-writing observations; events, recovery, and diagnostics are read-only; cleanup --confirm-cleanup is mutating.

Every command here uses the resolved state database: --state-db <path>, then HOSTWRIGHT_STATE_DB, then the Application Support default. The examples pass --state-db explicitly; omit it to use the default. See State store.

Status: observe and record

hostwright status --state-db /tmp/hostwright.sqlite

Observes Apple container through the RuntimeAdapter, persists a status event and observed snapshot, and renders desired services against observed lifecycle, health, and port facts. It never mutates.

Logs: bounded and redacted

hostwright logs web --state-db /tmp/hostwright.sqlite --tail 200
hostwright logs web --state-db /tmp/hostwright.sqlite --follow

Reads the last log lines for an observed Hostwright-managed service. Default tail is 100 lines, clamped at 1000. Output is redacted before display. --follow streams new output when the selected runtime provider supports it. For a shell inside the service or a file transfer, see exec, attach, and copy in the interactive and streaming commands.

Events: the ledger, filtered

hostwright events --state-db /tmp/hostwright.sqlite \
  --severity error --type cleanup.failed --limit 20 --sort desc

Reads the persisted event ledger in deterministic order, with --project, --type, --service, --severity, --limit, and --sort filters. events reads an already-migrated database; it fails rather than creating or migrating one as a side effect.

Recovery: diagnose interrupted operations

hostwright recovery --state-db /tmp/hostwright.sqlite

Reads operation recovery groups and steps and reports whether each apply completed, failed, or was interrupted, including redacted lock owners and lease expiry for active groups. Recovery output distinguishes: no recovery required, manual inspection required, and rollback unsupported (no safe inverse operation is proven).

Once you have reviewed a held operation, hostwright recovery resume --group <uuid> --confirm-plan <hash> continues it, and hostwright recovery rollback --group <uuid> --confirm-plan <hash> applies only the precomputed inverse actions that are provably safe. Both re-observe current reality before acting; neither is automatic.

Diagnostic by default

The bare hostwright recovery command only inspects; it never observes the runtime, retries mutation, or changes anything. An interrupted operation’s plan can be resumed or rolled back only when its checkpoint proves the exact remaining or reversible work; anything ambiguous stays in a safe hold for manual inspection.

Diagnostics: a local, redacted bundle

hostwright diagnostics --state-db /tmp/hostwright.sqlite \
  --bundle /tmp/hostwright-diagnostics.json --project app-suite

Writes a redacted JSON bundle: telemetry policy (local-only, no upload), schema metadata, and redacted events, operations, health results, restart state, ownership records, and snapshots. It refuses to overwrite an existing bundle file and never uploads anything. The bundle can still contain local context (project names, paths, hostnames). Review before sharing.

Cleanup: dry-run, then exact token

# 1. Classify candidates and get the exact confirmation token.
hostwright cleanup --state-db /tmp/hostwright.sqlite --dry-run

# 2. Delete only what the token covers.
hostwright cleanup --state-db /tmp/hostwright.sqlite --confirm-cleanup <token>

The dry run classifies every candidate: eligible, ambiguous, stale, running (never deleted), unknown, blocked, never-delete. Confirmed cleanup deletes only eligible containers: exact Hostwright-owned created/stopped/exited containers covered by the current token. It never deletes images, volumes, networks, or unmanaged containers, and never uses --all or --force. A partial failure exits with code 72 and preserves the successful deletions in the report.

Next

• Events and diagnostics: the same surfaces in reference depth.
• Error and exit codes: what each failure means.