playbook-cli

README

PLAYBOOK.md CLI

A command-line tool for authoring, validating, and inspecting PLAYBOOK.md files — multi-step AI workflows written in plain markdown.

Built with the Charm ecosystem for a polished terminal experience.

Install

go install github.com/PLAYBOOK-MD/playbook-cli@latest

Or build from source:

git clone https://github.com/PLAYBOOK-MD/playbook-cli.git
cd playbook-cli
go build -o playbook .

Usage

Validate playbooks

# Validate a single file
playbook validate my-workflow.playbook.md

# Validate multiple files with a glob
playbook validate *.playbook.md

# JSON output for CI pipelines
playbook validate --json *.playbook.md

# Silent mode (exit code only)
playbook validate --quiet *.playbook.md

Exit code 0 means all files are valid. Exit code 1 means one or more files have errors.

Parse a playbook

# Pretty-printed AST with styled header
playbook parse my-workflow.playbook.md

# Raw JSON output
playbook parse --json my-workflow.playbook.md

Show a summary

# Styled summary card
playbook summary my-workflow.playbook.md

# "info" is an alias
playbook info my-workflow.playbook.md

Displays title, description, step list, input/step counts, and feature badges (branching, elicitation, tool calls).

Convert to JSON

# Output to stdout
playbook convert my-workflow.playbook.md --to json

# Write to a file
playbook convert my-workflow.playbook.md --to json --output workflow.json

Scaffold a new playbook

# Interactive form
playbook init

# Specify output path
playbook init --output my-new-workflow.playbook.md

Walks you through an interactive form to set title, description, step count, and optional features (inputs, branching, artifacts), then generates a .playbook.md file.

Browse playbooks (TUI)

playbook tui [directory]

Interactive terminal browser for .playbook.md files. Browse, inspect, and navigate step-by-step using Bubble Tea.

• File browser with search/filter
• Playbook detail cards with validation status
• Step-by-step viewer with directive highlighting
• Keyboard-driven: arrows to navigate, enter to select, s for steps, v for validation, j for JSON

Set up editor integration

# Auto-detect coding tool
playbook setup

# Specify tool directly
playbook setup --tool claude-code
playbook setup --tool codex

# Preview without writing files
playbook setup --dry-run

Generates MCP server config and agent instruction files for your coding tool. Supports Claude Code, Codex, opencode, Continue, Cline, and Aider.

Development

Requires Go 1.22+.

This CLI depends on the Go SDK at ../playbook-integrations/packages/go/. The go.mod file uses a replace directive to reference it locally:

replace github.com/PLAYBOOK-MD/playbook-integrations/packages/go => ../playbook-integrations/packages/go

To build:

go mod tidy
go build -o playbook .

Tech Stack

• Cobra - Command structure
• Lip Gloss - Styled terminal output
• Glamour - Markdown rendering
• Huh - Interactive forms
• Charm Log - Structured logging

License

MIT