command, script & shell: mention 'cmd' parameter (#62778)

'cmd' parameter is supported since 2b3c5aa41e (v2.0.0-1)

lib/ansible/modules/commands/command.py

@@ -25,16 +25,20 @@ description:
        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,
-       pass parameters using the C(args) L(task keyword,../reference_appendices/playbooks_keywords.html#task).
+     - 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.
 options:
   free_form:
     description:
       - The command module takes a free form command to run.
       - There is no actual parameter named 'free form'.
-      - See the examples on how to use this module.
-    required: yes
+  cmd:
+    type: str
+    description:
+      - The command to run.
   argv:
     type: list
     description:
@@ -105,15 +109,21 @@ EXAMPLES = r'''
   command: cat /etc/motd
   register: mymotd
 
-- name: Run command if /path/to/database does not exist (without 'args').
+- 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
 
 # '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').
+- 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
 
+# '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
+
 - 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

lib/ansible/modules/commands/script.py

@@ -15,6 +15,7 @@ version_added: "0.9"
 short_description: Runs a local script on a remote node after transferring it
 description:
      - The C(script) module takes the script name followed by a list of space-delimited arguments.
+     - Either a free form command or C(cmd) parameter is required, see the examples.
      - The local script at path will be transferred to the remote node and then executed.
      - The given script will be processed through the shell environment on the remote node.
      - This module does not require python on the remote system, much like the M(raw) module.
@@ -23,8 +24,10 @@ options:
   free_form:
     description:
       - Path to the local script file followed by optional arguments.
-      - There is no parameter actually named 'free form', see the examples!
-    required: true
+  cmd:
+    type: str
+    description:
+      - Path to the local script to run followed by optional arguments.
   creates:
     description:
       - A filename on the remote node, when it already exists, this step will B(not) be run.
@@ -58,9 +61,13 @@ extends_documentation_fragment:
 '''
 
 EXAMPLES = r'''
-- name: Run a script with arguments
+- name: Run a script with arguments (free form)
   script: /some/local/script.sh --some-argument 1234
 
+- name: Run a script with arguments (using 'cmd' parameter)
+  script:
+    cmd: /some/local/script.sh --some-argument 1234
+
 - name: Run a script only if file.txt does not exist on the remote node
   script: /some/local/create_file.sh --some-argument 1234
   args:

lib/ansible/modules/commands/shell.py

@@ -23,6 +23,7 @@ module: shell
 short_description: Execute shell commands on targets
 description:
      - The C(shell) module takes the command name followed by a list of space-delimited arguments.
+     - Either a free form command or C(cmd) parameter is required, see the examples.
      - It is almost exactly like the M(command) module but runs
        the command through a shell (C(/bin/sh)) on the remote node.
      - For Windows targets, use the M(win_shell) module instead.
@@ -33,8 +34,11 @@ options:
       - 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.
-    required: yes
     type: str
+  cmd:
+    type: str
+    description:
+      - The command to run followed by optional arguments.
   creates:
     description:
       - A filename, when it already exists, this step will B(not) be run.
@@ -114,6 +118,12 @@ EXAMPLES = r'''
     chdir: somedir/
     creates: somelog.txt
 
+# You can also use the 'cmd' parameter instead of free form format.
+- name: This command will change the working directory to somedir/.
+  shell:
+    cmd: ls -l | grep log
+    chdir: somedir/
+
 - 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)
   shell: cat < /tmp/*txt
   args: