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
    • Project path
    • Diagnostics
    • 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 doctor

pbm check validates the project without connecting to managed hosts

To try Playbook Mate with the bundled example:

git clone --branch v2.1.0 --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

Project path

By default, Playbook Mate searches the current directory and its parents for a project root containing ansible.cfg and playbooks/. Use --project to start the search from a different directory:

pbm --project /path/to/your/ansible-project check
pbm --project /path/to/your/ansible-project playbooks
pbm --project /path/to/your/ansible-project doctor

Diagnostics

pbm doctor

The command reports the Playbook Mate, Python, and Ansible versions; paths to the required Ansible commands; the detected project root; and the active Ansible configuration. It diagnoses the local environment without validating inventory contents or playbook syntax.

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
pbm check --strict

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.

A role without meta/argument_specs.yml produces a warning by default, and the remaining checks continue. Use --strict in CI or projects that require every role to define an argument specification.

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