CLI Reference

Global Flags

These flags are available on all commands:

Flag	Description
`--debug`	Enable debug logging
`--dry-run`	Perform dry runs without making changes
`--config-file <path>`	Configuration file path

parallax play

Execute an Ansible-compatible playbook.

parallax play [flags] <playbook>

Core Options

Flag	Default	Description
`-i, --inventory <source>`		Inventory source (file or comma-separated hosts)
`-C, --check`	`false`	Dry-run mode (no changes made)
`--start-at-task <name>`		Begin execution at a specific task
`-l, --limit <pattern>`		Further restrict hosts to a pattern
`-e, --extra-vars <vars>`		Set additional variables (key=value, @file, or JSON)
`--forks <n>`	`5`	Number of parallel processes
`-D, --diff`	`false`	Show file differences when changing files
`-v, -vv, -vvv`	`0`	Increase output verbosity; each task’s result is rendered from `-v` upwards
`--inject-facts-as-vars`	`true`	Expose every gathered fact as a top-level `ansible_<key>` variable in addition to the `ansible_facts` dictionary
`--json`	`false`	Output as JSON
`--quiet`	`false`	Suppress task and play output; only the exit status reports the outcome
`--callback <name>`	`default`	Callback plugin (default, minimal, json, timer, profile_tasks)

debug: prints without -v: the module asks for its payload to be rendered, so debug: msg=... and debug: var=... behave as they do under Ansible. A task’s verbosity: is a threshold — the message appears once the run’s verbosity reaches it, and the task is reported as skipped below it. The run’s level is readable from playbooks as {{ ansible_verbosity }}.

Authentication

Flag	Default	Description
`--private-key <file>`		SSH private key file
`--ask-pass`	`false`	Prompt for connection password
`-b, --become`	`false`	Enable privilege escalation
`--become-user <user>`	`root`	Privilege escalation user
`--become-method <method>`	`sudo`	Privilege escalation method (sudo, su, doas, pfexec)
`--ask-become-pass`	`false`	Prompt for privilege escalation password

The become password is delivered on the escalation helper’s standard input, so it never appears in the target’s process table. Not every method can accept one:

Method	Password support
`sudo`	Yes — read from stdin via `sudo -S`
`su`	Yes — read from stdin. SSH exec requests are served without a PTY, so `su` falls back from `/dev/tty` to standard input
`doas`	No. `doas` reads `/dev/tty` and has no stdin equivalent of `sudo -S`. Grant the login user a `nopass` rule in `doas.conf`; supplying a password is an error rather than being silently ignored
`pfexec`	No. `pfexec` authorises through RBAC profiles and never prompts

runas (WinRM) is the one exception: PowerShell’s ConvertTo-SecureString has no stdin form over this transport, so the password is still interpolated into the command and is visible to anything that can enumerate command lines on the target.

Flag	Description
`--tag <tag>`	Only run tasks with this tag (repeatable)
`--tags <tags>`	Only run tasks with these tags (comma-separated)
`--skip-tag <tag>`	Skip tasks with this tag (repeatable)
`--skip-tags <tags>`	Skip tasks with these tags (comma-separated)

SSH Configuration

Flag	Default	Description
`--ssh-user <user>`		Default SSH user
`--ssh-port <port>`	`22`	Default SSH port
`--ssh-timeout <duration>`	`30s`	Connection timeout
`--ssh-retries <n>`	`3`	Number of connection retries
`--ssh-retry-interval <duration>`	`5s`	Interval between retries
`--ssh-keepalive`	`true`	Enable SSH keepalive
`--ssh-keepalive-interval <duration>`	`30s`	Keepalive interval
`--use-agent`	`true`	Use SSH agent for authentication
`--agent-socket <path>`		Path to SSH agent socket
`--known-hosts <file>`		Path to known_hosts file
`--strict-host-checking`	`true`	Enable strict host key verification

Bastion / Jump Host

Flag	Default	Description
`--bastion-host <host>`		Bastion host address
`--bastion-port <port>`	`22`	Bastion SSH port
`--bastion-user <user>`		Bastion user (defaults to –ssh-user)
`--bastion-key <file>`		Bastion-specific SSH private key

