ansible-playbook

Run tasks in playbook

$ ansible-playbook [playbook]

$ ansible-playbook [playbook] [[-i|--inventory]] [inventory_file]

$ ansible-playbook [playbook] [[-e|--extra-vars]] "[variable1]=[value1] [variable2]=[value2]"

$ ansible-playbook [playbook] [[-e|--extra-vars]] "@[variables.json]"

$ ansible-playbook [playbook] [[-t|--tags]] [tag1,tag2]

$ ansible-playbook [playbook] --start-at [task_name]

$ ansible-playbook [playbook] [[-C|--check]] [[-D|--diff]]

ansible-playbook [options] [playbook.yml] ...

-i INVENTORY, --inventory INVENTORY
    Specify path(s) to inventory host file(s) or host pattern

--limit LIMIT
    Further limit subset of hosts in inventory (comma-separated patterns)

-l SUBSET, --limit SUBSET
    Alias for --limit

--list-hosts, --list-tasks, --list
    Output list of matching hosts, tasks, etc., without execution

--syntax-check
    Perform syntax check on playbooks without execution

--check
    Dry-run mode; simulate changes without applying them

--diff
    Show diff output for file changes (with --check)

-v, -vv, ... -vvvvv
    Verbose mode (-v once up to very verbose)

--tags TAGS, -t TAGS
    Only run tasks matching these tags

--skip-tags TAGS
    Skip tasks matching these tags

-K, --ask-become-pass
    Prompt for sudo/become password

--ask-vault-pass
    Prompt for vault password

-e EXTRA_VARS, --extra-vars EXTRA_VARS
    Set variables (JSON, YAML, or key=value)

--vault-id @prompt
    Vault ID for decryption (interactive)

-u USER, --user USER
    Connect as this user (default: current user)

-c CONNECTION, --connection CONNECTION
    Connection type (ssh, paramiko, local, docker, etc.)

--forks FORKS
    Max number of parallel processes (default: 5)

-f FORKS, --forks FORKS
    Alias for --forks

--module-path PATH
    Directories to load modules/roles from

--roles-path PATH
    Directories to search for roles

-C, --check
    Alias for --check

--start-at-task TASK
    Start at specific task

-b, --become
    Run tasks with privilege escalation (sudo)

--become-method METHOD
    Privilege escalation method (sudo, su, etc.)

-J, --flush-cache
    Clear fact cache before run

--step
    Interactive mode; prompt before each task

ansible-playbook is the core command-line tool in Ansible, an agentless automation platform, used to run playbooks—YAML files defining a series of tasks, roles, and configurations for managing infrastructure, applications, and deployments across multiple hosts.

It orchestrates execution over SSH (default), WinRM for Windows, or other plugins, gathering facts about remote systems before applying tasks idempotently (only making changes when necessary). Playbooks support variables, conditionals, loops, handlers, and modules for tasks like package management, file operations, services, and cloud APIs.

Key features include dry-run mode (--check), syntax validation (--syntax-check), verbose output (-v to -vvvvv), tagging for selective execution, and integration with inventories (host lists/groups), vaults (encrypted secrets), and collections (modular extensions). It scales from single hosts to thousands via parallelism controls.

Ideal for configuration management, application deployment, orchestration, and compliance, it promotes simplicity with no custom agents required. Output includes task status (ok/changed/failed/unreachable), stats, and JSON for parsing.

Requires Ansible installed and SSH key setup for non-interactive use; idempotency assumes modules are written correctly; large inventories may hit memory limits; Windows hosts need WinRM configured.

YAML with hosts, become, tasks, roles, vars; tasks use modules like apt, service, template.

0: success; 1: error; 2: one+ hosts failed; 4: connection failed; 5: bad syntax.

Introduced in Ansible 1.0 (2013) by Michael DeHaan; evolved through Red Hat acquisition (2015); now at Ansible 2.10+ with collections; core to Ansible Core and AWX/Tower.

ansible(1), ansible-inventory(1), ansible-config(1), ansible-vault(1), ansible-galaxy(1)