Skip to content
Install

Ansible command names

Which Volant command replaces each ansible-core program, what is the same, what differs, and how to keep your command lines.

Volant runs the nine programs of ansible-core 2.19.12. Each one is a volant subcommand, and on Linux and macOS it can also be started under its ansible name. Windows is not supported for the program names or for the links.

ansible-core program Volant command Runs in Managed runtime
ansible volant adhoc Volant not needed for the native modules
ansible-playbook volant playbook, volant-playbook Volant installed on first use that needs Python
ansible-vault volant vault Volant not needed
ansible-inventory volant inventory Volant not needed, except for inventory plugins of collections
ansible-doc volant doc ansible-core’s own tool installed on first use
ansible-config volant config ansible-core’s own tool installed on first use
ansible-galaxy volant galaxy Volant, being written: the subcommands are refused until they are native not needed
ansible-pull volant pull Volant not needed for a git checkout
ansible-console volant console Volant not needed for the native modules

The managed runtime installs itself the first time a command needs it, as it does for a playbook, and prints one line on standard error when it does. The managed runtime describes it. You do not need to install ansible, but two of the nine commands run ansible-core’s own code from that runtime.

The links are not made unless you ask. Either run the install script with --shims, or run volant shims install:

Terminal window
curl -fsSL https://volant.sh/install.sh | sh -s -- --shims
volant shims install

Each name is a symbolic link to volant. Volant reads the file name it was started as, so the link ansible-vault runs volant vault. Both commands take the same arguments and give the same output and exit codes. A usage error exits with 2 and names the program as started, ansible-vault: error: .... Like ansible-core, a link checks the locale before it reads its arguments. A locale it cannot set, or one that is not UTF-8, exits with 1 and ERROR: Ansible could not initialize the preferred locale or ERROR: Ansible requires the locale encoding to be UTF-8. LC_ALL=C is refused; with no locale variable set, the C locale counts as C.UTF-8. volant itself does not check.

install does not replace a file or link it did not make, unless you give --force. When another program of that name is on your PATH, it says so: note: /usr/bin/ansible-vault is hidden by this link, DIR comes first in PATH when the link wins, or note: ... still runs first, DIR comes later in PATH when it does not. To remove the links:

Terminal window
volant shims remove

remove deletes only links that point at a file called volant, and leaves everything else.

A CI script like this one runs unchanged once the links exist, with no ansible on the machine:

Terminal window
ansible-inventory -i hosts.ini --list > inventory.json
ansible-vault view group_vars/all/secrets.yml --vault-password-file ci-pass
ansible-playbook -i hosts.ini site.yml

For ansible, ansible-vault and ansible-inventory, the output, the options listed on the command pages and the exit codes were measured against ansible-core 2.19.12. Each claim has a test behind it.

Claim Where it is checked
volant adhoc prints the minimal callback’s bytes, the [ERROR] block and the -o and -t forms, with the reference’s exit codes the adhoc-* scenario goldens and crates/volant/tests/adhoc_cli.rs
The ansible name runs volant adhoc the_ansible_name_runs_adhoc
The ansible-playbook name runs volant playbook a_link_named_ansible_playbook_behaves_as_the_playbook_subcommand
volant vault gives ansible-vault’s messages, exit codes, file modes and files crates/volant/tests/vault_cli.rs, and the vault-* scenario goldens for the vault data a playbook reads
A file one tool encrypts, the other decrypts, for the default id and for a label a_file_one_tool_encrypts_the_other_decrypts
volant inventory prints ansible-inventory’s JSON and YAML bytes: key order, four-space indent, PyYAML anchors crates/volant/tests/inventory_golden.rs over golden/inventories/cases.yml, and inventory_cli.rs
volant config prints what the tool prints crates/volant/tests/tools_cli.rs
volant galaxy takes ansible-galaxy’s options and makes its first checks with the same messages crates/volant/src/galaxy/tests.rs, and galaxy_golden.rs against a fake Galaxy server
volant pull prints the playbook run and the -o line as ansible-pull does, and checks out without Python a_pull_prints_what_the_reference_pull_prints and a_pull_checks_out_and_runs_without_python in console_pull.rs
volant console prints what ansible-console prints for its commands, modules and shell lines on a pipe, and needs no Python for native modules the_console_reads_its_commands_from_a_pipe and the_console_runs_without_python in console_pull.rs
The links install makes, the lines it prints and what remove leaves alone crates/volant/tests/shims.rs
Which names map to which command, and no other name does the tests in crates/volant/src/cli/program.rs

The options each native command accepts are listed on its own page: volant adhoc, volant vault, volant inventory and volant pull. An option that is not listed there is refused, never ignored.

  • The help text is Volant’s. It is never compared with the reference.
  • --version prints ansible [core 2.19.12] (or the program’s name) and the paths. The Python, Jinja and PyYAML lines are left out when Volant finds no interpreter with ansible-core, because --version installs nothing. See volant adhoc.
  • executable location in --version is the program as it was started: volant, or the link. See volant doc.
  • ansible-inventory --toml needs no Python package, where the reference needs tomli-w, and a null value gives one [ERROR] line instead of a traceback (both exit 250). See volant inventory.
  • volant pull prints its first two lines before what its steps print, and its checkout starts no Python. See volant pull.
  • volant config dump shows COLLECTIONS_PATHS as set by the environment once the runtime has a collections/ directory. See volant config.
  • ansible-vault view goes through a pager only on a terminal, with PAGER, then ANSIBLE_PAGER, then [defaults] pager, then less. See Vault.
  • volant adhoc and volant playbook use Volant’s engine, so the differences listed in Will my playbook run? and on volant adhoc apply.
Command 0 1 2 4 5 250
volant adhoc every host succeeded or was skipped no host left to target, or a bad meta action a host failed, or a usage error a host was unreachable, or something this release does not support yet an invalid setting, or no argument for command an argument that is not valid JSON
volant vault done a file error, such as create on an existing file a usage error a bad option, such as two files with --output
volant inventory printed a usage error no action or two actions, or a bad --host or --graph target

volant playbook uses the codes on Exit codes. The three tools that run in ansible-core’s runtime return the tool’s own code, or 1 with an [ERROR]: line when the interpreter cannot be started. volant pull exits 2 when the checkout fails, 5 for an options error or when no playbook is found, and otherwise with the playbook’s code.