Ansible ad-hoc commands cheat sheet

An ad-hoc command runs a single module against a group of hosts without writing a playbook. Use it for quick checks and one-off tasks; anything you will repeat belongs in a playbook. The general form is:

ansible <pattern> -i <inventory> -m <module> -a "<arguments>" [options]

<pattern> is a host, a group, or all. If you leave out -m, the command module is used. Arguments are key=value pairs or a JSON string.

Common options

• -i FILE: inventory to use.
• -m MODULE: module to run, for example ansible.builtin.copy.
• -a ARGS: module arguments.
• -u USER: remote SSH user (default: your local user name).
• -b / --become: escalate privileges (sudo by default). No password is implied.
• -K / --ask-become-pass: prompt for the sudo password. It does not turn on become by itself, so combine it with -b.
• --become-user USER: become this user instead of root (also needs -b).
• -f N: number of parallel forks (default 5).
• -C / --check: dry run, report what would change.
• -v to -vvvv: more verbose output; -vvvv includes SSH connection details.

Connectivity and facts

ansible all -i inventory.ini -m ping
ansible web -i inventory.ini -m ansible.builtin.setup
ansible web -i inventory.ini -m ansible.builtin.setup -a "filter=ansible_distribution*"
ansible-inventory -i inventory.ini --graph

Run commands

ansible web -i inventory.ini -a "uptime"
ansible web -i inventory.ini -a "df -h /"
ansible web -i inventory.ini -m ansible.builtin.shell -a "ps aux | grep [n]ginx"

The default command module does not use a shell, so pipes, redirects and variables like $HOME do not work. Use ansible.builtin.shell when you need them, and put the argument in single quotes if it contains $ so your local shell does not expand it.

Files

ansible web -i inventory.ini -b -m ansible.builtin.copy -a "src=./motd dest=/etc/motd mode=0644"
ansible web -i inventory.ini -b -m ansible.builtin.file -a "path=/srv/app state=directory mode=0755 owner=appuser"
ansible web -i inventory.ini -m ansible.builtin.fetch -a "src=/etc/os-release dest=./collected/"

fetch copies files from the hosts to the control node, into one subfolder per host.

Packages

ansible web -i inventory.ini -b -m ansible.builtin.apt -a "name=htop state=present update_cache=true"
ansible rhel -i inventory.ini -b -m ansible.builtin.dnf -a "name=htop state=present"
ansible all -i inventory.ini -b -m ansible.builtin.package -a "name=htop state=present"

ansible.builtin.package picks the right package manager for each host, which is handy for mixed fleets when the package name is the same everywhere.

Services and users

ansible web -i inventory.ini -b -m ansible.builtin.service -a "name=nginx state=restarted"
ansible web -i inventory.ini -b -m ansible.builtin.service -a "name=nginx enabled=true"
ansible all -i inventory.ini -b -m ansible.builtin.user -a "name=appuser state=present shell=/bin/bash"

Rebooting safely

Warning: a reboot hits every host in the pattern at once (up to the fork count). List the targets first with --list-hosts, and use -f 1 or a smaller group to go one by one.

ansible web -i inventory.ini --list-hosts
ansible web -i inventory.ini -b -f 1 -m ansible.builtin.reboot

The reboot module waits for the host to come back before it reports success, which a plain -a "/sbin/reboot" does not do.

Official documentation

• Introduction to ad hoc commands
• Understanding privilege escalation: become