Playbook Mate

pbm is a concise CLI for inspecting inventories, validating Ansible® projects, and running playbooks. Think of it as a small companion for the repetitive parts of working with an Ansible project

pbm does not replace Ansible. It helps you inspect an inventory, validate project structure, understand playbook variables, and run playbooks with predictable commands

Contents

• Playbook Mate
  • Contents
  • Get started
    • Requirements
    • Install
    • Run the first checks
  • Commands
    • Inventory
    • Playbooks
    • Validation
    • Playbook information
    • Run a playbook
  • Inventory example
  • Argument specs example
  • Development
  • License
  • Trademark

Get started

Requirements

Python 3.11 or newer is required. ansible-core and PyYAML are installed automatically. A supported project must contain ansible.cfg and a playbooks/ directory

Install

Install Playbook Mate as an isolated command-line application with pipx:

pipx install playbook-mate
pbm --version

Alternatively, install it into the active Python environment:

python3 -m pip install playbook-mate

Run the first checks

Open an Ansible project and let pbm discover its configuration:

cd /path/to/your/ansible-project
pbm check
pbm inventory
pbm playbooks

pbm check validates the project without connecting to managed hosts

To try Playbook Mate with the bundled example:

git clone --branch v2.0.1 --depth 1 \
  https://github.com/neuron22/playbook-mate.git
cd playbook-mate/examples/basic
pbm check
pbm inventory
pbm info hello

The complete example is available in examples/basic

Commands

pbm --help
pbm --version
pbm COMMAND --help

Inventory

pbm inventory
pbm inventory --list
pbm inventory --list --yaml
pbm inventory --host HOST

With no options, the command displays the inventory graph. Pass additional ansible-inventory arguments after --:

pbm inventory -- --vars

Playbooks

pbm playbooks

Lists playbooks available in the project's playbooks/ directory.

Validation

pbm check
pbm check PLAYBOOK
pbm check --skip-inventory

The command validates the inventory, argument_specs.yml, consistency between role defaults and argument specs, and playbook syntax. It does not connect to managed hosts.

Playbook information

pbm info PLAYBOOK

Displays the playbook's roles and their variable contracts, including required values, types, descriptions, choices, and defaults.

Run a playbook

pbm run PLAYBOOK -l TARGET [OPTIONS]

Examples:

pbm run ping -l app_servers
pbm run deploy_app -l app01 -e app_version=2.0 -e environment=stage
pbm run deploy_app -l app_servers -e @deploy-vars.yml --check --diff

Pass additional ansible-playbook arguments after --:

pbm run ping -l app_servers -- --list-hosts
pbm run deploy_app -l app01 -e app_version=2.0 -- -K

Inventory example

A complete minimal project is available in examples/basic. A YAML inventory can be structured as follows:

---
all:
  hosts:
    standalone01:
      ansible_host: 192.0.2.10
      ansible_user: deploy

  children:
    app_servers:
      vars:
        ansible_user: deploy
      hosts:
        app01:
          ansible_host: 192.0.2.11
        app02:
          ansible_host: 192.0.2.12

Argument specs example

# roles/app/meta/argument_specs.yml
---
argument_specs:
  main:
    short_description: Install an application
    options:
      app_name:
        type: str
        required: true
        description: Short application name
      app_user:
        type: str
        default: app
        description: System user for the application
      retries:
        type: int
        default: 3
        choices: [1, 3, 5]
        description: Number of retry attempts

Actual default values must also be defined in roles/app/defaults/main.yml:

---
app_user: app
retries: 3

Defaults in both files must match; pbm check validates this rule. Options with required: true must not define a default.

Development

Clone the repository and install it in editable mode with the development dependencies:

git clone https://github.com/neuron22/playbook-mate.git
cd playbook-mate
python3 -m pip install -e '.[dev]'

Run the same checks used by CI:

ruff check playbook_mate tests
ruff format --check playbook_mate tests
python3 -m unittest discover -s tests -v

License

Playbook Mate is available under the MIT License.

Trademark

Ansible is a registered trademark of Red Hat, LLC in the United States and other countries. Playbook Mate is an independent project and is not affiliated with or endorsed by Red Hat