ansible.builtin.shell (v2.16.5) — module

Install Ansible via pip

Install with pip install ansible-core==2.16.5

Description

The M(ansible.builtin.shell) module takes the command name followed by a list of space-delimited arguments.

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

It is almost exactly like the M(ansible.builtin.command) module but runs the command through a shell (C(/bin/sh)) on the remote node.

For Windows targets, use the M(ansible.windows.win_shell) module instead.

Usage examples

Scanned by Steampunk Spotter

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

- name: Execute the command in remote shell; stdout goes to the specified file on the remote
  ansible.builtin.shell: somescript.sh >> somelog.txt

Scanned by Steampunk Spotter

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

- name: Change the working directory to somedir/ before executing the command
  ansible.builtin.shell: somescript.sh >> somelog.txt
  args:
    chdir: somedir/

Scanned by Steampunk Spotter

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

# You can also use the 'args' form to provide the options.
- name: This command will change the working directory to somedir/ and will only run when somedir/somelog.txt doesn't exist
  ansible.builtin.shell: somescript.sh >> somelog.txt
  args:
    chdir: somedir/
    creates: somelog.txt

Scanned by Steampunk Spotter

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

# You can also use the 'cmd' parameter instead of free form format.
- name: This command will change the working directory to somedir/
  ansible.builtin.shell:
    cmd: ls -l | grep log
    chdir: somedir/

Scanned by Steampunk Spotter

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

- name: Run a command that uses non-posix shell-isms (in this example /bin/sh doesn't handle redirection and wildcards together but bash does)
  ansible.builtin.shell: cat < /tmp/*txt
  args:
    executable: /bin/bash

Scanned by Steampunk Spotter

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

- name: Run a command using a templated variable (always use quote filter to avoid injection)
  ansible.builtin.shell: cat {{ myfile|quote }}

Scanned by Steampunk Spotter

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

# You can use shell to run other executables to perform actions inline
- name: Run expect to wait for a successful PXE boot via out-of-band CIMC
  ansible.builtin.shell: |
    set timeout 300
    spawn ssh admin@{{ cimc_host }}

    expect "password:"
    send "{{ cimc_password }}\n"

    expect "\n{{ cimc_name }}"
    send "connect host\n"

    expect "pxeboot.n12"
    send "\n"

    exit 0
  args:
    executable: /usr/bin/expect
  delegate_to: localhost

Inputs

    
cmd:
    description:
    - The command to run followed by optional arguments.
    type: str

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.
    type: str
    version_added: '2.4'
    version_added_collection: ansible.builtin

creates:
    description:
    - A filename, when it already exists, this step will B(not) be run.
    type: path

removes:
    description:
    - A filename, when it does not exist, this step will B(not) be run.
    type: path
    version_added: '0.8'
    version_added_collection: ansible.builtin

free_form:
    description:
    - The shell module takes a free form command to run, as a string.
    - There is no actual parameter named 'free form'.
    - See the examples on how to use this module.
    type: str

executable:
    description:
    - Change the shell used to execute the command.
    - This expects an absolute path to the executable.
    type: path
    version_added: '0.9'
    version_added_collection: ansible.builtin

stdin_add_newline:
    default: true
    description:
    - Whether to append a newline to stdin data.
    type: bool
    version_added: '2.8'
    version_added_collection: ansible.builtin

Outputs

cmd:
  description: The command executed by the task.
  returned: always
  sample: rabbitmqctl join_cluster rabbit@master
  type: str
delta:
  description: The command execution delta time.
  returned: always
  sample: '0:00:00.325771'
  type: str
end:
  description: The command execution end time.
  returned: always
  sample: '2016-02-25 09:18:26.755339'
  type: str
msg:
  description: changed
  returned: always
  sample: true
  type: bool
rc:
  description: The command return code (0 means success).
  returned: always
  sample: 0
  type: int
start:
  description: The command execution start time.
  returned: always
  sample: '2016-02-25 09:18:26.429568'
  type: str
stderr:
  description: The command standard error.
  returned: always
  sample: 'ls: cannot access foo: No such file or directory'
  type: str
stderr_lines:
  description: The command standard error split in lines.
  returned: always
  sample:
  - u'ls cannot access foo: No such file or directory'
  - "u'ls \u2026'"
  type: list
stdout:
  description: The command standard output.
  returned: always
  sample: "Clustering node rabbit@slave1 with rabbit@master \u2026"
  type: str
stdout_lines:
  description: The command standard output split in lines.
  returned: always
  sample:
  - "u'Clustering node rabbit@slave1 with rabbit@master \u2026'"
  type: list

See also

• ansible.builtin.command
• ansible.builtin.raw
• ansible.builtin.script
• ansible.windows.win_shell