Showboat Demos

Overview

Showboat is a CLI tool that constructs Markdown documents by capturing real command output. Each exec block runs a command, records the output, and appends both to the document. The result is a reproducible demo that proves code works — not just that tests pass.

Install: go install github.com/simonw/showboat@latest

When to Use

• After implementing a new feature or API endpoint
• After fixing a bug that affected observable behavior
• When onboarding documentation needs live examples
• When a PR would benefit from proof-of-work beyond test results

Do NOT use for:

• Internal implementation details (test those with unit tests)
• Workflows requiring complex auth flows that can't be reproduced locally

Core Workflow

init → note → exec → exec → ... → verify

1. init: Create the document with a title
2. note: Add descriptive text explaining what follows
3. exec: Run a command and capture its output
4. verify: Re-run all commands and confirm outputs match

Example: API Demo

# Create the demo document
showboat init demos/users-api.md 'Users API'

# Describe what we're demonstrating
showboat note demos/users-api.md 'Create a user and verify the response'

# Execute and capture API calls
showboat exec demos/users-api.md bash \
  'curl -s -X POST http://localhost:3000/users \
   -H "Content-Type: application/json" \
   -d "{\"name\":\"test\"}" | jq .'

showboat exec demos/users-api.md bash \
  'curl -s http://localhost:3000/users | jq .'

# Verify the demo is reproducible
showboat verify demos/users-api.md

Example: CLI Tool Demo

showboat init demos/my-cli.md 'My CLI Tool'

showboat note demos/my-cli.md 'Show help output'
showboat exec demos/my-cli.md bash 'my-cli --help'

showboat note demos/my-cli.md 'Run a basic command'
showboat exec demos/my-cli.md bash 'my-cli process input.txt'

showboat verify demos/my-cli.md

Naming Convention

Name demo files after the feature: demos/<feature>.md

Examples: demos/users-api.md, demos/email-sync.md, demos/search.md

Error Recovery

If an exec captures bad output (wrong response, error, etc.):

# Remove the last section
showboat pop demos/feature.md

# Fix the issue, then retry
showboat exec demos/feature.md bash 'fixed-command'

pop removes the most recent entry (note, exec, or image). Call it multiple times to remove multiple entries.

Verification

verify re-runs every exec block and compares output to what was recorded:

showboat verify demos/feature.md

• Exit code 0: all outputs match
• Exit code 1: outputs differ (demo is stale or non-reproducible)

Use --output to write an updated version without modifying the original:

showboat verify demos/feature.md --output demos/feature-updated.md

Best Practices

1. One concept per demo — a single feature or short workflow, not an entire surface area
2. Progressive complexity — start with the simplest call, then show variations
3. Use jq for formatting — pipe JSON output through jq . for readability
4. Add -s to curl — suppress progress bars (curl -s)
5. Narrate with notes — explain what each exec block demonstrates
6. Verify before committing — always run showboat verify to confirm reproducibility
7. Idempotent demos — prefer read operations or use unique test data so demos can re-run cleanly