---
name: "ansible"
section: "1"
platform: "linux"
package: "ansible-core"
version: "2.21.5-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/ansible"
---

# ansible(1)

Define and run a single task 'playbook' against a set of hosts

## Name

ansible - Define and run a single task 'playbook' against a set of hosts

## SYNOPSIS

- **usage: ansible \[-h\] \[--version\] \[-v\] \[-b\] \[--become-method BECOME\_METHOD\]**

  \[--become-user BECOME\_USER\] \[-K \| --become-password-file BECOME\_PASSWORD\_FILE\] \[-i INVENTORY\] \[--list-hosts\] \[-l SUBSET\] \[--flush-cache\] \[-P POLL\_INTERVAL\] \[-B SECONDS\] \[-o\] \[-t TREE\] \[--private-key PRIVATE\_KEY\_FILE\] \[-u REMOTE\_USER\] \[-c CONNECTION\] \[-T TIMEOUT\] \[--ssh-common-args SSH\_COMMON\_ARGS\] \[--sftp-extra-args SFTP\_EXTRA\_ARGS\] \[--scp-extra-args SCP\_EXTRA\_ARGS\] \[--ssh-extra-args SSH\_EXTRA\_ARGS\] \[-k \| --connection-password-file CONNECTION\_PASSWORD\_FILE\] \[-C\] \[-D\] \[-e EXTRA\_VARS\] \[--vault-id VAULT\_IDS\] \[-J \| --vault-password-file VAULT\_PASSWORD\_FILES\] \[-f FORKS\] \[-M MODULE\_PATH\] \[--playbook-dir BASEDIR\] \[--task-timeout TASK\_TIMEOUT\] \[-a MODULE\_ARGS\] \[-m MODULE\_NAME\] pattern

## DESCRIPTION

is an extra-simple tool/framework/API for doing 'remote things'. this command allows you to define and run a single task 'playbook' against a set of hosts

## COMMON OPTIONS

host pattern

- **--become-method** 'BECOME\_METHOD'

  privilege escalation method to use (default=sudo), use *ansible-doc -t become -l* to list valid choices.

- **--become-password-file** 'BECOME\_PASSWORD\_FILE', **--become-pass-file** 'BECOME\_PASSWORD\_FILE'

  Become password file

- **--become-user** 'BECOME\_USER'

  run operations as this user (default=root)

- **--connection-password-file** 'CONNECTION\_PASSWORD\_FILE', **--conn-pass-file** 'CONNECTION\_PASSWORD\_FILE'

  Connection password file

- **--flush-cache**

  clear the fact cache for every host in inventory

- **--list-hosts**

  outputs a list of matching hosts; does not execute anything else

- **--playbook-dir** 'BASEDIR'

  Since this tool does not use playbooks, use this as a substitute playbook directory. This sets the relative path for many features including roles/ group\_vars/ etc.

- **--private-key** 'PRIVATE\_KEY\_FILE', **--key-file** 'PRIVATE\_KEY\_FILE'

  use this file to authenticate the connection

- **--scp-extra-args** 'SCP\_EXTRA\_ARGS'

  specify extra arguments to pass to scp only (e.g. -l)

- **--sftp-extra-args** 'SFTP\_EXTRA\_ARGS'

  specify extra arguments to pass to sftp only (e.g. -f, -l)

- **--ssh-common-args** 'SSH\_COMMON\_ARGS'

  specify common arguments to pass to sftp/scp/ssh (e.g. ProxyCommand)

- **--ssh-extra-args** 'SSH\_EXTRA\_ARGS'

  specify extra arguments to pass to ssh only (e.g. -R)

- **--task-timeout** 'TASK\_TIMEOUT'

  set task timeout limit in seconds, must be positive integer.

- **--vault-id**

  the vault identity to use. This argument may be specified multiple times.

- **--vault-password-file**, **--vault-pass-file**

  vault password file

- **--version**

  show program's version number, config file location, configured module search path, module location, executable location and exit

- **-B** 'SECONDS', **--background** 'SECONDS'

  run asynchronously, failing after X seconds (default=N/A)

- **-C**, **--check**

  don't make any changes; instead, try to predict some of the changes that may occur

