ansible.builtin.command module – Execute commands on targets
Note
This module is part of ansible-core
and included in all Ansible
installations. In most cases, you can use the short
module name
command
even without specifying the collections:
keyword.
However, we recommend you use the FQCN for easy linking to the
module documentation and to avoid conflicting with other collections that may have
the same module name.
Synopsis
The
command
module takes the command name followed by a list of space-delimited arguments.The given command will be executed on all selected nodes.
The command(s) will not be processed through the shell, so variables like
$HOSTNAME
and operations like"*"
,"<"
,">"
,"|"
,";"
and"&"
will not work. Use the ansible.builtin.shell module if you need these features.To create
command
tasks that are easier to read than the ones using space-delimited arguments, pass parameters using theargs
task keyword or usecmd
parameter.Either a free form command or
cmd
parameter is required, see the examples.For Windows targets, use the ansible.windows.win_command module instead.
Note
This module has a corresponding action plugin.
Parameters
Parameter |
Comments |
---|---|
Passes the command as a list rather than a string. Use Only the string (free form) or the list (argv) form can be provided, not both. One or the other must be provided. |
|
Change into this directory before running the command. |
|
The command to run. |
|
A filename or (since 2.0) glob pattern. If a matching file already exists, this step will not be run. This is checked before removes is checked. |
|
The command module takes a free form string as a command to run. There is no actual parameter named ‘free form’. |
|
A filename or (since 2.0) glob pattern. If a matching file exists, this step will be run. This is checked after creates is checked. |
|
Set the stdin of the command directly to the specified value. |
|
If set to Choices:
|
|
Strip empty lines from the end of stdout/stderr in result. Choices:
|
|
(deprecated) Enable or disable task warnings. This feature is deprecated and will be removed in 2.14. As of version 2.11, this option is now disabled by default. Choices:
|
Attributes
Attribute |
Support |
Description |
---|---|---|
Support: partial while the command itself is arbitrary and cannot be subject to the check mode semantics it adds |
Can run in check_mode and return changed status prediction without modifying target |
|
Support: none |
Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode |
|
Platform: posix |
Target OS/families that can be operated against |
|
Support: full |
Indicates if an action takes a ‘raw’ or ‘free form’ string as an option and has it’s own special parsing of it |
Notes
Note
If you want to run a command through the shell (say you are using
<
,>
,|
, and so on), you actually want the ansible.builtin.shell module instead. Parsing shell metacharacters can lead to unexpected commands being executed if quoting is not done correctly so it is more secure to use thecommand
module when possible.creates
,removes
, andchdir
can be specified after the command. For instance, if you only want to run a command if a certain file does not exist, use this.Check mode is supported when passing
creates
orremoves
. If running in check mode and either of these are specified, the module will check for the existence of the file and report the correct changed status. If these are not supplied, the task will be skipped.The
executable
parameter is removed since version 2.4. If you have a need for this parameter, use the ansible.builtin.shell module instead.For Windows targets, use the ansible.windows.win_command module instead.
For rebooting systems, use the ansible.builtin.reboot or ansible.windows.win_reboot module.
See Also
See also
- ansible.builtin.raw
Executes a low-down and dirty command.
- ansible.builtin.script
Runs a local script on a remote node after transferring it.
- ansible.builtin.shell
Execute shell commands on targets.
- ansible.windows.win_command
Executes a command on a remote Windows node.
Examples
- name: Return motd to registered var
ansible.builtin.command: cat /etc/motd
register: mymotd
# free-form (string) arguments, all arguments on one line
- name: Run command if /path/to/database does not exist (without 'args')
ansible.builtin.command: /usr/bin/make_database.sh db_user db_name creates=/path/to/database
# free-form (string) arguments, some arguments on separate lines with the 'args' keyword
# 'args' is a task keyword, passed at the same level as the module
- name: Run command if /path/to/database does not exist (with 'args' keyword)
ansible.builtin.command: /usr/bin/make_database.sh db_user db_name
args:
creates: /path/to/database
# 'cmd' is module parameter
- name: Run command if /path/to/database does not exist (with 'cmd' parameter)
ansible.builtin.command:
cmd: /usr/bin/make_database.sh db_user db_name
creates: /path/to/database
- name: Change the working directory to somedir/ and run the command as db_owner if /path/to/database does not exist
ansible.builtin.command: /usr/bin/make_database.sh db_user db_name
become: yes
become_user: db_owner
args:
chdir: somedir/
creates: /path/to/database
# argv (list) arguments, each argument on a separate line, 'args' keyword not necessary
# 'argv' is a parameter, indented one level from the module
- name: Use 'argv' to send a command as a list - leave 'command' empty
ansible.builtin.command:
argv:
- /usr/bin/make_database.sh
- Username with whitespace
- dbname with whitespace
creates: /path/to/database
- name: Safely use templated variable to run command. Always use the quote filter to avoid injection issues
ansible.builtin.command: cat {{ myfile|quote }}
register: myoutput
Return Values
Common return values are documented here, the following are the fields unique to this module:
Key |
Description |
---|---|
The command executed by the task. Returned: always Sample: |
|
The command execution delta time. Returned: always Sample: |
|
The command execution end time. Returned: always Sample: |
|
changed Returned: always Sample: |
|
The command return code (0 means success). Returned: always Sample: |
|
The command execution start time. Returned: always Sample: |
|
The command standard error. Returned: always Sample: |
|
The command standard error split in lines. Returned: always Sample: |
|
The command standard output. Returned: always Sample: |
|
The command standard output split in lines. Returned: always Sample: |