Introduction
What Tooee is, and how to use it from the CLI, from a launcher script, or as a framework for your own app.
Tooee is a framework for terminal apps built on Bun and OpenTUI. You can use it in three ways:
| Way | What you write | Start at |
|---|---|---|
| Use the CLI | Shell commands: tooee view, tooee ask, tooee choose | View |
| Write a launcher | A Bun script that calls launch() with your own data | Write a launcher |
| Build a custom app | React components on the Tooee shell | Your first Tooee app |
All three share the same screens, keys, themes, and config files. The keys are in Keyboard basics.
Built-in apps
Tooee ships three core apps exposed by the CLI as commands. The packages expose the same apps as launch() functions and as React components.
| App | Package | Job |
|---|---|---|
| View | @tooee/view | Show markdown, code, text, tables, diffs, and images with cursor movement, search, and copy. |
| Ask | @tooee/ask | Collect one line or many lines of text. |
| Choose | @tooee/choose | Filter a list and pick one or more items. |
Use the CLI
Install @tooee/cli and open a file:
tooee view README.mdTooee picks a renderer from the file extension. Press j and k to move, / to search, and q to quit. Pick this way when you read files, patches, and CSV data in the terminal and the data already exists on disk.
Write a launcher
Add @tooee/view to a Bun project and give View your own content:
import { launch } from "@tooee/view";
await launch({
contentProvider: {
load: () => ({
format: "markdown",
markdown: "# Release 0.9\n\n- Compatibility APIs removed\n- Chooser behavior shared",
title: "Release notes",
}),
},
});Run it with bun release-notes.ts. A content provider can read a file, run a process, or call an API. Ask and Choose work the same way: launch() opens the screen and resolves with the answer.
Build a custom app
Add @tooee/shell and compose a screen from React components. The shell and its sibling packages give you modes, commands with hotkeys, a document model for rows, layout chrome, overlays, panels, routing, and themes. Take this route when your tool has its own screens or several views.