ansible.builtin.command – Execute commands on targets

Note

This module is part of ansible-base and included in all Ansible installations. In most cases, you can use the short module name command even without specifying the collections: keyword. Despite that, 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 the args task keyword or use cmd 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	Choices/Defaults	Comments
argv list / elements=string added in 2.6 of ansible.builtin		Passes the command as a list rather than a string. Use argv to avoid quoting values that would otherwise be interpreted incorrectly (for example "user name"). Only the string (free form) or the list (argv) form can be provided, not both. One or the other must be provided.
chdir path added in 0.6 of ansible.builtin		Change into this directory before running the command.
cmd string		The command to run.
creates path		A filename or (since 2.0) glob pattern. If a matching file already exists, this step will not be run.
free_form string		The command module takes a free form string as a command to run. There is no actual parameter named 'free form'.
removes path added in 0.8 of ansible.builtin		A filename or (since 2.0) glob pattern. If a matching file exists, this step will be run.
stdin string added in 2.4 of ansible.builtin		Set the stdin of the command directly to the specified value.
stdin_add_newline boolean added in 2.8 of ansible.builtin	Choices: no yes ←	If set to yes, append a newline to stdin data.
strip_empty_ends boolean added in 2.8 of ansible.builtin	Choices: no yes ←	Strip empty lines from the end of stdout/stderr in result.
warn boolean added in 1.8 of ansible.builtin	Choices: no yes ←	Enable or disable task warnings.

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 the command module when possible.

• creates, removes, and chdir 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 or removes. 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

The official documentation on the ansible.builtin.raw module.

ansible.builtin.script

The official documentation on the ansible.builtin.script module.

ansible.builtin.shell

The official documentation on the ansible.builtin.shell module.

ansible.windows.win_command

The official documentation on the ansible.windows.win_command module.

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	Returned	Description
cmd list / elements=string	always	The command executed by the task. Sample: ['echo', 'hello']
delta string	always	The command execution delta time. Sample: 0:00:00.001529
end string	always	The command execution end time. Sample: 2017-09-29 22:03:48.084657
msg boolean	always	changed Sample: True
rc integer	always	The command return code (0 means success).
start string	always	The command execution start time. Sample: 2017-09-29 22:03:48.083128
stderr string	always	The command standard error. Sample: ls cannot access foo: No such file or directory
stderr_lines list / elements=string	always	The command standard error split in lines. Sample: [{"u'ls cannot access foo": "No such file or directory'"}, "u'ls …'"]
stdout string	always	The command standard output. Sample: Clustering node rabbit@slave1 with rabbit@master …
stdout_lines list / elements=string	always	The command standard output split in lines. Sample: ["u'Clustering node rabbit@slave1 with rabbit@master …'"]

Authors

• Ansible Core Team

• Michael DeHaan