ansible.builtin.command (v2.9.23) — module

Install Ansible via pip

Install with pip install ansible==2.9.23

Description

The C(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 C($HOME) and operations like C("<"), C(">"), C("|"), C(";") and C("&") will not work. Use the M(shell) module if you need these features.

To create C(command) tasks that are easier to read than the ones using space-delimited arguments, pass parameters using the C(args) L(task keyword,../reference_appendices/playbooks_keywords.html#task) or use C(cmd) parameter.

Either a free form command or C(cmd) parameter is required, see the examples.

For Windows targets, use the M(win_command) module instead.

Usage examples

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: return motd to registered var
  command: cat /etc/motd
  register: mymotd

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Run command if /path/to/database does not exist (without 'args' keyword).
  command: /usr/bin/make_database.sh db_user db_name creates=/path/to/database

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# '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).
  command: /usr/bin/make_database.sh db_user db_name
  args:
    creates: /path/to/database

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# 'cmd' is module parameter
- name: Run command if /path/to/database does not exist (with 'cmd' parameter).
  command:
    cmd: /usr/bin/make_database.sh db_user db_name
    creates: /path/to/database

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: Change the working directory to somedir/ and run the command as db_owner if /path/to/database does not exist.
  command: /usr/bin/make_database.sh db_user db_name
  become: yes
  become_user: db_owner
  args:
    chdir: somedir/
    creates: /path/to/database

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

# 'argv' is a parameter, indented one level from the module
- name: Use 'argv' to send a command as a list - leave 'command' empty
  command:
    argv:
      - /usr/bin/make_database.sh
      - Username with whitespace
      - dbname with whitespace

Scanned by Steampunk Spotter

• Success
  Steampunk Spotter scan finished with no errors, warnings or hints.

- name: safely use templated variable to run command. Always use the quote filter to avoid injection issues.
  command: cat {{ myfile|quote }}
  register: myoutput

Inputs

    
cmd:
    description:
    - The command to run.
    type: str

argv:
    description:
    - Passes the command as a list rather than a string.
    - Use C(argv) to avoid quoting values that would otherwise be interpreted incorrectly
      (for example "user name").
    - Only the string or the list form can be provided, not both.  One or the other must
      be provided.
    type: list
    version_added: '2.6'
    version_added_collection: ansible.builtin

warn:
    default: true
    description:
    - Enable or disable task warnings.
    type: bool
    version_added: '1.8'
    version_added_collection: ansible.builtin

chdir:
    description:
    - Change into this directory before running the command.
    type: path
    version_added: '0.6'
    version_added_collection: ansible.builtin

stdin:
    description:
    - Set the stdin of the command directly to the specified value.
    version_added: '2.4'
    version_added_collection: ansible.builtin

creates:
    description:
    - A filename or (since 2.0) glob pattern. If it already exists, this step B(won't)
      be run.
    type: path

removes:
    description:
    - A filename or (since 2.0) glob pattern. If it already exists, this step B(will)
      be run.
    type: path
    version_added: '0.8'
    version_added_collection: ansible.builtin

free_form:
    description:
    - The command module takes a free form command to run.
    - There is no actual parameter named 'free form'.

strip_empty_ends:
    default: true
    description:
    - Strip empty lines from the end of stdout/stderr in result.
    type: bool
    version_added: '2.8'
    version_added_collection: ansible.builtin

stdin_add_newline:
    default: true
    description:
    - If set to C(yes), append a newline to stdin data.
    type: bool
    version_added: '2.8'
    version_added_collection: ansible.builtin

Outputs

cmd:
  description: the cmd that was run on the remote machine
  returned: always
  sample:
  - echo
  - hello
  type: list
delta:
  description: cmd end time - cmd start time
  returned: always
  sample: 0.001529
  type: str
end:
  description: cmd end time
  returned: always
  sample: '2017-09-29 22:03:48.084657'
  type: str
start:
  description: cmd start time
  returned: always
  sample: '2017-09-29 22:03:48.083128'
  type: str

See also

• raw
• script
• shell
• win_command