# win_shell – Execute shell commands on target hosts

- Synopsis
- Parameters
- Notes
- See Also
- Examples
- Return Values
- Status

## Synopsis

- The `win_shell` module takes the command name followed by a list of space-delimited arguments. It is similar to the win_command module, but runs the command via a shell (defaults to PowerShell) on the target host.
- For non-Windows targets, use the shell module instead.

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---
chdir path |  | Set the specified path as the current working directory before executing a command
creates path |  | A path or path filter pattern; when the referenced path exists on the target host, the task will be skipped.
executable path |  | Change the shell used to execute the command (eg, `cmd`). The target shell must accept a `/c` parameter followed by the raw command line to be executed.
free_form string / required |  | The `win_shell` module takes a free form command to run. There is no parameter actually named 'free form'. See the examples!

no_profile
boolean
added in 2.8

Choices:
- no ←
- yes

Do not load the user profile before running a command. This is only valid when using PowerShell as the executable.

removes path |  | A path or path filter pattern; when the referenced path does not exist on the target host, the task will be skipped.
stdin string added in 2.5 |  | Set the stdin of the command directly to the specified value.

## Notes

Note

- If you want to run an executable securely and predictably, it may be better to use the win_command module instead. Best practices when writing playbooks will follow the trend of using win_command unless `win_shell` is explicitly required. When running ad-hoc commands, use your best judgement.
- WinRM will not return from a command execution until all child processes created have exited. Thus, it is not possible to use `win_shell` to spawn long-running child or background processes. Consider creating a Windows service for managing background processes.

## See Also

See also

psexec – Runs commands on a remote Windows host based on the PsExec model
  The official documentation on the psexec module.
raw – Executes a low-down and dirty command
  The official documentation on the raw module.
script – Runs a local script on a remote node after transferring it
  The official documentation on the script module.
shell – Execute shell commands on targets
  The official documentation on the shell module.
win_command – Executes a command on a remote Windows node
  The official documentation on the win_command module.
win_psexec – Runs commands (remotely) as another (privileged) user
  The official documentation on the win_psexec module.

## Examples

    # Execute a command in the remote shell; stdout goes to the specified
    # file on the remote.
    - win_shell: C:\somescript.ps1 >> C:\somelog.txt

    # Change the working directory to somedir/ before executing the command.
    - win_shell: C:\somescript.ps1 >> C:\somelog.txt chdir=C:\somedir

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

    # Run a command under a non-Powershell interpreter (cmd in this case)
    - win_shell: echo %HOMEDIR%
      args:
        executable: cmd
      register: homedir_out

    - name: Run multi-lined shell commands
      win_shell: |
        $value = Test-Path -Path C:\temp
        if ($value) {
            Remove-Item -Path C:\temp -Force
        }
        New-Item -Path C:\temp -ItemType Directory

    - name: Retrieve the input based on stdin
      win_shell: '$string = [Console]::In.ReadToEnd(); Write-Output $string.Trim()'
      args:
        stdin: Input message

## Return Values

Common return values are documented here, the following are the fields unique to this module:

Key | Returned | Description
--- | --- | ---
cmd string | always | The command executed by the task. Sample: rabbitmqctl join_cluster rabbit@master
delta string | always | The command execution delta time. Sample: 0:00:00.325771
end string | always | The command execution end time. Sample: 2016-02-25 09:18:26.755339
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: 2016-02-25 09:18:26.429568
stderr string | always | The command standard error. Sample: ls: cannot access foo: No such file or directory
stdout string | always | The command standard output. Sample: Clustering node rabbit@slave1 with rabbit@master ...
stdout_lines list | always | The command standard output split in lines. Sample: ["u'Clustering node rabbit@slave1 with rabbit@master ...'"]

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]
- This module is maintained by the Ansible Core Team. [core]

### Red Hat Support

More information about Red Hat’s support of this module is available from this Red Hat Knowledge Base article.

### Authors

- Matt Davis (@nitzmahone)

Hint

If you notice any issues in this documentation, you can edit this document to improve it.