CLI reference

Validate

automax validate --job job.yaml --inventory inventory.yaml

Useful options:

--vars PATH
--secrets PATH
--var KEY=VALUE
--tags TAGS
--skip-tags TAGS

Review

automax review --job job.yaml --inventory inventory.yaml --output review.md
automax review --job job.yaml --inventory inventory.yaml --secrets secrets.yaml --format=json

Builds a masked pre-run operator review report from the selected job. The report combines strict validation, selected targets, masked secret status, masked rendered vars, capability requirements, check preview, diff/manual preview coverage, resume points and ready-to-copy operator commands. Review reports that use --secrets are printed to stdout only; --output is accepted only when the review does not load a secrets file.

Approval gates

automax approval create --job job.yaml --inventory inventory.yaml --approved-by change-1234 --output approval.json
automax approval verify --job job.yaml --inventory inventory.yaml --approval approval.json
automax run --job job.yaml --inventory inventory.yaml --approval approval.json

Approval files are secret-free JSON gates for reviewed plans. Create and verify them without --secrets; execution may still pass --secrets because the gate compares the secret-free review digest.

Plan

automax plan --job job.yaml --inventory inventory.yaml

Prints target, checkpoint, plugin and tags without executing the job.

Check-mode preview for the selected job:

automax plan --check --job job.yaml --inventory inventory.yaml

File diff preview for supported file-oriented plugins:

automax plan --diff --job job.yaml --inventory inventory.yaml
automax plan --diff --job job.yaml --inventory inventory.yaml --format=json

Machine-readable output:

automax plan --job job.yaml --inventory inventory.yaml --format=json

Run

automax run --job job.yaml --inventory inventory.yaml --state-dir .automax/runs

For sudo-enabled remote substeps on targets that require a sudo password, pass the controller-side environment variable name instead of configuring passwordless sudo on the target:

export AUTOMAX_SUDO_PASSWORD='...'
automax run --job job.yaml --inventory inventory.yaml --sudo-password-env AUTOMAX_SUDO_PASSWORD

Preview the selected run without creating run state. By default this prints a compact per-task summary; add --verbose to show every per-target substep preview.

automax run --check --job job.yaml --inventory inventory.yaml
automax run --check --verbose --job job.yaml --inventory inventory.yaml

Machine-readable final summary:

automax run --job job.yaml --inventory inventory.yaml --format=json

Restart from an explicit checkpoint in a new run:

automax run --job job.yaml --inventory inventory.yaml --from task.install

automax run --job job.yaml --inventory inventory.yaml --from task.install:step.packages

automax run --job job.yaml --inventory inventory.yaml --from task.install:step.packages:substep.nginx

Capabilities

Inspect job-scoped remote tool requirements and install only the missing dependency packages for the selected job and targets:

automax capabilities requirements --job job.yaml --inventory inventory.yaml
automax capabilities install --job job.yaml --inventory inventory.yaml --sudo-password-env AUTOMAX_SUDO_PASSWORD

capabilities install prints live check/plan/install status plus a compact summary. Successful install command stdout/stderr is suppressed by default; add --verbose when troubleshooting package-manager output. --format=json keeps the full masked stdout/stderr payload for automation.

automax capabilities install --job job.yaml --inventory inventory.yaml --sudo-password-env AUTOMAX_SUDO_PASSWORD --verbose

Resume

automax resume <run-id> --state-dir .automax/runs

Resume modes:

automax resume <run-id> --skip-successful
automax resume <run-id> --only-failed
automax resume <run-id> --from task.deploy:step.restart:substep.service
automax resume <run-id> --skip-successful --sudo-password-env AUTOMAX_SUDO_PASSWORD

Runs

automax runs list --state-dir .automax/runs
automax runs show <run-id> --state-dir .automax/runs
automax runs show <run-id> --failed
automax runs show <run-id> --server web01
automax runs show <run-id> --json
automax runs export <run-id> --state-dir .automax/runs --output evidence.md
automax runs export <run-id> --state-dir .automax/runs --format json --output evidence.json
automax runs bundle <run-id> --state-dir .automax/runs --output automax-evidence.zip

OS information

Detect operating-system release facts for inventory targets before capability planning or dependency installation:

automax os info --inventory inventory.yaml
automax os info --inventory inventory.yaml --limit web --format=json

The output includes ID, ID_LIKE, pretty release name, version, codename, normalized family (debian, rhel or unknown) and package manager.

Inventory inspection

Show the inventory targets selected by a specific job:

automax inventory show --job job.yaml --inventory inventory.yaml
automax inventory show --job job.yaml --inventory inventory.yaml --limit web
automax inventory show --job job.yaml --inventory inventory.yaml --format=json

Vars render

Render the final target-specific variable context for the selected job while masking all secret values:

automax vars render --job job.yaml --inventory inventory.yaml --vars vars.yaml --secrets secrets.yaml
automax vars render --job job.yaml --inventory inventory.yaml --limit web01
automax vars render --job job.yaml --inventory inventory.yaml --format=json

Secrets check

Check secret providers referenced by the selected job without printing values:

automax secrets check --job job.yaml --inventory inventory.yaml --secrets secrets.yaml
automax secrets check --job job.yaml --inventory inventory.yaml --secrets secrets.yaml --all
automax secrets check --job job.yaml --inventory inventory.yaml --secrets secrets.yaml --format=json

