Skip to content
Install

Command line

Every command and option Volant accepts, grouped by what they change, and the ansible-playbook options it does not have yet.

Terminal window
volant playbook [OPTIONS] <PLAYBOOK>...
volant-playbook [OPTIONS] <PLAYBOOK>...
volant adhoc [OPTIONS] <PATTERN>
volant config [ARGS...]
volant console [pattern] [OPTIONS]
volant doc [ARGS...]
volant galaxy [ARGS...]
volant pull -U URL [OPTIONS] [PLAYBOOK...]
volant inventory (--list | --host HOST) [OPTIONS]
volant runtime <install|pack|status|path|remove>
volant shadow replay RECORDING [--json]
volant compat install [-p PATH] [-f]
volant lock [--check]
volant shims <install|remove>
volant vault <encrypt|decrypt|view|create|edit|rekey|encrypt_string>
volant --version

Each other command has its own page: volant adhoc, volant check, volant config, volant compat, volant console, volant doc, volant galaxy, volant pull, volant inventory, volant lock, volant runtime, volant shadow, volant shims, volant vault. Ansible command names ties them together. This page covers volant playbook.

volant playbook takes the same options as ansible-playbook, for the ones that exist. volant-playbook is the same program under a name that reads like the one you know. Playbooks given together run in order, and each one prints its own recap.

On Linux and macOS the volant binary also dispatches on the name it was started as (the file name of argv[0]). Started as ansible-playbook, ansible-vault, ansible-doc, ansible-config, ansible-galaxy, ansible-console, ansible-pull or ansible-inventory, through a symlink or a hard link, it behaves as volant playbook, volant vault, volant doc, volant config, volant galaxy, volant console, volant pull or volant inventory with the same arguments, output and exit codes. Started as ansible, it behaves as volant adhoc. volant doc and config run ansible-core’s own tools from Volant’s Python runtime. volant galaxy is being made native and refuses each subcommand until it is. volant pull and volant console are Volant’s own; volant pull and volant console list how they differ. A usage error exits with 2 and names the program as started. Any other name keeps the usual volant behaviour.

Where an option has an ansible.cfg key or an environment variable, the entry names it. The option wins over both; Configuration explains the order.

An inventory source: a file, a directory, a script or a comma list of hosts. Repeat it to merge several, see Inventories. Without one, only the implicit localhost exists.

ansible.cfg
[defaults] inventory
Environment
ANSIBLE_INVENTORY

Run only on hosts matching this pattern. A limit that matches no host warns and narrows the run to what it did match.

Start at the first task named NAME; * and ? match any text. The tasks in front of it are left out, Gathering Facts apart, and so are the plays in front of the one that holds it. Only tasks written in the play are searched, as in ansible-playbook: a task an include_tasks or include_role reads while the run goes is not found. A name nothing matches prints the plays with an empty recap, then an error, and exits 0.

Ask before each task: y runs it, n or anything else skips it, c runs it and every task after it without asking. It needs a terminal; without one the run stops with exit code 250 before it touches a host.

Remove the fact cache entries of the inventory hosts before the run.

Print the Volant version and the ansible-core release it matches, then stop.

Log in to hosts as this user. Without it, ssh picks the user, from your ~/.ssh/config or your local account.

ansible.cfg
[defaults] remote_user
Environment
ANSIBLE_REMOTE_USER

The connection plugin for hosts that name none: ssh or local. A host’s ansible_connection and a play, block or task connection keyword both win over it. Any other name fails the task with the connection plugin '<name>' was not found.

The private key ssh authenticates with, passed as ssh -i.

ansible.cfg
[defaults] private_key_file
Environment
ANSIBLE_PRIVATE_KEY_FILE

Arguments added to every ssh command line. Volant splits them into words as a shell would, and an unbalanced quote stops the run before it starts. The host variable ansible_ssh_common_args replaces this value for that host.

Arguments added to the ssh command line after the common ones. The host variable ansible_ssh_extra_args replaces this value for that host.

How long to wait for a connection, passed to ssh as ConnectTimeout.

Default
10
ansible.cfg
[defaults] timeout
Environment
ANSIBLE_TIMEOUT

How many hosts a play works on at once. Zero or a value that is not a number is rejected before the run starts.

Default
5
ansible.cfg
[defaults] forks
Environment
ANSIBLE_FORKS

Directories searched for modules before the configured ones. Colon-separated and repeatable. A later -M goes in front of an earlier one.

Extra variables, at the top of the precedence order: key=value pairs, inline JSON or YAML, or @file. Repeatable.

Run only tasks with these tags. Comma-separated and repeatable, and added to the configured default rather than replacing it. See Tags and listings.

ansible.cfg
[tags] run
Environment
ANSIBLE_RUN_TAGS

Skip tasks with these tags. Comma-separated and repeatable, and added to the configured default.

ansible.cfg
[tags] skip
Environment
ANSIBLE_SKIP_TAGS

These options read the playbooks and stop. They never connect to a host and never stop on an unsupported module, so they work on playbooks this release cannot run yet.

List the tasks the run would execute, in Ansible’s format.

List the tags the run would select.

List the hosts each play would run on, in inventory order.

