Modules and Plugins

## Two modules, one difference Both modules run a command on the managed host and return its exit status, `stdout` and `stderr`. The single difference is whether a shell sits between Ansible and the program. `ansible.builtin.command` splits the command line into an argument vector and executes the program directly. Nothing interprets metacharacters. `ansible.builtin.shell` hands the whole string to a shell on the target — `/bin/sh` unless you set the `executable` argument — and lets the shell do its usual job: word splitting, glob expansion, variable expansion, pipelines, redirection, command chaining with `&&` and `;`. ```yaml # Fails: the > and the pipe are passed to `cat` as literal arguments - ansible.builtin.command: cat /etc/hosts | grep db > /tmp/db_hosts # Works: the shell parses the pipeline and the redirect - ansible.builtin.shell: cat /etc/hosts | grep db > /tmp/db_hosts ``` The classic interview symptom is a task that "does nothing but reports success": someone wrote a redirect under `command`, the program accepted the extra arguments or ignored them, and the output file never appeared. ## Why command is the default **Injection surface.** Task command lines are usually templated from variables. Under `shell`, a variable containing `; rm -rf /var/lib/app` or even an unexpected space becomes shell syntax. Under `command`, it is one literal argument. When the value comes from inventory, from a `register`ed result, or from a survey field, that difference is the difference between an argument and an incident. For full control you can use `command` with `argv` — an explicit list of arguments, with no string parsing at all. **Explicitness.** Choosing `shell` documents "this task depends on shell features". A codebase where everything is `shell` tells the reader nothing. **Portability.** `/bin/sh` is not the same shell everywhere. Bash-isms written under `shell` on a Debian control host can behave differently on a target where `/bin/sh` is dash. If you need bash specifically, say so with `executable: /bin/bash` rather than assuming. ## What they share Both accept `chdir` (run from a directory), `creates` (skip if a path exists) and `removes` (skip if a path does not exist), and both are non-idempotent by nature — Ansible cannot inspect what your command did, so a successful run reports changed. Both also skip by default under `--check`. Both also require Python on the managed host, because they are ordinary modules shipped to the target and executed there. When the host has no Python — a bare container, a network appliance, a machine you are about to bootstrap — `ansible.builtin.raw` is the escape hatch: it pushes the command straight down the SSH connection with no module payload at all. Use it to install Python, then stop using it. ## When you should be using neither The most common right answer to "command or shell?" in a review is "neither". Reaching for a shell is usually a sign that a purpose-built module exists and was not looked for: `ansible.builtin.uri` for HTTP calls, `ansible.builtin.git` for clones and checkouts, `ansible.builtin.unarchive` for tarballs, `ansible.builtin.file` for permissions and symlinks, `ansible.builtin.service` for daemons, `ansible.builtin.package` for installs. Those modules compare state and report changed honestly; a shell-out cannot. When you genuinely must shell out — a vendor installer, a one-off migration, a CLI with no module — the reviewable form is: `command` rather than `shell` unless a shell feature is required, a `creates` guard so it runs once, and a clear task `name` explaining what the command is for. ## A small trap worth naming Running a long pipeline under `shell` reports the exit status of the *last* command in the pipeline, which is standard shell behaviour and means a failing first stage can pass silently. If that matters, set `executable: /bin/bash` and include `set -o pipefail` at the front of the command, or split the work into separate tasks. This is the sort of detail that separates "I have used shell" from "I have debugged shell in a playbook".