Vault

Flag	Description
`--vault-id <label@source>`	Vault identity (repeatable)
`--vault-password-file <file>`	File containing vault password
`--ask-vault-pass`	Prompt for vault password

Connection Pooling

Flag	Default	Description
`--connection-pooling`	`false`	Enable SSH connection pooling
`--pool-max-connections <n>`	`20`	Maximum pooled connections
`--pool-max-idle <n>`	`5`	Maximum idle connections
`--pool-max-idle-time <duration>`	`30m`	Maximum idle time
`--pool-max-lifetime <duration>`	`2h`	Maximum connection lifetime
`--pool-acquire-timeout <duration>`	`30s`	Connection acquire timeout
`--pool-health-check-interval <duration>`	`5m`	Health check interval
`--pool-enable-health-check`	`true`	Enable health checks
`--pool-stats`		Display pool statistics (`show`)

Module Caching

Flag	Default	Description
`--cache`	`true`	Enable module binary caching
`--cache-dir <path>`	`~/.parallax/module-cache`	Cache directory
`--cache-info <action>`		Display cache info (`stats`, `list`)
`--cache-clear`	`false`	Clear all cached modules
`--cache-clear-module <name>`		Clear cache for specific module

Precompilation

Flag	Default	Description
`--precompile`	`false`	Precompile common modules before execution
`--precompile-background`	`false`	Background precompilation
`--precompile-modules <modules>`		Specific modules to precompile
`--precompile-concurrency <n>`		Parallel precompilation processes
`--precompile-current-platform`	`false`	Only precompile for current platform
`--precompile-quiet`	`false`	Suppress precompilation output
`--precompile-usage-stats`		Show module usage stats (`show`)
`--precompile-recommended`		Show recommended modules (`show`)

Facts Gathering

Flag	Default	Description
`--facts-parallel`	`true`	Parallel fact gathering
`--facts-concurrency <n>`	`10`	Max concurrent fact gatherers
`--facts-cache`	`true`	Enable facts caching
`--facts-cache-ttl <duration>`	`30m`	Facts cache TTL
`--facts-timeout <duration>`	`30s`	Gather timeout
`--facts-subset <subset>`	`all`	Facts subset to gather
`--facts-filter <pattern>`	`*`	Filter pattern
`--facts-directory <path>`	`/etc/ansible/facts.d`	Custom facts directory
`--facts-info`		Cache info (`stats`)
`--facts-cache-clear`	`false`	Clear facts cache
`--facts-incremental`	`true`	Incremental fact gathering
`--facts-incremental-threshold <n>`	`0.25`	Change threshold for re-gather
`--facts-force-full`	`false`	Force full fact gathering
`--facts-compression`	`true`	Enable facts compression
`--facts-compression-algorithm <alg>`	`gzip`	Compression algorithm
`--facts-compression-level <n>`	`6`	Compression level (1-9)
`--facts-auto-compression`	`true`	Auto-select compression
`--facts-compression-threshold <bytes>`	`1024`	Minimum size for compression

Template Caching

Flag	Default	Description
`--template-cache`	`true`	Enable template caching
`--template-cache-size <n>`	`1000`	Maximum cached templates
`--template-cache-max-age <duration>`	`1h`	Cache max age
`--template-cache-eviction-interval <duration>`	`5m`	Eviction interval
`--template-cache-info`		Display cache info (`stats`, `list`)
`--template-cache-clear`	`false`	Clear template cache

Resource Management

Flag	Default	Description
`--resource-management`	`false`	Enable resource management
`--module-timeout <duration>`		Global module execution timeout
`--max-memory <mb>`		Maximum memory in MB
`--max-cpu <percent>`		Maximum CPU usage percentage
`--max-execution-time <duration>`		Maximum total execution time
`--max-open-files <n>`		Maximum open file descriptors

Validation