Load and compile the playbooks without running anything.

Run tasks with privilege escalation. A become keyword in the playbook still decides for its own play, block or task. See Privilege escalation.

Default
false
ansible.cfg
[privilege_escalation] become
Environment
ANSIBLE_BECOME

The user to escalate to.

Default
root
ansible.cfg
[privilege_escalation] become_user
Environment
ANSIBLE_BECOME_USER

The escalation method: sudo or su. Other methods stop the run before it starts.

Default
sudo
ansible.cfg
[privilege_escalation] become_method
Environment
ANSIBLE_BECOME_METHOD

Ask for the SSH password on the terminal, with echo turned off. ssh gets it through SSH_ASKPASS, so it needs OpenSSH 8.4 or later. The password is in no command line, no environment sent to the host and no log. After -k, an empty answer to the -K prompt reuses the SSH password, as in ansible-playbook.

Read the SSH password from the first line of this file. It conflicts with -k.

Read the escalation password from the first line of this file. It conflicts with -K.

Ask for the escalation password on the terminal, with echo turned off. The password is written once to sudo and appears in no command line, log or result.

Ask for the vault password on the terminal, with echo turned off.

A file holding the vault password, or an executable that prints it. Repeatable.

ansible.cfg
[defaults] vault_password_file
Environment
ANSIBLE_VAULT_PASSWORD_FILE

A vault identity: the source is a file, an executable or prompt. Repeatable. Every password is tried on every vaulted value, whatever its label. See Vault.

ansible.cfg
[defaults] vault_identity_list
Environment
ANSIBLE_VAULT_IDENTITY_LIST

Run notified handlers even on hosts that failed. A force_handlers keyword on the play takes priority. See Handlers.

Default
false
ansible.cfg
[defaults] force_handlers
Environment
ANSIBLE_FORCE_HANDLERS

Report what each task would change without changing it. A task’s own check_mode keyword wins over this option, so a task with check_mode: false still runs for real. A host with no Python cannot answer apt, user, group or file under --check or --diff: those modules need it, and the task fails. See Check mode and diff.

Default
false

Print the changes modules make to files, the way ansible-playbook does. A task’s own diff keyword wins over this option, so diff: false keeps a task’s changes off the screen. A host with no Python cannot answer apt, user, group or file under --diff: those modules need it, and the task fails. See Check mode and diff.

Default
false

Show module results for successful tasks too. Repeatable, like Ansible’s -vvv. A result carries its invocation key, the arguments the module received, only from -vvv on. At -vvvv the run also prints every option it was given, the plugins it loads and the ssh commands it runs.

Print without colors. The option beats force_color (ANSIBLE_FORCE_COLOR), which beats nocolor. See Configuration.

ansible.cfg
[defaults] nocolor
Environment
ANSIBLE_NOCOLOR

Where gathered facts come from. auto uses the agent’s native setup when every fact the plays can read is one it produces, and ansible-core’s setup module otherwise. python always runs the Python module, to compare against. native always asks the agent’s collector, and facts it does not produce are then undefined. On a host other than Debian or Ubuntu the native collector hands the task back to the Python module whatever this option says. See Facts.

Default
auto

Refuse the run with exit code 4, before any connection, when the installed collections, roles, runtime or Volant differ from volant.lock. Without it, each difference is a warning.

After the recap, print on standard error where the run’s time went: the controller’s phases per host, then for each module the path its tasks took (native, python or fallback), their times, and why a native module handed a task back. The first line says where facts came from and why.

Volant reads the ANSIBLE_* variables named above, plus a few of its own.

The Python interpreter the controller uses to build module payloads. It needs ansible-core. When set, Volant uses it alone and installs nothing. Which interpreter a run uses gives the full order.

Whether Volant may use and install its own Python. See The managed runtime.

ansible.cfg
[volant] runtime

A directory that holds the agent binaries. It is checked first, before the agents built into the release controller and the directory of the volant executable. Useful with a controller built from source, or to test an agent of your own.

ansible.cfg
[volant] batching

How a controller src that a managed host named is treated. See host_named_paths.

ansible.cfg
[volant] host_named_paths

The controller directories a fetch may write under when a managed host named its dest. See host_named_dest_dirs.

ansible.cfg
[volant] host_named_dest_dirs

With 0, every task runs ansible-core’s Python module instead of the agent’s native version. See Native modules.

ansible.cfg
[volant] native_modules

With 0, every ssh run opens its own connection instead of sharing one per inventory host.

ansible.cfg
[volant] ssh_control_master

Write the run’s profile to this file, one JSON object per line: the native modules each agent reported, then the phases, then one line per task with its module, path, hand-back reason and times in microseconds. It is written whatever became of the run, and a file that cannot be written only prints a warning.

Every ansible-playbook option is accepted. --scp-extra-args and --sftp-extra-args have no effect, because files move over the agent link. The parity page lists each option with its status.

volant has the subcommands playbook, adhoc, check, inventory, runtime, lock, shadow, shims, compat, vault, doc, config, galaxy, console and pull. There is no volant lint. Run ansible-lint for that. volant check says whether Volant can run a playbook. --check is a different option: it runs the playbook in check mode against hosts.