Ad-Hoc Commands

Analogy categoryAnalogies

An ad-hoc command is a single Ansible module invoked directly against a target group with the ansible CLI tool (not ansible-playbook), useful for quick, one-off operations like checking disk space, restarting a service, or copying a single file across a fleet without writing and saving a YAML file for a task you'll only run once. The basic form is ansible <pattern> -m <module> -a '<arguments>', where <pattern> selects hosts or groups from your inventory and the module does the actual work.

🏏

Cricket analogy: An ad-hoc command is like a captain calling a single, specific field change mid-over ('third man in') rather than drawing up a full written fielding plan for the entire innings.

Anatomy of an Ad-Hoc Command

The pattern argument accepts a group name, a specific hostname, a comma-separated list, or wildcards, and all is a special pattern matching every host in inventory. The -m flag names the module (defaulting to the command module if omitted), and -a passes module-specific arguments as a quoted string; -b (short for --become) escalates privileges when the task requires root, and -i lets you point at a specific inventory file if it isn't already configured as the default in ansible.cfg.

🏏

Cricket analogy: Selecting a pattern like 'webservers' is like a coach calling out 'all-rounders' as a subgroup to brief, rather than addressing the entire 15-man squad for something only relevant to a few.

bash

# Check connectivity
ansible all -m ping

# Check disk space on webservers
ansible webservers -m command -a "df -h"

# Restart nginx with elevated privileges
ansible webservers -m service -a "name=nginx state=restarted" -b

# Copy a file to db servers
ansible dbservers -m copy -a "src=./maintenance.html dest=/tmp/maintenance.html"

# Install a package (idempotent — only installs if missing)
ansible webservers -m apt -a "name=curl state=present" -b

Common Modules for Ad-Hoc Use

The command and shell modules run arbitrary commands (shell additionally supports pipes and redirection, but is not idempotent and should be a last resort), while purpose-built modules like service, apt/yum, copy, and user model a specific resource declaratively and check current state before acting, making them idempotent and safer for repeated use. The setup module is a special case worth knowing: run ad-hoc as ansible all -m setup, it gathers and displays every fact Ansible knows about a host — OS version, IP addresses, memory, disk layout — which is invaluable when writing conditionals that need to branch on host facts.

🏏

Cricket analogy: Using the idempotent 'service' module over raw 'shell' is like a coach using a proven, repeatable warm-up drill instead of improvising random exercises that might injure a player if repeated carelessly.

When to Use Ad-Hoc vs Playbooks

Ad-hoc commands are best for quick diagnostics, emergency fixes, and exploratory tasks you won't need to repeat or share with a team — checking whether a process is running, tailing a log, or rebooting a single stuck server. The moment a task needs to run in a specific order relative to other tasks, needs conditionals or loops, needs to be version-controlled and code-reviewed, or needs to be repeatable by teammates on a schedule, it belongs in a playbook instead, since playbooks are the durable, shareable, testable form of the same underlying module system.

🏏

Cricket analogy: This distinction is like a captain making a quick verbal field adjustment mid-over versus submitting the team's full pre-planned strategy document to selectors before the series begins.

A useful mental model: if you'd be comfortable running the exact same command again next week with the same result, and it's simple enough to type in one line, ad-hoc is fine. If you're copy-pasting the same ad-hoc command into a team chat more than once, it's time to promote it into a playbook.

Ad-hoc commands run a single module against a host pattern via the ansible CLI, not ansible-playbook.
The basic syntax is: ansible <pattern> -m <module> -a '<args>'.
-b escalates privileges (become); -i specifies a non-default inventory file.
command/shell run arbitrary commands but aren't idempotent; shell should be a last resort.
Purpose-built modules like service, apt, and copy are idempotent and check state before acting.
The setup module gathers and prints all facts Ansible knows about a host.
Repeatable, ordered, or team-shared tasks belong in a playbook, not an ad-hoc command.