Ansible Command Line Tools

Core Ansible Commands

Ansible provides a comprehensive suite of command-line tools for automation, configuration management, and infrastructure orchestration. Understanding these tools is essential for effective Ansible usage.

ansible - Ad-Hoc Commands

Execute single tasks quickly without writing playbooks.

Basic Syntax

ansible [pattern] -m [module] -a "[arguments]" [options]

Common Examples

# Ping all hosts
ansible all -m ping

# Ping specific group
ansible webservers -m ping

# Run shell command
ansible all -m shell -a "uptime"

# Get system facts
ansible all -m setup

# Filter facts
ansible all -m setup -a "filter=ansible_distribution*"

# Copy file
ansible all -m copy -a "src=/tmp/file dest=/tmp/file"

# Install package
ansible all -m apt -a "name=nginx state=present" --become

# Start service
ansible all -m systemd -a "name=nginx state=started" --become

# Create user
ansible all -m user -a "name=deploy state=present" --become

# Gather facts from specific hosts
ansible web01,web02 -m setup

# Execute with specific user
ansible all -m ping -u ansible_user

# Use specific inventory
ansible all -i inventory/production -m ping

Common Options

# Connection and privilege
-u USERNAME         # Remote user
--become           # Escalate privileges (sudo)
--become-user USER # User to become (default: root)
-K                 # Prompt for privilege escalation password
-k                 # Prompt for SSH password

# Inventory
-i INVENTORY       # Specify inventory file
--list-hosts       # Show matching hosts
--limit PATTERN    # Further limit hosts

# Output
-v, -vv, -vvv     # Increase verbosity
-o                # Condensed output
--tree DIR        # Save output to files in directory

# Performance
-f FORKS          # Number of parallel processes (default: 5)
-B SECONDS        # Async timeout
-P SECONDS        # Async poll interval

# Other
-e VAR=VALUE      # Set extra variables
--check           # Dry run
--diff            # Show differences

ansible-playbook - Run Playbooks

Basic Usage

# Run playbook
ansible-playbook playbook.yml

# With inventory
ansible-playbook -i inventory/production playbook.yml

# With extra variables
ansible-playbook playbook.yml -e "version=1.2.3"

# With vault password
ansible-playbook playbook.yml --ask-vault-pass
ansible-playbook playbook.yml --vault-password-file ~/.vault_pass

# Dry run
ansible-playbook playbook.yml --check

# Show changes
ansible-playbook playbook.yml --diff

# Syntax check
ansible-playbook playbook.yml --syntax-check

Limiting Execution

# Limit to specific hosts
ansible-playbook playbook.yml --limit web01,web02

# Limit to group
ansible-playbook playbook.yml --limit webservers

# Limit with pattern
ansible-playbook playbook.yml --limit "webservers[0:5]"

# Exclude hosts
ansible-playbook playbook.yml --limit 'all:!web03'

Tags

# List available tags
ansible-playbook playbook.yml --list-tags

# Run specific tags
ansible-playbook playbook.yml --tags "install,configure"

# Skip tags
ansible-playbook playbook.yml --skip-tags "testing"

# Run tagged tasks
ansible-playbook playbook.yml --tags tagged

# Run untagged tasks
ansible-playbook playbook.yml --tags untagged

Advanced Options

# Start at specific task
ansible-playbook playbook.yml --start-at-task "Install packages"

# Step through tasks
ansible-playbook playbook.yml --step

# List tasks
ansible-playbook playbook.yml --list-tasks

# List hosts
ansible-playbook playbook.yml --list-hosts

# Force handlers
ansible-playbook playbook.yml --force-handlers

# Flush cache
ansible-playbook playbook.yml --flush-cache

ansible-galaxy - Manage Roles and Collections

Installing Roles

# Install role from Galaxy
ansible-galaxy install geerlingguy.nginx

# Install specific version
ansible-galaxy install geerlingguy.nginx,2.8.0

# Install from requirements file
ansible-galaxy install -r requirements.yml

# Install to specific path
ansible-galaxy install geerlingguy.nginx -p ./roles

