Run the workshop in the project that owns your OpenTUI components. The public website and hosted Docs are separate from this local development process.

1. Prerequisites

Use Bun, not Node.js, to run Textbook. Your project should use @opentui/core for its terminal components. When contributing to Textbook itself, use the repository's Devenv environment for its toolchain.

bun --version

2. Installation

Add textbook to your project dependencies:

bun add -d textbook

3. Add a story

Create a file such as src/button.stories.ts using the Writing Stories guide. Textbook discovers *.stories.ts files under the current directory by default. Installing Textbook does not add the repository's example catalog to your project.

4. Start your local Canvas

bunx textbook web --open
# Or select the directory containing your stories:
bunx textbook web --cwd src --port 8008 --open

The command prints the local URL, normally http://localhost:8008/. Keep the process running. Select a story in the sidebar, then click the terminal to interact with it. A link to localhost means the reader's machine, not a hosted demo.

5. Read Docs online or locally

Continue reading hosted Docs, or start a separate local Docs process:

bunx textbook docs --open

Local Docs default to port 8001. They do not start a terminal renderer. For project-specific documentation, run Docs and Canvas with the same working directory and story discovery options:

# Terminal 1: run your components
bunx textbook web --cwd src --open
# Terminal 2: browse their local documentation
bunx textbook docs --cwd src --open

On loopback addresses, local Docs adds a Project Stories section with documented props and links to the matching local Canvas story. Repository example guides only get a Canvas link when that example is loaded in the Docs registry. Canvas still needs to be running with the same story files; a link does not start it. Hosted Docs show the guide without these project controls.

The landing website is deployed separately and has no CLI command.

Terminal TUI and command help

You can also run Textbook directly inside your current terminal session:

bunx textbook
bunx textbook --help
bunx textbook --man

For repository contributors, devenv tasks run textbook:landing, textbook:docs, and textbook:canvas start the three development surfaces on ports 8000, 8001, and 8008 respectively. These tasks belong to the Textbook repository, not projects that merely install the package.