simonw/showboat

uvx showboat --help

uv tool install showboat
# or
pip install showboat

go install github.com/simonw/showboat@latest

go run github.com/simonw/showboat@latest --help

showboat - Create executable demo documents that show and prove an agent's work.

Showboat helps agents build markdown documents that mix commentary, executable
code blocks, and captured output. These documents serve as both readable
documentation and reproducible proof of work. A verifier can re-execute all
code blocks and confirm the outputs still match.

Usage:
  showboat init <file> <title>             Create a new demo document
  showboat note <file> [text]              Append commentary (text or stdin)
  showboat exec <file> <lang> [code]       Run code and capture output
  showboat image <file> <path>             Copy image into document
  showboat image <file> '![alt](path)'   Copy image with alt text
  showboat pop <file>                      Remove the most recent entry
  showboat verify <file> [--output <new>]  Re-run and diff all code blocks
  showboat extract <file> [--filename <name>]  Emit commands to recreate file

Global Options:
  --workdir <dir>   Set working directory for code execution (default: current)
  --version         Print version and exit
  --help, -h        Show this help message

Exec output:
  The "exec" command prints the captured shell output to stdout and exits with
  the same exit code as the executed command. This lets agents see what happened
  and react to errors. The output is still appended to the document regardless
  of exit code. Use "pop" to remove a failed entry.

    $ showboat exec demo.md bash "echo hello && exit 1"
    hello
    $ echo $?
    1

Image:
  The "image" command accepts a path to an image file or a markdown image
  reference of the form ![alt text](path). The image is copied into the same
  directory as the document with a generated filename and an image reference is
  appended to the markdown. When a markdown reference is provided the alt text
  is preserved; otherwise it is derived from the generated filename.

Pop:
  The "pop" command removes the most recent entry from a document. For an "exec"
  or "image" entry this removes both the code block and its output. For a "note"
  entry it removes the single commentary block. This is useful when a command
  produces an error that shouldn't remain in the document.

Verify:
  Re-runs every code block (skipping image blocks) and compares actual output
  against the recorded output. Prints diffs and exits with code 1 if any output
  has changed; exits 0 if everything matches. Use --output <file> to write an
  updated copy of the document with the new outputs without modifying the
  original.

Extract:
  Parses a document and prints the sequence of showboat CLI commands (one per
  line) that would recreate it from scratch. Output blocks are omitted since
  they are regenerated by "exec". Use --filename <name> to substitute a
  different filename in the emitted commands.

Stdin:
  Commands accept input from stdin when the text/code argument is omitted.
  For example:
    echo "Hello world" | showboat note demo.md
    cat script.sh | showboat exec demo.md bash

Example:
  # Create a demo
  showboat init demo.md "Setting Up a Python Project"

  # Add commentary
  showboat note demo.md "First, let's create a virtual environment."

  # Run a command and capture output (output is printed to stdout)
  showboat exec demo.md bash "python3 -m venv .venv && echo 'Done'"

  # Run Python and capture output
  showboat exec demo.md python "print('Hello from Python')"

  # Oops, wrong command — remove the last entry from the document
  showboat pop demo.md

  # Redo it correctly
  showboat exec demo.md python3 "print('Hello from Python')"

  # Add a screenshot
  showboat image demo.md screenshot.png

  # Add a screenshot with alt text
  showboat image demo.md '![Homepage screenshot](screenshot.png)'

  # Verify the demo still works
  showboat verify demo.md

  # See what commands built the demo
  showboat extract demo.md

Resulting markdown format:

  # Setting Up a Python Project

  *2026-02-06T15:30:00Z*

  First, let's create a virtual environment.

  ```bash
  python3 -m venv .venv && echo 'Done'
  ```

  ```output
  Done
  ```

  ```python3
  print('Hello from Python')
  ```

  ```output
  Hello from Python
  ```

  ```bash {image}
  screenshot.png
  ```

  ![screenshot](screenshot.png)

  ```bash {image}
  ![Homepage screenshot](screenshot.png)
  ```

  ![Homepage screenshot](screenshot.png)

# Create a demo
showboat init demo.md "Setting Up a Python Project"

# Add commentary
showboat note demo.md "First, let's create a virtual environment."

# Run a command and capture output
showboat exec demo.md bash "python3 -m venv .venv && echo 'Done'"

# Run Python and capture output
showboat exec demo.md python "print('Hello from Python')"

# Add a screenshot
showboat image demo.md screenshot.png

# Add a screenshot with alt text
showboat image demo.md '![Homepage screenshot](screenshot.png)'

# Setting Up a Python Project

*2026-02-06T15:30:00Z*

First, let's create a virtual environment.

```bash
python3 -m venv .venv && echo 'Done'
```

```output
Done
```

```python
print('Hello from Python')
```

```output
Hello from Python
```

showboat verify demo.md

showboat extract demo.md

showboat init demo.md 'Setting Up a Python Project'
showboat note demo.md 'First, let'\''s create a virtual environment.'
showboat exec demo.md bash 'python3 -m venv .venv && echo '\''Done'\'''
showboat exec demo.md python 'print('\''Hello from Python'\'')'

showboat extract demo.md --filename copy.md

<!-- showboat-id: 550e8400-e29b-41d4-a716-446655440000 -->

export SHOWBOAT_REMOTE_URL=https://www.example.com/showboat

export SHOWBOAT_REMOTE_URL=https://www.example.com/showboat?token=secret-token-here

uvx go-to-wheel . \
  --readme README.md \
  --description "Create executable documents that demonstrate an agent's work" \
  --author 'Simon Willison' \
  --license Apache-2.0 \
  --url https://github.com/simonw/showboat \
  --set-version-var main.version \
  --version 0.1.0