AnsibleByExample

Ansible ansible-playbook Command — CLI Options and Usage

Beginner
2024-01-016By 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 →

Ansible ansible-playbook Command — CLI Options and Usage

Introduction

ansible-playbook is the primary command for running Ansible playbooks. While the basic usage is simple (ansible-playbook site.yml), the CLI offers dozens of options for controlling execution — targeting specific hosts, running in check mode, passing variables, controlling parallelism, and debugging. This guide covers every option you'll use regularly.

Basic Usage

# Run a playbook
ansible-playbook site.yml

# Specify inventory
ansible-playbook -i inventory/production site.yml

# Multiple playbooks
ansible-playbook setup.yml deploy.yml cleanup.yml

Most-Used Options

Check Mode (Dry Run)

# Show what would change without making changes
ansible-playbook site.yml --check

# Check mode with diff (show file changes)
ansible-playbook site.yml --check --diff

# Short form
ansible-playbook site.yml -C -D

Limit (Target Specific Hosts)

# Single host
ansible-playbook site.yml --limit web01

# Multiple hosts
ansible-playbook site.yml --limit "web01,web02,web03"

# Group
ansible-playbook site.yml --limit webservers

# Pattern
ansible-playbook site.yml --limit "web*"

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

# From file
ansible-playbook site.yml --limit @failed_hosts.txt

# Short form
ansible-playbook site.yml -l web01

Tags

# Run only tagged tasks
ansible-playbook site.yml --tags "deploy,configure"

# Skip tagged tasks
ansible-playbook site.yml --skip-tags "cleanup,debug"

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

# Short form
ansible-playbook site.yml -t deploy

Extra Variables

# Pass variables
ansible-playbook site.yml --extra-vars "version=2.5.1 env=production"

# JSON format
ansible-playbook site.yml --extra-vars '{"version": "2.5.1", "features": ["api", "web"]}'

# From file
ansible-playbook site.yml --extra-vars @vars/production.yml

# Short form
ansible-playbook site.yml -e "version=2.5.1"

# Multiple -e flags
ansible-playbook site.yml -e "env=prod" -e "@secrets.yml" -e "debug=false"

Verbosity

# Increasing verbosity levels
ansible-playbook site.yml -v      # Show task results
ansible-playbook site.yml -vv     # Show task input parameters
ansible-playbook site.yml -vvv    # Show connection debugging
ansible-playbook site.yml -vvvv   # Show connection plugin details (SSH)

Forks (Parallelism)

# Default: 5 parallel hosts
ansible-playbook site.yml --forks 20

# Short form
ansible-playbook site.yml -f 20

Authentication Options

# SSH key
ansible-playbook site.yml --private-key ~/.ssh/deploy_key

# SSH password (prompt)
ansible-playbook site.yml --ask-pass    # or -k

# Become (sudo) password
ansible-playbook site.yml --ask-become-pass    # or -K

# Become user
ansible-playbook site.yml --become --become-user root

# Combined
ansible-playbook site.yml -b -K    # become + ask sudo password

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

Execution Control

Start at a Specific Task

# Resume from a specific task name
ansible-playbook site.yml --start-at-task "Deploy application"

# Step through tasks one by one
ansible-playbook site.yml --step

List Mode

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

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

# List all tags
ansible-playbook site.yml --list-tags

Syntax Check

# Validate playbook syntax without running
ansible-playbook site.yml --syntax-check

Complete Reference

OptionShortDescription
--inventory-iSpecify inventory file/directory
--limit-lLimit to specific hosts/groups
--check-CDry run (don't make changes)
--diff-DShow file differences
--tags-tRun only these tags
--skip-tagsSkip these tags
--extra-vars-ePass extra variables
--verbose-vIncrease verbosity (up to -vvvv)
--forks-fParallel processes (default 5)
--become-bRun with privilege escalation
--become-userTarget user for become
--ask-become-pass-KPrompt for become password
--ask-pass-kPrompt for SSH password
--ask-vault-passPrompt for Vault password
--vault-password-fileVault password file
--private-keySSH private key
--user-uRemote user
--connection-cConnection type
--timeout-TConnection timeout
--start-at-taskStart at named task
--stepConfirm each task
--syntax-checkCheck syntax only
--list-tasksList all tasks
--list-hostsList target hosts
--list-tagsList available tags
--flush-cacheClear fact cache
--force-handlersRun handlers even on failure

Common Workflows

Development → Staging → Production

# Development
ansible-playbook deploy.yml -i inventory/dev -e "env=dev" --check --diff

# Staging (after dev succeeds)
ansible-playbook deploy.yml -i inventory/staging -e "env=staging"

# Production (with confirmation)
ansible-playbook deploy.yml -i inventory/prod -e "env=production" --step

Debug a Failing Task

# 1. Find where it fails
ansible-playbook site.yml -vvv

# 2. Start from the failing task
ansible-playbook site.yml --start-at-task "Configure database"

# 3. Step through from that point
ansible-playbook site.yml --start-at-task "Configure database" --step

Retry Failed Hosts

# First run (creates retry file on failure)
ansible-playbook site.yml
# Output: "RETRY: site.retry"

# Retry only failed hosts
ansible-playbook site.yml --limit @site.retry

Environment Variables

# Alternative to CLI flags
export ANSIBLE_INVENTORY=/path/to/inventory
export ANSIBLE_FORKS=20
export ANSIBLE_BECOME=true
export ANSIBLE_VAULT_PASSWORD_FILE=~/.vault_pass
export ANSIBLE_STDOUT_CALLBACK=yaml
export ANSIBLE_HOST_KEY_CHECKING=false

ansible-playbook site.yml

Troubleshooting

IssueSolution
"No hosts matched"Check -i inventory path and -l limit pattern
"Permission denied"Add -b -K for sudo, or --private-key
Playbook hangsReduce -f forks; check SSH connectivity
"Vault password required"Add --ask-vault-pass or --vault-password-file
Too much outputRemove -v flags; use ANSIBLE_STDOUT_CALLBACK=minimal
Changes made in check modeSome modules don't support check mode; use check_mode: false

Best Practices

  1. Always --check --diff first — preview changes before applying
  2. Use --limit in production — avoid accidental full-fleet runs
  3. Use -e @file.yml for secrets — keep sensitive vars in Vault-encrypted files
  4. Increase forks for large fleets — -f 50 for 100+ hosts
  5. Use --start-at-task for debugging — skip already-completed tasks
  6. Set common options in ansible.cfg — forks, inventory, callbacks

Conclusion

ansible-playbook is the Swiss Army knife of Ansible execution. Master --check --diff for safe previews, --limit for targeted runs, -e for runtime configuration, and -v for debugging. Combine these options into a workflow — check mode in dev, step mode for production, retry files for failed hosts — and you'll handle any deployment scenario confidently.

All Tutorials