Job inspection and recovery

Automax provides job-scoped inspection commands for operators who need to verify what a job will touch before running it, diagnose a failed substep, reproduce the failed action manually and then restart from the next safe checkpoint.

These commands resolve the same job, inventory, variables, secrets, target filters and tag filters used by automax run. They are intentionally scoped to one job so the output describes the operation under review, not unrelated files or inventory entries.

Generate a review pack

Use automax review when the selected job needs one pre-run attachment for a change record, handover or operator approval. It does not create run state. It uses the same selectors as automax run and combines the focused inspection views into one masked Markdown or JSON report.

automax review \
  --job jobs/deploy.yaml \
  --inventory inventory/prod.yaml \
  --vars vars/prod.yaml \
  --limit web \
  --output review.md

automax review \
  --job jobs/deploy.yaml \
  --inventory inventory/prod.yaml \
  --secrets secrets/prod.yaml \
  --format=json

The report includes strict validation, selected targets, masked secret status, masked rendered vars, capability requirements, check-mode preview, diff/manual preview coverage, resume points and ready-to-copy operator commands. Reports that use --secrets are printed to stdout only; saved reports are reserved for reviews that do not load a secrets file.

Inspect selected targets

Use automax inventory show before a production run to confirm the resolved server set:

automax inventory show \
  --job jobs/deploy.yaml \
  --inventory inventory/prod.yaml \
  --vars vars/prod.yaml \
  --secrets secrets/prod.yaml \
  --limit web

The command prints only targets selected by the job after applying --limit, --exclude, --tags and --skip-tags.

Prepare SSH known_hosts entries

Use automax ssh known-hosts scan before the first SSH run when targets are not yet present in the configured known_hosts file:

automax ssh known-hosts scan \
  --inventory inventory/prod.yaml \
  --limit web \
  --output ~/.ssh/automax_known_hosts

Verify the printed fingerprints out-of-band before relying on the written file. Automax still uses strict host-key rejection during real SSH runs.

Render final variable context

Use automax vars render to see the final target-specific variable context, masked secret names and selected nodes before a run:

automax vars render \
  --job jobs/deploy.yaml \
  --inventory inventory/prod.yaml \
  --vars vars/prod.yaml \
  --secrets secrets/prod.yaml \
  --limit web01

Secrets are listed by name only and rendered as ***. This keeps the command safe for CI logs and issue attachments while still showing which secret keys are available to templates.

Check only secrets used by the selected job

Use automax secrets check to verify that required secret providers can be read without exposing secret values:

automax secrets check \
  --job jobs/deploy.yaml \
  --inventory inventory/prod.yaml \
  --secrets secrets/prod.yaml \
  --limit web

By default the command checks only secrets referenced by the resolved job plan. Use --all when you explicitly want to check every secret declared in the secrets file.

Preview check-mode behavior

Use automax plan --check when you want a dry-run style view of the selected substeps and their plugin-level check support:

automax plan --check \
  --job jobs/deploy.yaml \
  --inventory inventory/prod.yaml \
  --vars vars/prod.yaml \
  --secrets secrets/prod.yaml

automax run --check does not create run state. It prints a compact per-task summary by default for CI and smoke gates; add --verbose when you need the full per-target substep payload.

Preview file diffs

Use automax plan --diff to list every selected substep. File-oriented plugins that support deterministic previews include a unified diff; other plugins are shown with a reason explaining why no deterministic diff is available:

automax plan --diff \
  --job jobs/deploy.yaml \
  --inventory inventory/prod.yaml \
  --vars vars/prod.yaml \
  --secrets secrets/prod.yaml

Secret values rendered into previews are masked before output. Non-file or state-dependent plugins are still listed so operators can see the full selected job shape.

Compress or decompress standalone files

data.archive.tar.create already supports .tar.gz, .tar.bz2 and .tar.xz through compression: auto. Use data.compression.gzip.compress / data.compression.gzip.decompress for standalone .gz, .bz2 and .xz files that are not tar containers.

Preserve file content before regex replacements

fs.file.replace can create a pre-change backup before writing replacements:

- id: update_config
  use: fs.file.replace
  with:
    path: /etc/myapp/app.conf
    pattern: "^port=.*$"
    replacement: "port=8080"
    backup: true
    sudo: true

The backup is created only when the replacement actually changes the file. automax plan --diff cannot read the remote file during planning, so fs.file.replace emits a deterministic replacement plan showing path, regex, replacement, count and backup target instead of pretending to know the final remote diff.

Failed substep diagnostics

When a text run substep fails, Automax prints the rendered operator command plus masked stdout and stderr immediately below the failed status line. This makes a failed lab or production run actionable without first opening the SQLite state or re-rendering the command manually.

Example:

[FAILED] web01 task.deploy:step.install:substep.restart rc=1 remote command failed
  commands:
    $ sudo -n systemctl restart nginx
  stdout: <empty>
  stderr:
    Job for nginx.service failed because the control process exited with error code.

The same redaction policy used for persisted run state is applied to command, stdout and stderr diagnostics before printing. Successful substeps keep the compact one-line output; use automax commands render when every command needs to be displayed before execution.

Render manual recovery commands

When a job fails, render copy/pasteable commands for the same selected substeps:

automax commands render \
  --job jobs/deploy.yaml \
  --inventory inventory/prod.yaml \
  --vars vars/prod.yaml \
  --secrets secrets/prod.yaml \
  --limit web01 \
  --tags install

The output includes the target, host, checkpoint, plugin name and a sudo=yes/no marker before each command. Every selected substep is listed. If any rendered command contains sudo -n, the text output prints a sudo note: pasted manual commands require an existing sudo timestamp, while normal automax run or automax resume can use --sudo-password-env ENV_NAME. Plugins that cannot safely render a manual command are reported with a reason instead of inventing shell snippets.

A typical recovery loop is:

Run automax runs show <run-id> --failed to identify the failed checkpoint.
Run automax commands render with matching --limit and --tags filters.
Execute the printed command manually on the affected host or controller.
Fix the root cause outside Automax.
Restart from the next appropriate checkpoint with automax resume --from or automax run --from.

Machine-readable output

All inspection commands support JSON output for CI or operator tooling:

automax inventory show --job job.yaml --inventory inventory.yaml --format=json
automax secrets check --job job.yaml --inventory inventory.yaml --secrets secrets.yaml --format=json
automax vars render --job job.yaml --inventory inventory.yaml --format=json
automax commands render --job job.yaml --inventory inventory.yaml --format=json