win_command – Executes a command on a remote Windows node

From Get docs
Ansible/docs/2.7/modules/win command module


win_command – Executes a command on a remote Windows node

New in version 2.2.


Synopsis

  • The win_command module takes the command name followed by a list of space-delimited arguments.
  • The given command will be executed on all selected nodes. It will not be processed through the shell, so variables like $env:HOME and operations like "<", ">", "|", and ";" will not work (use the win_shell module if you need these features).
  • For non-Windows targets, use the command 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.

free_form

- / required

The win_command module takes a free form command to run.

There is no parameter actually named 'free form'. See the examples!

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

-

added in 2.5

Set the stdin of the command directly to the specified value.



Notes

Note

  • If you want to run a command through a shell (say you are using <, >, |, etc), you actually want the win_shell module instead. The win_command module is much more secure as it’s not affected by the user’s environment.
  • 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.
  • For non-Windows targets, use the command module instead.


Examples

- name: Save the result of 'whoami' in 'whoami_out'
  win_command: whoami
  register: whoami_out

- name: Run command that only runs if folder exists and runs from a specific folder
  win_command: wbadmin -backupTarget:C:\backup\
  args:
    chdir: C:\somedir\
    creates: C:\backup\

- name: Run an executable and send data to the stdin for the executable
  win_command: powershell.exe -
  args:
    stdin: Write-Host test

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

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.


© 2012–2018 Michael DeHaan
© 2018–2019 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/2.7/modules/win_command_module.html