Flag	Default	Description
`--validate-features`	`false`	Validate Ansible compatibility
`--strict-validation`	`false`	Treat unsupported features as errors
`--ignore-unsupported <feature>`		Ignore specific unsupported features (repeatable)
`--show-supported-modules`		Show supported modules (`show`)
`--show-unsupported-modules`		Show unsupported modules (`show`)
`--validation-enabled`	`true`	Enable module argument validation
`--validation-level <level>`		Level (basic, standard, strict, pedantic)
`--validation-show-warnings`	`true`	Show warnings

Debug

Flag	Default	Description
`--debug-enabled`	`false`	Enhanced debug mode
`--debug-level <level>`	`none`	Debug level (none, basic, verbose, trace)
`--debug-profiling`	`false`	Performance profiling
`--debug-tracing`	`false`	Execution tracing
`--debug-report`	`false`	Output debug report at end
`--debug-output <file>`		Debug output file

Plugins

Flag	Default	Description
`--plugin-dir <path>`		Additional plugin directories (repeatable)
`--preload-plugins`	`false`	Preload plugins at startup
`--plugin-timeout <duration>`	`30s`	Plugin execution timeout

Subcommands

parallax play list <playbook> – List tasks in playbook
parallax play exec <playbook> – Execute playbook (alternate form)

parallax validate

Validate playbook and inventory syntax without executing.

parallax validate [flags]

Flag	Description
`-p, --playbook <path>`	Path to playbook file
`-i, --inventory <source>`	Inventory file or host list

parallax vault

Ansible Vault compatible encryption/decryption operations.

parallax vault <subcommand> [flags]

Persistent Vault Flags

Flag	Description
`--vault-id <label@source>`	Vault identity (repeatable)
`--vault-password-file <file>`	File containing vault password
`--ask-vault-pass`	Prompt for vault password

vault encrypt

parallax vault encrypt <file>

Encrypt a file with Ansible Vault.

vault decrypt

parallax vault decrypt <file>

Decrypt a vault-encrypted file.

vault view

parallax vault view <file>

View the contents of a vault-encrypted file without decrypting it to disk.

vault edit

parallax vault edit <file>

Edit a vault-encrypted file in your $EDITOR.

vault encrypt_string

parallax vault encrypt_string [flags] <string>

Flag	Description
`--name <var>`	Variable name for YAML output

vault rekey

parallax vault rekey [flags] <files...>

Re-encrypt files with a new vault password.

Flag	Description
`--new-vault-password-file <file>`	File with the new password
`--new-vault-id <label@source>`	New vault identity

parallax doc

Module documentation commands.

parallax doc <subcommand> [flags]

doc show

parallax doc show <module>

Display documentation for a specific module.

doc list

parallax doc list

List all available modules.

doc generate

parallax doc generate [flags]

Generate static module documentation.

Flag	Default	Description
`--output-dir <path>`	`./docs/modules`	Output directory
`--format <format>`	`markdown`	Output format (`markdown`, `hugo`)

parallax plugins

Manage Parallax plugins.

parallax plugins <subcommand> [flags]

plugins init

parallax plugins init <type> <name> [flags]

Create a new plugin project skeleton.

Flag	Default	Description
`--module-path <path>`	`github.com/user/<name>`	Go module path override

Supported types: module, callback, connection, filter, inventory, lookup, strategy

plugins add

parallax plugins add <source> [flags]

Install a plugin from a git repository.

Flag	Default	Description
`--version <version>`	latest	Version to install
`--type <type>`		Plugin type
`--name <name>`		Override derived plugin name
`--no-build`	`false`	Clone only, skip building

plugins list

parallax plugins list [flags]

Flag	Description
`--type <type>`	Filter by plugin type

plugins remove

parallax plugins remove <name>

Remove an installed plugin.

plugins upgrade

parallax plugins upgrade <name> [flags]

Flag	Default	Description
`--version <version>`	latest	Target version

parallax tool

Tool-specific subcommands.

tool version

parallax tool version

Display version information including build commit.

parallax upgrade

Self-update the Parallax binary.

parallax upgrade [flags]

Aliases: self-update

Flag	Default	Description
`-v, --version <version>`	latest	Version to upgrade to
`--list`	`false`	List available versions
`--notes`	`false`	Show release notes for a version