AnsibleByExample

Understanding the ansible-console Command

Beginneransibleansible-consoleDevOpsautomation
2024-01-014By Luca Berton

Lesson 1 of 20 in Production Playbooks

Production Playbooks and Troubleshooting — full curriculum
  1. 1. Advanced Playbook Structure & Execution Strategies
  2. 2. Deep Dive: Variable Precedence & Best Practices
  3. 3. Jinja2 Templating Beyond Basics
  4. 4. Advanced Conditionals
  5. 5. Loops Masterclass
  6. 6. Blocks, Rescue, Always (Error Handling)
  7. 7. Handlers Advanced
  8. 8. Change Control: changed_when, failed_when
  9. 9. Tags and Selective Runs
  10. 10. Performance Tuning
  11. 11. Delegation Patterns
  12. 12. Local Actions and Remote Actions
  13. 13. Dynamic Inventory & Runtime Host Management
  14. 14. Includes & Imports (Structuring Large Codebases)
  15. 15. Role Design Patterns
  16. 16. Ansible Galaxy & Collections in Real Projects
  17. 17. Working with APIs (uri + JSON workflows)
  18. 18. Testing and Linting (Quality Gates)
  19. 19. Advanced Debugging Playbook Failures
  20. 20. Capstone: Multi-Stage Deployment
View path overview →

Introduction

The ansible-console command provides an interactive REPL (Read-Eval-Print Loop) for running Ansible modules against your inventory in real-time. It's ideal for ad-hoc tasks, debugging, and exploring hosts without writing full playbooks.

Starting ansible-console

# Connect to all hosts
ansible-console -i inventory

# Connect to a specific group
ansible-console -i inventory webservers

# Connect with become (sudo)
ansible-console -i inventory --become

# With specific user
ansible-console -i inventory -u deploy --become

You'll see a prompt showing your target and number of hosts:

Welcome to the ansible console. Type help or ? to list commands.

user@all (3)[f:5]$

The prompt shows: user@group (host_count)[f:forks]$

Basic Commands

Ping All Hosts

user@all (3)[f:5]$ ping
web1 | SUCCESS => {"changed": false, "ping": "pong"}
web2 | SUCCESS => {"changed": false, "ping": "pong"}
db1  | SUCCESS => {"changed": false, "ping": "pong"}

Run Shell Commands

user@all (3)[f:5]$ command hostname
web1 | CHANGED | rc=0 >> web1.example.com
web2 | CHANGED | rc=0 >> web2.example.com

user@all (3)[f:5]$ shell uptime
web1 | CHANGED | rc=0 >> 10:30:01 up 45 days, 3:22, 0 users

user@all (3)[f:5]$ raw df -h /
web1 | CHANGED | rc=0 >> Filesystem  Size  Used Avail Use% Mounted on
/dev/sda1    50G   12G   35G  26% /

Gather Facts

user@all (3)[f:5]$ setup filter=ansible_distribution*
web1 | SUCCESS => {
    "ansible_facts": {
        "ansible_distribution": "CentOS",
        "ansible_distribution_major_version": "9",
        "ansible_distribution_version": "9.3"
    }
}

Switching Targets

# Switch to a specific group
user@all (3)[f:5]$ cd webservers
user@webservers (2)[f:5]$

# Switch to a single host
user@webservers (2)[f:5]$ cd web1
user@web1 (1)[f:5]$

# Go back to all
user@web1 (1)[f:5]$ cd all
user@all (3)[f:5]$

Change Settings

# Change number of forks
user@all (3)[f:5]$ forks 10
user@all (3)[f:10]$

# Enable become (sudo)
user@all (3)[f:10]$ become true
user@all (3)[f:10]$

# Set become user
user@all (3)[f:10]$ become_user root

Package Management

# Install a package (RHEL)
user@all (3)[f:5]$ yum name=htop state=present

# Install on Debian
user@all (3)[f:5]$ apt name=htop state=present update_cache=true

# Check if package is installed
user@all (3)[f:5]$ package_facts manager=auto

File Operations

# Check if file exists
user@all (3)[f:5]$ stat path=/etc/nginx/nginx.conf

# Read file content
user@all (3)[f:5]$ slurp src=/etc/hostname

# Create a directory
user@all (3)[f:5]$ file path=/opt/myapp state=directory mode=0755

# Copy content to file
user@all (3)[f:5]$ copy content="maintenance mode" dest=/tmp/status.txt

Service Management

# Check service status
user@all (3)[f:5]$ systemd name=nginx

# Restart a service
user@all (3)[f:5]$ systemd name=nginx state=restarted

# Enable a service
user@all (3)[f:5]$ systemd name=nginx enabled=true

User Management

# Check user info
user@all (3)[f:5]$ command id deploy

# Create a user
user@all (3)[f:5]$ user name=deploy shell=/bin/bash state=present

Practical Use Cases

Quick Health Check

user@all (50)[f:20]$ ping
user@all (50)[f:20]$ command uptime
user@all (50)[f:20]$ shell free -h | grep Mem
user@all (50)[f:20]$ shell df -h / | tail -1

Debug Connectivity Issues

user@all (3)[f:5]$ cd problematic_host
user@problematic_host (1)[f:5]$ ping
user@problematic_host (1)[f:5]$ raw whoami
user@problematic_host (1)[f:5]$ setup filter=ansible_connection

Emergency Maintenance

# Quick fix across all web servers
user@webservers (10)[f:10]$ systemd name=nginx state=stopped
user@webservers (10)[f:10]$ copy src=/tmp/emergency-fix.conf dest=/etc/nginx/nginx.conf backup=true
user@webservers (10)[f:10]$ systemd name=nginx state=started

Help and Tab Completion

# List available commands
user@all (3)[f:5]$ help

# Tab completion for modules
user@all (3)[f:5]$ ansible.builtin.<TAB>
ansible.builtin.apt         ansible.builtin.file
ansible.builtin.command     ansible.builtin.ping
...

# List module documentation
user@all (3)[f:5]$ help copy

Exiting

user@all (3)[f:5]$ exit
# or Ctrl+D

ansible-console vs ansible (ad-hoc)

Featureansible-consoleansible (ad-hoc)
Interactive✅ REPL❌ One-shot
Switch targets✅ cd groupSpecify each time
Tab completion✅❌
Session state✅ Persistent❌
Scripting❌✅ Pipeline-friendly
Best forExploration, debuggingScripted one-liners

Best Practices

  1. Test in non-production first — commands execute immediately on all targeted hosts
  2. Use cd to narrow scope before running commands on specific groups
  3. Enable become only when needed — avoid running everything as root
  4. Use --check mode when available to preview changes
  5. Prefer ansible-console for debugging, playbooks for repeatable automation

Conclusion

ansible-console is Ansible's interactive mode — start with ansible-console -i inventory, use cd group to switch targets, type module names with parameters directly (ping, yum name=htop state=present), and exit when done. Use it for ad-hoc debugging, quick health checks, and emergency maintenance. For repeatable automation, write playbooks instead.

All Tutorials