# Force reinstall
ansible-galaxy install geerlingguy.nginx --force

Managing Collections

# Install collection
ansible-galaxy collection install community.general

# Install specific version
ansible-galaxy collection install community.general:5.0.0

# Install from requirements
ansible-galaxy collection install -r requirements.yml

# List installed collections
ansible-galaxy collection list

# Verify collection
ansible-galaxy collection verify community.general

Creating Roles

# Initialize new role
ansible-galaxy init my_role

# Initialize with specific structure
ansible-galaxy init --role-skeleton=/path/to/skeleton my_role

# Role structure created:
my_role/
├── defaults/
│   └── main.yml
├── files/
├── handlers/
│   └── main.yml
├── meta/
│   └── main.yml
├── tasks/
│   └── main.yml
├── templates/
├── tests/
│   ├── inventory
│   └── test.yml
└── vars/
    └── main.yml

requirements.yml Example

# roles from Galaxy
roles:
  - name: geerlingguy.nginx
    version: 2.8.0
  - name: geerlingguy.docker

# roles from GitHub
  - src: https://github.com/user/ansible-role-name
    version: main
    name: custom_role

# collections
collections:
  - name: community.general
    version: ">=5.0.0"
  - name: ansible.posix
  - name: community.docker

ansible-vault - Secrets Management

Creating and Editing

# Create encrypted file
ansible-vault create secrets.yml

# Edit encrypted file
ansible-vault edit secrets.yml

# Encrypt existing file
ansible-vault encrypt vars.yml

# Decrypt file
ansible-vault decrypt vars.yml

# View encrypted file
ansible-vault view secrets.yml

# Rekey (change password)
ansible-vault rekey secrets.yml

Using Vaulted Files

# Playbook with vault
ansible-playbook playbook.yml --ask-vault-pass

# With password file
ansible-playbook playbook.yml --vault-password-file ~/.vault_pass

# With multiple vault IDs
ansible-playbook playbook.yml \
  --vault-id dev@~/.vault_dev \
  --vault-id prod@~/.vault_prod

Encrypting Variables

# Encrypt string
ansible-vault encrypt_string 'secret_password' --name 'db_password'

# Output to include in playbooks
db_password: !vault |
  $ANSIBLE_VAULT;1.1;AES256
  66386439653236336462626566653063336164663966303231363934653561363964363833
  ...

# Encrypt string with vault ID
ansible-vault encrypt_string --vault-id dev@prompt 'secret' --name 'api_key'

ansible-config - Configuration Management

# List all config options
ansible-config list

# Show current config
ansible-config dump

# Show only changed config
ansible-config dump --only-changed

# View specific setting
ansible-config dump | grep forks

# Validate config file
ansible-config view

ansible-inventory - Inventory Management

# List all hosts
ansible-inventory --list

# Show as graph
ansible-inventory --graph

# Show specific host
ansible-inventory --host web01

# Export to JSON
ansible-inventory --list -i inventory/ > inventory.json

# Export to YAML
ansible-inventory --list -i inventory/ --yaml

# Show vars for host
ansible-inventory --host web01 --vars

ansible-doc - Documentation

# View module documentation
ansible-doc apt

# List all modules
ansible-doc -l

# List all plugins of type
ansible-doc -t callback -l

# View specific plugin type
ansible-doc -t connection ssh

# Search modules
ansible-doc -l | grep docker

# Snippet mode (show examples only)
ansible-doc apt -s

# Plugin types
ansible-doc -t module ping      # Modules
ansible-doc -t connection ssh   # Connection plugins
ansible-doc -t callback json    # Callback plugins
ansible-doc -t filter list      # Filters
ansible-doc -t lookup file      # Lookup plugins

ansible-pull - Pull-Based Architecture

Inverse operation where nodes pull configuration from a repository:

# Pull and run playbook from Git
ansible-pull -U https://github.com/user/ansible-playbooks.git

# Specify playbook
ansible-pull -U https://github.com/user/repo.git playbook.yml

