Ansible Ad-Hoc Commands: Fast Remote Automation Without Playbooks

Most Ansible tutorials jump straight to playbooks. That's like teaching someone to drive by starting with a Formula 1 pit stop. You don't need a YAML file to restart a service or check disk space. Ad-hoc commands are the swiss army knife you reach for when production is on fire and you need answers now.

The problem they solve is simple: you have 10, 50, or 500 servers. SSHing into each one is slow and error-prone. Writing a playbook for a one-off task is overkill. Ad-hoc commands give you the power of Ansible's modules without the ceremony.

By the end of this guide, you'll be able to run any Ansible module on any group of hosts, debug connectivity issues, and avoid the three mistakes that have cost me sleep at 3 AM.

Why Ad-Hoc Commands Exist — The Problem with Playbooks

Playbooks are great for repeatable, complex automation. But they're YAML files you need to write, test, and commit. When you just need to check if a service is running or restart it, writing a playbook is like using a sledgehammer to crack a nut. Ad-hoc commands let you run any Ansible module directly from the CLI. They're the fastest way to get answers from your infrastructure.

The classic mistake: someone writes a playbook for a one-off task, forgets to clean it up, and six months later someone runs it thinking it's current. Ad-hoc commands leave no trace — they're ephemeral by design.

# io.thecodeforge — DevOps tutorial

# Test connectivity to all hosts in inventory
ansible all -m ping

# Output:
# server1 | SUCCESS => {
#     "changed": false,
#     "ping": "pong"
# }
# server2 | SUCCESS => {
#     "changed": false,
#     "ping": "pong"
# }

The Anatomy of an Ad-Hoc Command

Every ad-hoc command follows this pattern: ansible <host-pattern> -m <module> -a '<module-arguments>'. The host-pattern can be a group name from your inventory, all, or a wildcard. The module is the action you want to perform — command, shell, copy, service, etc. Arguments are passed as a quoted string.

Why shell over command? The command module is safer — it doesn't expand shell variables or interpret pipes. Use shell when you need pipes, redirects, or $HOME. But beware: shell is a security risk if you're passing user input. In production, I default to command and only use shell when I absolutely need it.

# io.thecodeforge — DevOps tutorial

# Check uptime on all web servers using shell module (needs pipes)
ansible webservers -m shell -a 'uptime | awk "{print \$3 \$4}"'

# Output:
# server1 | CHANGED | rc=0 >>
# 2 days,
# server2 | CHANGED | rc=0 >>
# 5 days,

Running Commands as Root (Become)

Many tasks require root — installing packages, restarting services, editing system files. In Ansible, you use --become (or -b) to escalate privileges. By default it uses sudo. You can specify the user with --become-user=root.

The rookie mistake: running ansible all -m service -a 'name=nginx state=restarted' without --become. It fails with a permission error. Always add -b when you need root. I've seen this bring down a production deployment because someone forgot the flag and the service never restarted.

# io.thecodeforge — DevOps tutorial

# Restart nginx on all web servers with sudo
ansible webservers -m service -a 'name=nginx state=restarted' --become

# Output:
# server1 | CHANGED => {
#     "changed": true,
#     "name": "nginx",
#     "state": "started"
# }
# server2 | CHANGED => {
#     "changed": true,
#     "name": "nginx",
#     "state": "started"
# }

Copying Files with the Copy Module

The copy module pushes files from the control node to managed hosts. It's perfect for deploying config files or scripts. Syntax: ansible <pattern> -m copy -a 'src=/local/path dest=/remote/path owner=root group=root mode=0644'.

Why not just use scp? Because copy is idempotent — it only transfers if the file has changed. It also sets permissions and ownership atomically. In a production environment, I use copy to deploy SSL certs, application configs, and systemd unit files.

# io.thecodeforge — DevOps tutorial

# Deploy nginx config to all web servers
ansible webservers -m copy -a 'src=./nginx.conf dest=/etc/nginx/nginx.conf owner=root group=root mode=0644 backup=yes' --become

# Output:
# server1 | CHANGED => {
#     "changed": true,
#     "dest": "/etc/nginx/nginx.conf",
#     "src": "/home/user/nginx.conf",
#     "backup_file": "/etc/nginx/nginx.conf.12345.2025-03-15@10:30:00~"
# }
# server2 | SUCCESS => {
#     "changed": false,
#     "dest": "/etc/nginx/nginx.conf"
# }