Plugins

Inspect builtin and external plugins:

automax plugins list
automax plugins describe fs.file.template
automax plugins coverage --strict
automax plugins audit

Create, validate and package an external plugin source file:

automax plugins init company.echo --output ./plugins
automax plugins check ./plugins
automax plugins check ./plugins --format=json
automax plugins package ./plugins --output dist/company-plugins.zip
automax plugins package ./plugins --output dist/company-plugins.zip --automax-requires '>=1.0.0'
automax plugins verify-package dist/company-plugins.zip
automax plugins index dist/company-plugins.zip --output dist/automax-plugins-index.json
automax plugins verify-package dist/company-plugins.zip --format=json
automax plugins install dist/company-plugins.zip --dest .automax/plugins
automax plugins installed --dest .automax/plugins
automax plugins installed --dest .automax/plugins --format=json
automax plugins update dist/company-plugins.zip --dest .automax/plugins
automax plugins uninstall company-plugins.zip --dest .automax/plugins
automax plugins describe company.echo --plugin-path ./plugins
automax plugins describe company.echo --plugin-path dist/company-plugins.zip
automax plugins describe company.echo --plugin-path .automax/plugins

plugins check loads only the external plugin path and validates the public metadata contract: canonical name, description, category, parameter schemas, examples and result fields. plugins package runs the same check before writing a ZIP archive with the plugin sources, automax-plugin.json, Automax compatibility metadata and per-file SHA-256 checksums. plugins verify-package checks the manifest, canonical plugin names, file list, sizes and checksums. plugins index verifies one or more package ZIPs and writes a deterministic automax-external-plugin-index-v1 JSON file for repository publishing or change records. Verified package ZIPs can be used directly with --plugin-path without an unpack step; Automax validates manifest entries and checksums before loading the packaged Python plugin sources. plugins install copies a verified ZIP into a local plugin directory, records its checksum in automax-plugins.lock.json, plugins update replaces an installed package only after verification, and plugins uninstall removes both the ZIP and its lock entry. Normal --plugin-path .automax/plugins commands load installed packages from that directory and reject lock mismatches, missing locked packages and unmanaged ZIPs when a plugin lock is present.

Manual commands

Render copy/pasteable commands for selected substeps when a failed operation must be reproduced manually before restarting from a checkpoint:

automax commands render --job job.yaml --inventory inventory.yaml
automax commands render --job job.yaml --inventory inventory.yaml --limit web01 --tags install
automax commands render --job job.yaml --inventory inventory.yaml --format=json
# unavailable plugins are listed with an explicit reason instead of omitted

Text output marks each node with sudo=yes/no and prints a sudo note when rendered manual commands contain sudo -n. JSON output includes top-level uses_sudo/sudo_note fields and per-node uses_sudo flags for operator tooling.

SSH known_hosts scan

Scan SSH host keys for direct hosts or inventory-selected targets. The command prints fingerprints so operators can verify them over a trusted channel before using the generated known_hosts file:

automax ssh known-hosts scan --host web01.example.com
automax ssh known-hosts scan --inventory inventory/prod.yaml --limit web
automax ssh known-hosts scan --inventory inventory/prod.yaml --limit web --output ~/.ssh/automax_known_hosts
automax ssh known-hosts scan --host web01.example.com --format=json

Artifacts

automax artifacts list <run-id> --state-dir .automax/runs
automax artifacts path <run-id> --state-dir .automax/runs

Plugins

automax plugins list
automax plugins describe fs.file.template
automax plugins describe fs.file.template --json
automax plugins coverage
automax plugins coverage --format=markdown --output plugin-coverage.md
automax plugins coverage --strict
automax plugins audit

Schema export

automax schema export --kind job --format=json --output automax-job.schema.json
automax schema export --kind inventory --format=json

Documentation helpers

automax docs generate-plugins --output docs/plugins/generated.md

Explain

Inspect a resolved job without creating run state:

automax explain --job jobs/deploy.yaml --inventory inventory/prod.yaml
automax explain --job jobs/deploy.yaml --inventory inventory/prod.yaml --format=json

Graph

Render a resolved job graph:

automax graph --job jobs/deploy.yaml --inventory inventory/prod.yaml --format=mermaid
automax graph --job jobs/deploy.yaml --inventory inventory/prod.yaml --format=svg --output /tmp/job.svg
automax graph --job jobs/deploy.yaml --inventory inventory/prod.yaml --format=png --output /tmp/job.png

Runbook export

Export a Markdown runbook from a resolved job:

automax runbook export --job jobs/deploy.yaml --inventory inventory/prod.yaml --output /tmp/runbook.md

Run locking

Protect job and target concurrency with file-based locks:

automax run --job jobs/deploy.yaml --inventory inventory/prod.yaml --lock
automax resume <run-id> --lock --skip-successful

Retry policies

Retry policies are declared in job YAML, not as CLI flags. They can be inherited from job, task or step level and overridden on a substep:

retry:
  attempts: 3
  delay: 2
  backoff: exponential
  max_delay: 10

Text output prints [RETRY] lines for visible retry attempts before the final node result.