Metadata-Version: 2.4
Name: playbook-mate
Version: 2.0.1
Summary: A concise CLI companion for Ansible projects
Author: neuron22
License-Expression: MIT
Project-URL: Homepage, https://github.com/neuron22/playbook-mate
Project-URL: Repository, https://github.com/neuron22/playbook-mate.git
Project-URL: Issues, https://github.com/neuron22/playbook-mate/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ansible-core>=2.19
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: ruff>=0.12; extra == "dev"
Dynamic: license-file

# 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](#playbook-mate)
  - [Contents](#contents)
  - [Get started](#get-started)
    - [Requirements](#requirements)
    - [Install](#install)
    - [Run the first checks](#run-the-first-checks)
  - [Commands](#commands)
    - [Inventory](#inventory)
    - [Playbooks](#playbooks)
    - [Validation](#validation)
    - [Playbook information](#playbook-information)
    - [Run a playbook](#run-a-playbook)
  - [Inventory example](#inventory-example)
  - [Argument specs example](#argument-specs-example)
  - [Development](#development)
  - [License](#license)
  - [Trademark](#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

```bash
python3 -m pip install \
  "git+https://github.com/neuron22/playbook-mate.git@v2.0.1"
pbm --version
```

### Run the first checks

Open an Ansible project and let `pbm` discover its configuration:

```bash
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:

```bash
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`](examples/basic)

## Commands

```bash
pbm --help
pbm --version
pbm COMMAND --help
```

### Inventory

```bash
pbm inventory
pbm inventory --list
pbm inventory --list --yaml
pbm inventory --host HOST
```

| Option | Description |
| --- | --- |
| `--list` | Show the complete inventory with variables |
| `--host HOST` | Show variables for a host |
| `-y`, `--yaml` | Output YAML instead of JSON |

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

```bash
pbm inventory -- --vars
```

### Playbooks

```bash
pbm playbooks
```

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

### Validation

```bash
pbm check
pbm check PLAYBOOK
pbm check --skip-inventory
```

| Argument or option | Description |
| --- | --- |
| `PLAYBOOK` | Validate only the specified playbook |
| `--skip-inventory` | Skip inventory validation |

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

```bash
pbm info PLAYBOOK
```

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

### Run a playbook

```bash
pbm run PLAYBOOK -l TARGET [OPTIONS]
```

| Option | Description |
| --- | --- |
| `-l`, `--limit`, `--target TARGET` | Target host, group, or Ansible pattern; required |
| `-e`, `--extra-vars VARS` | `key=value`, YAML/JSON, or `@vars.yml`; may be repeated |
| `-C`, `--check` | Run in check mode without applying changes |
| `-D`, `--diff` | Show file and template changes |
| `-v`, `--verbose` | Increase verbosity; may be repeated as `-vv` or `-vvv` |
| `-t`, `--tags TAGS` | Run only tasks with the specified tags; may be repeated |
| `--skip-tags TAGS` | Skip tasks with the specified tags; may be repeated |

Examples:

```bash
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 `--`:

```bash
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:

```yaml
---
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

```yaml
# 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`:

```yaml
---
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:

```bash
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:

```bash
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