Gathering Facts with the Setup Module

The setup module collects system facts — OS, IP addresses, memory, disk, etc. It's the same data Ansible gathers before running a playbook. Run it ad-hoc to debug a host's configuration.

Why this matters: I once spent an hour debugging why a playbook failed on one host. Turns out the host had a different network interface name. A quick ansible problematic-host -m setup -a 'filter=ansible_default_ipv4' revealed the issue in seconds.

# io.thecodeforge — DevOps tutorial

# Get memory info from all database servers
ansible databases -m setup -a 'filter=ansible_memtotal_mb'

# Output:
# db1 | SUCCESS => {
#     "ansible_facts": {
#         "ansible_memtotal_mb": 16384
#     },
#     "changed": false
# }
# db2 | SUCCESS => {
#     "ansible_facts": {
#         "ansible_memtotal_mb": 32768
#     },
#     "changed": false
# }

Managing Packages with the Package Module

The package module works across package managers — yum, apt, dnf, pacman. It's the universal way to install, update, or remove packages. Use state=present to install, state=latest to upgrade, state=absent to remove.

Production trap: never run state=latest on all packages without testing. I've seen a curl update break a legacy app that depended on an old version. Pin versions or use state=present with a specific version.

# io.thecodeforge — DevOps tutorial

# Install htop on all servers
ansible all -m package -a 'name=htop state=present' --become

# Output:
# server1 | CHANGED => {
#     "changed": true,
#     "msg": "Installed htop-2.2.0-3.el7.x86_64"
# }
# server2 | SUCCESS => {
#     "changed": false,
#     "msg": "Package htop already installed"
# }

Debugging with Verbosity and Check Mode

When an ad-hoc command fails, you need to see what's happening. Add -v (verbose), -vvv (very verbose), or -vvvv (connection debug) to get more output. Check mode (-C) shows what would change without actually doing it.

Why this matters: I once ran a copy command that silently failed because the source path was wrong. Without -v, it just said SUCCESS with changed=false. Verbose mode showed the actual error: file not found.

# io.thecodeforge — DevOps tutorial

# Dry-run a service restart with verbose output
ansible webservers -m service -a 'name=nginx state=restarted' --become -C -v

# Output (truncated):
# Using module file /usr/lib/python3.9/site-packages/ansible/modules/service.py
# server1 | SUCCESS => {
#     "changed": false,
#     "msg": "Would have restarted nginx"
# }

Limiting Targets with Patterns and Limits

By default, ad-hoc commands run on all hosts in the pattern. Use --limit to target a subset. Patterns support wildcards, groups, and even regex. Examples: ansible '*.example.com' -m ping, ansible webservers:!dbservers -m ping (in dbservers group but not webservers).

Production trap: running ansible all -m shell -a 'reboot' without --limit will reboot every host in your inventory. Always double-check your pattern. I add --limit as a safety net even when I'm sure.

# io.thecodeforge — DevOps tutorial

# Check disk on just the first two web servers
ansible webservers -m shell -a 'df -h /' --limit 'webservers[0:2]'

# Output:
# web1 | CHANGED | rc=0 >>
# Filesystem      Size  Used Avail Use% Mounted on
# /dev/sda1        20G   15G  4.6G  77% /
# web2 | CHANGED | rc=0 >>
# Filesystem      Size  Used Avail Use% Mounted on
# /dev/sda1        20G   12G  7.8G  61% /

When Not to Use Ad-Hoc Commands

Ad-hoc commands are for one-off tasks. If you find yourself running the same command repeatedly, write a playbook. If you need conditional logic, loops, or error handling, use a playbook. If you're orchestrating a multi-step deployment, use a playbook.

The rule of thumb: if you type the same ad-hoc command more than twice in a week, it's time to write a playbook. I've seen teams with 50-line shell scripts that should have been a 10-line playbook. Don't be that team.

# io.thecodeforge — DevOps tutorial

# Bad: Running the same command every day
ansible all -m shell -a 'systemctl status nginx'  # Do this once, then automate

# Good: Write a playbook for recurring checks
# ---
# - name: Check nginx status
#   hosts: webservers
#   tasks:
#     - name: Get nginx status
#       command: systemctl status nginx
#       register: result
#     - debug: var=result.stdout_lines