# Run on schedule (cron)
ansible-pull -U https://github.com/user/repo.git \
  -d /var/lib/ansible/pull \
  -i localhost, \
  local.yml

# With inventory
ansible-pull -U https://github.com/user/repo.git \
  -i inventory/production \
  site.yml

ansible-console - Interactive Console

# Start interactive console
ansible-console

# With specific hosts
ansible-console webservers

# In console
webservers (3)[f:5]$ ping
webservers (3)[f:5]$ command uptime
webservers (3)[f:5]$ become
webservers (3)[f:5]$ apt name=nginx state=present

Common Workflows

Development Workflow

# 1. Check syntax
ansible-playbook playbook.yml --syntax-check

# 2. Dry run
ansible-playbook playbook.yml --check --diff

# 3. Run on single host
ansible-playbook playbook.yml --limit test-server

# 4. Run with tags
ansible-playbook playbook.yml --tags configure

# 5. Full run
ansible-playbook playbook.yml

Debugging Workflow

# 1. Verify inventory
ansible-inventory --list

# 2. Test connectivity
ansible all -m ping

# 3. Check facts
ansible hostname -m setup

# 4. Run with verbosity
ansible-playbook playbook.yml -vvv

# 5. Step through
ansible-playbook playbook.yml --step

Production Deployment

# 1. Validate inventory
ansible-inventory -i inventory/production --list

# 2. Syntax check
ansible-playbook site.yml --syntax-check

# 3. Dry run
ansible-playbook -i inventory/production site.yml --check

# 4. Deploy to staging first
ansible-playbook -i inventory/staging site.yml

# 5. Deploy to production
ansible-playbook -i inventory/production site.yml

Environment Variables

# Common environment variables
export ANSIBLE_CONFIG=/path/to/ansible.cfg
export ANSIBLE_INVENTORY=/path/to/inventory
export ANSIBLE_REMOTE_USER=ansible
export ANSIBLE_BECOME=true
export ANSIBLE_BECOME_USER=root
export ANSIBLE_VAULT_PASSWORD_FILE=~/.vault_pass
export ANSIBLE_FORKS=20
export ANSIBLE_HOST_KEY_CHECKING=false
export ANSIBLE_FORCE_COLOR=true
export ANSIBLE_STDOUT_CALLBACK=yaml
export ANSIBLE_GATHERING=smart
export ANSIBLE_CACHE_PLUGIN=jsonfile
export ANSIBLE_CACHE_PLUGIN_CONNECTION=/tmp/ansible_facts

Shell Aliases for Efficiency

# Add to ~/.bashrc or ~/.zshrc
alias ap='ansible-playbook'
alias aps='ansible-playbook --syntax-check'
alias apc='ansible-playbook --check'
alias apd='ansible-playbook --check --diff'
alias a='ansible'
alias ai='ansible-inventory'
alias ag='ansible-galaxy'
alias av='ansible-vault'
alias ad='ansible-doc'

# Quick commands
alias ansible-ping='ansible all -m ping'
alias ansible-uptime='ansible all -m shell -a "uptime"'
alias ansible-facts='ansible all -m setup'

Quick Reference

# ansible - Ad-hoc commands
ansible all -m ping
ansible all -m shell -a "command"
ansible all -m setup

# ansible-playbook - Run playbooks
ansible-playbook playbook.yml
ansible-playbook playbook.yml --check --diff
ansible-playbook playbook.yml --tags install

# ansible-galaxy - Roles and collections
ansible-galaxy install role_name
ansible-galaxy collection install collection_name
ansible-galaxy init role_name

# ansible-vault - Encrypt secrets
ansible-vault create secrets.yml
ansible-vault edit secrets.yml
ansible-vault encrypt_string 'password'

# ansible-config - Configuration
ansible-config dump
ansible-config list

# ansible-inventory - Inventory info
ansible-inventory --list
ansible-inventory --graph

# ansible-doc - Documentation
ansible-doc module_name
ansible-doc -l

Next Steps

• Learn about Playbooks for automation
• Explore Inventory Management
• Master Ansible Vault for secrets
• Try the Playground to practice commands