- **-D**, **--diff**

  when changing (small) files and templates, show the differences in those files; works great with --check

- **-J**, **--ask-vault-password**, **--ask-vault-pass**

  ask for vault password

- **-K**, **--ask-become-pass**

  ask for privilege escalation password

- **-M**, **--module-path**

  prepend colon-separated path(s) to module library (default={{ ANSIBLE\_HOME ~ "/plugins/modules:/usr/share/ansible/plugins/modules" }}). This argument may be specified multiple times.

- **-P** 'POLL\_INTERVAL', **--poll** 'POLL\_INTERVAL'

  set the poll interval if using -B (default=15)

- **-T** 'TIMEOUT', **--timeout** 'TIMEOUT'

  override the connection timeout in seconds (default depends on connection)

- **-a** 'MODULE\_ARGS', **--args** 'MODULE\_ARGS'

  The action's options in space separated k=v format: -a 'opt1=val1 opt2=val2' or a json string: -a '{"opt1": "val1", "opt2": "val2"}'

- **-b**, **--become**

  run operations with become (does not imply password prompting)

- **-c** 'CONNECTION', **--connection** 'CONNECTION'

  connection type to use (default=ssh)

- **-e**, **--extra-vars**

  set additional variables as key=value or YAML/JSON, if filename prepend with @. This argument may be specified multiple times.

- **-f** 'FORKS', **--forks** 'FORKS'

  specify number of parallel processes to use (default=5)

- **-h**, **--help**

  show this help message and exit

- **-i**, **--inventory**, **--inventory-file**

  specify inventory host path or comma separated host list. This argument may be specified multiple times.

- **-k**, **--ask-pass**

  ask for connection password

- **-l** 'SUBSET', **--limit** 'SUBSET'

  further limit selected hosts to an additional pattern

- **-m** 'MODULE\_NAME', **--module-name** 'MODULE\_NAME'

  Name of the action to execute (default=command)

- **-o**, **--one-line**

  condense output

- **-t** 'TREE', **--tree** 'TREE'

  log output to this directory

- **-u** 'REMOTE\_USER', **--user** 'REMOTE\_USER'

  connect as this user (default=None)

- **-v**, **--verbose**

  Causes Ansible to print more debug messages. Adding multiple -v will increase the verbosity, the builtin plugins currently evaluate up to -vvvvvv. A reasonable level to start is -vvv, connection debugging might require -vvvv. This argument may be specified multiple times.

## INVENTORY

Ansible stores the hosts it can potentially operate on in an inventory. This can be an YAML file, ini-like file, a script, directory, list, etc. For additional options, see the documentation on \<https://docs.ansible.com/\>.

## ENVIRONMENT

The following environment variables may be specified.

ANSIBLE\_INVENTORY  -- Override the default ansible inventory sources

ANSIBLE\_LIBRARY -- Override the default ansible module library path

ANSIBLE\_CONFIG -- Specify override location for the ansible config file

Many more are available for most options in ansible.cfg

For a full list check \<https://docs.ansible.com/\>. or use the *ansible-config* command.

## FILES

/etc/ansible/hosts -- Default inventory file

/etc/ansible/ansible.cfg -- Config file, used if present

\~/.ansible.cfg -- User config file, overrides the default config if present

./ansible.cfg -- Local config file (in current working directory) assumed to be 'project specific' and overrides the rest if present.

As mentioned above, the ANSIBLE\_CONFIG environment variable will override all others.

## AUTHOR

Ansible was originally written by Michael DeHaan.

## COPYRIGHT

Copyright © 2018 Red Hat, Inc \| Ansible. Ansible is released under the terms of the GPLv3 license.

## SEE ALSO

**ansible-config** (1), **ansible-console** (1), **ansible-doc** (1), **ansible-galaxy** (1), **ansible-inventory** (1), **ansible-playbook** (1), **ansible-pull** (1), **ansible-vault** (1)

Extensive documentation is available in the documentation site: \<\<https://docs.ansible.com\>\>. IRC and mailing list info can be found in file CONTRIBUTING.md, available in: \<\<https://github.com/ansible/ansible\>\>