Ad-Hoc Commands
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.
# 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" -bCommon 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.
Practice what you learned
1. What CLI tool is used to run an ad-hoc command (as opposed to a playbook)?
2. What is the correct general syntax for an ad-hoc command?
3. Why is the 'shell' module considered riskier for repeated use than a module like 'service'?
4. What does the 'setup' module do when run ad-hoc?
5. When should a task move from an ad-hoc command into a full playbook?
Was this page helpful?
You May Also Like
What Is Ansible?
Ansible is an open-source, agentless automation tool for configuration management, application deployment, and orchestration, driven by human-readable YAML playbooks.
Inventory Files Explained
An inventory file tells Ansible which hosts exist and how they're grouped, and can be static (INI or YAML) or generated dynamically from a cloud provider or CMDB.
Installing and Configuring Ansible
Ansible is installed via pip or a system package manager on the control node, then tuned through the layered ansible.cfg configuration file.
Agentless Architecture and SSH
Ansible manages remote systems without installing any persistent software on them, relying entirely on existing SSH connectivity and Python for execution.
Related Reading
Related Study Notes in DevOps
Browse all study notesNginx Study Notes
DevOps · 30 topics
DevOpsAdvanced Kubernetes Study Notes
Kubernetes · 30 topics
DevOpsAdvanced Bash Scripting Study Notes
Bash · 30 topics
DevOpsApache Kafka Study Notes
Kafka · 30 topics
DevOpsDocker & Kubernetes Study Notes
YAML · 40 topics
DevOpsCI/CD Tools & Pipelines Study Notes
YAML · 37 topics