rb

Runbook Commands

Spry Runbook (rb) Commands provide the interface for executing tasks and running workflows in Spry.

Root Command

spry rb [OPTIONS]
spry rb [COMMAND] [OPTIONS]

Options:

-h, --help - Show this help.

Commands

ls - List code cells (tasks) in markdown documents.

spry rb ls [OPTIONS] [PATHS...]

Arguments:

• PATHS - Path(s) to Markdown file(s) (defaults to Spryfile.md)

Options:

• --no-color - Show output without using ANSI colors

Examples:

spry rb ls

spry rb ls Spryfile.md

spry rb ls *.md

spry rb ls --no-color

Engine Types:

task - Execute a specific cell and its dependencies.

spry rb task [OPTIONS] <TASK_ID> [PATHS...]

Arguments:

• TASK_ID - The task identity to execute
• PATHS - Path(s) to Markdown file(s)

Arguments:

• TASK_ID - The task identity to execute
• PATHS - Path(s) to Markdown file(s)

Options:

Examples:

spry rb task task-1

spry rb task task-1 --verbose rich

spry rb task task-1 --summarize

spry rb task task-1 --verbose rich --summarize

run - Execute all code cells in markdown documents as a DAG (Directed Acyclic Graph).

spry rb run [OPTIONS] [PATHS...]

Arguments:

• PATHS - Path(s) to Markdown file(s)

Options:

• -h, --help - Show help information
• --verbose <style> - Emit information messages verbosely
  • plain - Plain text output
  • rich - Colorized/formatted output
  • markdown - Markdown formatted output
• --graph <name> - Run only nodes in provided graph(s)
• --summarize - Emit summary after execution in JSON format
• --visualize <style> - Visualize the DAG before/during execution
  • ascii-tree - Tree structure diagram
  • ascii-workflow - Workflow sequence diagram
  • ascii-flowchart - Detailed flowchart format
  • mermaid-js - Mermaid graph syntax

Examples:

# Run all tasks in order
spry rb run

# Run from specific file
spry rb run Spryfile.md

# Plain text output
spry rb run --verbose plain

# Colored detailed output
spry rb run --verbose rich

# Markdown formatted output
spry rb run --verbose markdown

# Run only Graph A tasks
spry rb run --graph A

# Run Graphs A and B
spry rb run --graph "A,B"

# Show task tree structure
spry rb run --visualize ascii-tree

# Show workflow sequence
spry rb run --visualize ascii-workflow

# Show detailed flowchart
spry rb run --visualize ascii-flowchart

# Show Mermaid diagram
spry rb run --visualize mermaid-js

# JSON execution summary
spry rb run --summarize

# Output with visualization
spry rb run --verbose rich --visualize ascii-workflow

# Save execution log
spry rb run --verbose rich --summarize > execution.json

issues - Display any issues (errors, warnings, etc.) in the mdast nodes.

spry rb issues [PATHS...]

Arguments:

• PATHS - Path(s) to Markdown file(s)

What It Detects:

• Malformed code block syntax
• Invalid task IDs
• Circular dependencies
• Missing task references
• Duplicate task names
• Syntax errors

Examples:

# Check current file
spry rb issues

# Check specific file
spry rb issues Spryfile.md

# Check all markdown files
spry rb issues *.md

Output:

No Issues:

✓ No issues found

With Issues:

Spryfile.md:
  Line 42: ERROR - Circular dependency: task-a → task-b → task-a
  Line 58: WARNING - Undefined task reference 'missing-task'
  Line 75: ERROR - Missing language specifier in code block

Usage Patterns:

1. Validate Before Running

spry rb issues && spry rb run

2. In Scripts

if spry rb issues > /dev/null; then
  echo "Ready to run"
  spry rb run
else
  echo "Fix issues first"
fi

tap - Execute all code cells and return results in TAP (Test Anything Protocol) format.

spry rb tap [OPTIONS] [PATHS...]

Arguments:

• PATHS - Path(s) to Markdown file(s)

Options:

Output Styles:

Examples:

# Run and print TAP to terminal
spry rb tap runbook.md

# Generate Markdown TAP report
spry rb tap runbook.md --style markdown

# Generate HTML report for browser viewing
spry rb tap runbook.md --style html

# Generate JSON output
spry rb tap runbook.md --style json

# Write the output to a file 
spry rb tap runbook.md --save report.tap

# Save report as JSON
spry rb tap runbook.md --style json --save report.json

# Save HTML report
spry rb tap runbook.md --style html --save test.tap.html

# Run only a specific graph
spry rb tap --graph rowcounts runbook.md

# Run multiple graphs
spry rb tap --graph "A,B" runbook.md

# Run graph and save HTML report
spry rb tap --graph rowcounts --style html --save test.tap.html

# Verbose execution with JSON output
spry rb tap --verbose rich --style json runbook.md

Use Cases:

Related Commands:

For full diagnostics with execution context and details, use:

spry rb report > report.md
spry rb report --graph rowcounts > report.rowcounts.md

report - Execute all code cells and return as new markdown with outputs embedded.

spry rb report [OPTIONS] [PATHS...]

Arguments:

• PATHS - Path(s) to Markdown file(s)

Options:

Examples:

# Generate report from current directory
spry rb report

# Generate report from specific file
spry rb report Spryfile.md

# Generate reports from multiple files
spry rb report *.md

# Generate reports and save the response to a file
spry rb report file.md > executed-runbook.md

Output Example

Before:

```bash
echo "Hello"
```

After:

```bash
echo "Hello"
```
```output
Hello
```

File Sources

All commands that accept file paths support:

1. Local file system paths: ./Spryfile.md, /path/to/file.md
2. Default behavior: If no path is provided, uses Spryfile.md in the current directory
3. Multiple sources: Some commands support multiple file paths