adhoc: clarify how the command module handles variables - #4078

SUMMARY

The note in "Introduction to ad hoc commands" says:

The command module does not support extended shell syntaxes like piping and redirects (although shell variables will always work).

The part in parentheses is not accurate. The command module does not run a shell. AnsibleModule.run_command expands the arguments itself with os.path.expandvars and os.path.expanduser (module_utils/basic.py), and since ansible-core 2.16 this is controlled by the module option expand_argument_vars (default true). The module documentation already describes this: "environment variables are resolved via Python, not shell, see expand_argument_vars and are left unchanged if not matched."

So environment variables such as $HOME work, but:

• a variable that is not set stays in the argument as $NAME (a shell would replace it with an empty string);
• shell parameters and expansions such as $$, $RANDOM or ${VAR:-default} are passed to the command literally.

This PR rewords the note to say this and points to expand_argument_vars.

ISSUE TYPE

• Docs Pull Request

COMPONENT NAME

docs/docsite/rst/command_guide/intro_adhoc.rst

ADDITIONAL INFORMATION

Checked with ansible-core 2.16.3 (Ubuntu 24.04 package) and ansible-core 2.21.5 (run from the v2.21.5 tag), Python 3.12, against localhost. Both versions give the same output:

$ ansible localhost -c local -m command -a 'echo HOME=$HOME BRACED=${HOME} RANDOM=$RANDOM DEFAULT=${UNSET_VAR:-fallback} PID=$$ UNSET=$UNSET_VAR'
HOME=/root BRACED=/root RANDOM=$RANDOM DEFAULT=${UNSET_VAR:-fallback} PID=$$ UNSET=$UNSET_VAR

$ ansible localhost -c local -m shell -a '<same command>'
HOME=/root BRACED=/root RANDOM= DEFAULT=fallback PID=104 UNSET=

And in a playbook with ansible-core 2.21.5:

- ansible.builtin.command:
    argv: [echo, "HOME=$HOME", "UNSET=$UNSET_VAR"]
# -> HOME=/root UNSET=$UNSET_VAR
- ansible.builtin.command:
    argv: [echo, "HOME=$HOME"]
    expand_argument_vars: false
# -> HOME=$HOME

This change was drafted with AI assistance and reviewed by me.

🤖 Generated with Claude Code