DOCSEARCHbyAlgolia
Submit Docs

showboat

repository·main·Indexed 22 days ago

https://github.com/simonw/showboat

A CLI tool for creating executable markdown documents that combine commentary, code blocks, and captured outputs to provide reproducible proof of work. It includes commands to initialize documents, append notes, execute code in various languages, manage images, and verify document integrity by re-running code blocks. Showboat also supports extracting recreation commands from existing documents and real-time streaming of updates to a remote viewer via the SHOWBOAT_REMOTE_URL environment variable.

Tokens
10.7K
Snippets
48
Records
58
Agent score
74%

What's inside showboat

  2. Understand Showboat markdown block types

    main

    Showboat documents are composed of several distinct block types. Each block type represents a specific element in the markdown document:

    • TitleBlock: The document header, consisting of an H1 title and a timestamp.
    • CommentaryBlock: Free-form markdown prose used for explanation.
    • CodeBlock: An executable fenced code block. It includes the language (Lang) and the source code (Code). If IsImage is true, it is treated as an image-generating block.
    • OutputBlock: Captured text output resulting from a CodeBlock.
    • ImageOutputBlock: A captured image reference, containing AltText and a Filename.

    These blocks are serialized into a specific markdown format where code blocks are often immediately followed by their corresponding output blocks.

  3. Reflect exit codes using `build run`

    main

    When using build run, Showboat reflects the exit code of the executed shell command. If the command fails (returns a non-zero exit code), build run will also exit with that same code. The output of the failed command is still captured and recorded within the document, even if the command itself fails.

    /tmp/showboat build /tmp/demo.md run bash "echo about to fail && exit 1"
echo "showboat exit code: $?"

  4. Run integration tests for Showboat

    main

    To verify the full workflow of the application, you can run the specific integration test using the Go test tool. This ensures that the sequence of creating a demo, adding commentary, running commands, and capturing screenshots works as expected.

    Run the following command to execute the full workflow test: go test -v -run TestFullWorkflow -timeout 60s

    go test -v -run TestFullWorkflow -timeout 60s

  5. Install Showboat

    main

    You can install Showboat using pip, uv, or go. It is also available to run without installation via uvx or go run.

    Using Python tools

    # Run without installing
uvx showboat --help

# Install via uv
uv tool install showboat

# Install via pip
pip install showboat

    Using Go

    # Install the Go binary
go install github.com/simonw/showboat@latest

# Run without installation
go run github.com/simonw/showboat@latest --help
    uvx showboat --help

  7. Capture and display shell output with `build run`

    main

    The build run command executes a shell command and captures its output into the document. Unlike previous versions, it now also prints the command's stdout directly to your terminal. This allows you to see the results of the command execution in real-time while they are being recorded in the demo document.

    /tmp/showboat build /tmp/demo.md run bash "echo Hello from the inner document"

  9. Install and use Showboat

    main

    Showboat is a Go CLI tool for creating executable markdown demo documents. It allows you to mix commentary, executable code, and captured output (including images) into a single, verifiable markdown file. This is particularly useful for agents or developers who want to provide documentation that proves its own correctness.

    Package: github.com/simonw/showboat

  10. Initialize a new demo document

    main

    Use showboat init <file> <title> to create a new markdown demo document with a specified filename and title. This serves as the starting point for building an executable document.

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

  11. Use the Showboat CLI to create and build demo documents

    main

    Showboat is a CLI tool designed to help agents create, verify, and extract executable markdown demo documents. These documents combine commentary, executable code blocks, and captured output to serve as both documentation and reproducible proof of work.

    Core Commands

    • showboat init <file> <title>: Initializes a new demo document with a title and timestamp.
    • showboat build <file> <subcommand> [args]: Appends content to an existing document.
      • commentary [text]: Appends markdown prose. If text is omitted, it reads from stdin.
      • run <lang> [code]: Executes code in the specified language and appends both the code block and the captured output.
      • image [script]: Runs a script, captures an image output, and appends the image reference.
    • showboat verify <file> [--output <new>]: Re-runs all code blocks in the file and compares the new output against the existing output to ensure the demo is still valid.
    • showboat extract <file>: Emits the sequence of build commands required to recreate the document from scratch.

    Global Options

    • --workdir <dir>: Sets the working directory for code execution (defaults to the current directory).
    • --help, -h: Shows the help message.

    Usage Examples

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

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

# Add commentary via stdin
echo "More text here" | showboat build demo.md commentary

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

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

# Run a script to capture a screenshot
showboat build demo.md image "python screenshot.py http://localhost:8000"

# Verify the demo still works
showboat verify demo.md

# Extract the build commands
showboat extract demo.md
    showboat init demo.md "Setting Up a Python Project"
showboat build demo.md commentary "First, let's create a virtual environment."
showboat build demo.md run bash "python3 -m venv .venv && echo 'Done'"
showboat build demo.md run python "print('Hello from Python')"
showboat build demo.md image "python screenshot.py http://localhost:8000"
showboat verify demo.md
showboat extract demo.md

  12. Use Showboat CLI commands to build a demo

    main

    Use the following commands to incrementally build a markdown demo document:

    • showboat init <file> <title>: Create a new demo document with a title.
    • showboat note <file> [text]: Append commentary. If [text] is omitted, it reads from stdin.
    • showboat exec <file> <lang> [code]: Run code in a specific language (e.g., bash, python3) and capture the output. If [code] is omitted, it reads from stdin. The captured output is printed to stdout and appended to the document.
    • showboat image <file> <path>: Copy an image into the document directory. Use a markdown reference like '![alt](path)' to preserve alt text.
    • showboat pop <file>: Remove the most recent entry (the last note, exec, or image block).

    Example Workflow

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

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

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

# 4. Run Python code
showboat exec demo.md python "print('Hello from Python')"

# 5. Add a screenshot
showboat image demo.md '![Homepage screenshot](screenshot.png)'
    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 image demo.md '![Homepage screenshot](screenshot.png)'