terminaltui
A standardized engine for terminal apps.
Write a pages directory of TypeScript. Get a navigable terminal app you can ship with npx or host over SSH.
npx terminaltui tryA five-page guided tour. Nothing to install.
████████╗███████╗██████╗ ███╗ ███╗██╗███╗ ██╗ █████╗ ██╗ ████████╗██╗ ██╗██╗ ╚══██╔══╝██╔════╝██╔══██╗████╗ ████║██║████╗ ██║██╔══██╗██║ ╚══██╔══╝██║ ██║██║ ██║ █████╗ ██████╔╝██╔████╔██║██║██╔██╗ ██║███████║██║ ██║ ██║ ██║██║ ██║ ██╔══╝ ██╔══██╗██║╚██╔╝██║██║██║╚██╗██║██╔══██║██║ ██║ ██║ ██║██║ ██║ ███████╗██║ ██║██║ ╚═╝ ██║██║██║ ╚████║██║ ██║███████╗ ██║ ╚██████╔╝██║ ╚═╝ ╚══════╝╚═╝ ╚═╝╚═╝ ╚═╝╚═╝╚═╝ ╚═══╝╚═╝ ╚═╝╚══════╝ ╚═╝ ╚═════╝ ╚═╝ Next.js for the terminal ──────────────────────────────────────────────────────────────────────────────────────────────────── ❯ ◆ // Home [1] ◆ >> Showcase [2] ◆ ## Themes [3] ◆ ~~ Live Data [4] ◆ ++ Get Started [5] ◆ [] Images [6] ──────────────────────────────────────────────────────────────────────────────────────────────────── ↑↓ navigate ⏎ select q quit : command
The welcome tour, flintNight theme, 100 columns. Not a mockup: this is the real cell grid, dumped out of a headless PTY.
The file is the screen.
A directory of TypeScript files becomes a navigable app. Brackets make a route dynamic. A file under api/ is an HTTP endpoint. You do not design an architecture, because there is one.
Nothing else routes terminal screens this way. Ink is a component library. Pastel routes CLI subcommands. Bubble Tea gives you an update loop and a blank canvas.
pages/index.ts/pages/about.ts/aboutpages/projects/index.ts/projectspages/projects/[slug].ts/projects/:slugapi/stats.tsGET /api/stats← back >> Projects ──────────────────────────────────────────────────────────────────────────────────────────────────── ▌╭─────────────────────────────────────────────────────────────────────────────────────────────────╮ ▌│ Search projects... │ ▌╰─────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭──────────────────────────────────────────────╮ │ ╭──────────────────────────────────────────────╮ │ ◇ Patchwork Lead Engineer @ Stit… │ │ │ ◇ Vektor Open Source (2024) │ │ A collaborative document editor built on │ │ │ A type-safe database query builder and │ │ CRDTs that handles 50k+ concurrent users. │ │ │ migration toolkit for TypeScript. Compiles │ │ Real-time cursors, inline comments, version │ │ │ queries at build time for zero-runtime │ │ history, and a plugin SDK used by 200+ │ │ │ overhead. Supports PostgreSQL, SQLite, and │ │ teams. Built with React, Hocuspocus, and │ │ │ MySQL with full IntelliSense. 4.2k GitHub │ │ Y.js. │ │ │ stars. │ │ │ │ │ │ │ [React] [CRDTs] [WebSockets] [TypeScript] │ │ │ [TypeScript] [PostgreSQL] [CLI] │ ╰──────────────────────────────────────────────╯ │ │ [Open Source] │ │ ╰──────────────────────────────────────────────╯ ╭──────────────────────────────────────────────╮ │ ╭──────────────────────────────────────────────╮
pages/projects.ts in the developer-portfolio demo. Cards, focus ring and keyboard navigation, none of it hand-drawn.
Two ways to ship. Both are one line.
Over npm
npx your-appPublish the bundle and anyone runs it. No install step, no binary to build for three platforms, no Electron, no browser.
Over SSH
terminaltui serveOne server, many sessions. Colour depth is negotiated per client from its TERM, so the same app is correct in Apple Terminal and in kitty.
Photographs, in a grid of characters.
On kitty and Ghostty the renderer draws real pixels through the kitty graphics protocol. Everywhere else it paints coloured cells with block glyphs at the same row count, so the layout never moves and images survive tmux, SSH and Apple Terminal.
image("./cover.png", { width: 60 })
3 runtime dependencies hold the whole thing up: esbuild, jpeg-js, pngjs. No sharp, no node-gyp, no postinstall build. Video uses the same pipeline over prepacked frames: real pixels on Kitty and Ghostty, coloured cells elsewhere.
Rendering proof
Now watch it move.
A real three-second capture of Cinema running inside Kitty—not a browser mock-up. Play it here, then open the dedicated page for the rendering paths, measurements and reproducible command.
Designed before you start.
42 components, 12 themes, a 12-column grid, 14 ASCII fonts and 15 scenes. The first commit already looks considered.
- Content
- section · card · timeline · table · list · quote · hero · gallery · tabs · accordion · link · skillBar · progressBar · badge · image · text · ascii · markdown · gradient · sparkline · divider · spacer
- Input
- textInput · textArea · select · checkbox · toggle · radioGroup · numberInput · searchInput · button · form · asyncContent
- Layout
- columns · rows · grid · panel · col · row · container
- Navigation
- menu · chat
- flintNight
- flintDay
- cyberpunk
- dracula
- nord
- monokai
- solarized
- gruvbox
- catppuccin
- tokyoNight
- rosePine
- hacker
← back ## Themes ──────────────────────────────────────────────────────────────────────────────────────────────────── ↑ more above ──────────────────────────────────────────────── = ──────────────────────────────────────────────── ╭────────────────────────────────────╮ │ ╭───────────────────────────╮ │ cyberpunk — neon green / magenta │ │ │ dracula — purple / teal │ ╰────────────────────────────────────╯ │ ╰───────────────────────────╯ ╭────────────────────────────╮ │ ╭─────────────────────────────────╮ │ nord — icy blues + greys │ │ │ monokai — warm reds + oranges │ ╰────────────────────────────╯ │ ╰─────────────────────────────────╯ ╭───────────────────────────────────╮ │ ╭──────────────────────────╮ │ solarized — muted, eye-friendly │ │ │ gruvbox — earthy retro │ ╰───────────────────────────────────╯ │ ╰──────────────────────────╯ ╭──────────────────────────────╮ │ ╭─────────────────────────────────╮ │ catppuccin — pastel mauves │ │ │ tokyoNight — deep blue + neon │ ╰──────────────────────────────╯ │ ╰─────────────────────────────────╯
The theme picker, live. Switching a theme re-colours every component; you do not restyle anything.
12 demos. One command each.
- Welcome Tour
npx terminaltui tryflintNight - Developer Portfolio
npx terminaltui demo developer-portfolioflintNight - Restaurant
npx terminaltui demo restaurantflintNight - Dashboard
npx terminaltui demo dashboardflintNight - Cinema
npx terminaltui demo cinemadracula - Server Dashboard
npx terminaltui demo server-dashboardflintNight - Mac Monitor
npx terminaltui demo mac-monitorflintNight - Startup
npx terminaltui demo startuptokyoNight - Conference
npx terminaltui demo conferenceflintNight - Band
npx terminaltui demo bandrosePine - Coffee Shop
npx terminaltui demo coffee-shopflintNight - Freelancer
npx terminaltui demo freelancercustom
← back * Menu ──────────────────────────────────────────────────────────────────────────────────────────────────── ▌╭─────────────────────────────────────────────────────────────────────────────────────────────────╮ ▌│ Search the menu... │ ▌╰─────────────────────────────────────────────────────────────────────────────────────────────────╯ Starters [Mains] [Desserts] [Cocktails] ─────────────────────────────────────────────────────────────────────────────────────────────── ╭────────────────────────────────────────────╮ │ ╭────────────────────────────────────────────╮ │ ◇ Burrata & Heirloom Tomato $16 │ │ │ ◇ Charred Octopus $19 │ │ Creamy burrata over vine-ripened heirloom │ │ │ Spanish octopus grilled over binchotan │ │ tomatoes with aged balsamic reduction, │ │ │ charcoal, served with fingerling potatoes, │ │ basil oil, and flaky Maldon sea salt. │ │ │ smoked paprika aioli, and pickled fresno │ │ │ │ │ chilis. │ │ [vegetarian] [gluten free] │ │ │ │ ╰────────────────────────────────────────────╯ │ │ [gluten free] │ │ ╰────────────────────────────────────────────╯ ╭────────────────────────────────────────────╮ │ │ ◇ Bone Marrow & Toast $17 │ │ ╭────────────────────────────────────────────╮ │ Roasted bone marrow with chimichurri, │ │ │ ◇ Wild Mushroom Soup $14 │ │ capers, shallot jam, and grilled sourdough │ │ │ A velvety blend of porcini, chanterelle, │ │ from our house bakery. │ │ │ and hen-of-the-woods mushrooms finished │ ╰────────────────────────────────────────────╯ │ │ with truffle cream and chive oil. Served │ │ │ with warm focaccia. │ ╭────────────────────────────────────────────╮ │ │ │ ↓ 1 item below ──────────────────────────────────────────────────────────────────────────────────────────────────── ↑↓ navigate ⏎ select ← back q quit [1/5]
restaurant demo, gruvbox theme — one of twelve, captured at 100×32.
Against the alternatives.
Ink and Bubble Tea are excellent and far more mature. The difference is shape: they give you pieces, terminaltui gives you a structure.
| Capability | terminaltui | Ink | Pastel | Bubble Tea |
|---|---|---|---|---|
| Language | TypeScript | TypeScript (React) | TypeScript (Ink-based) | Go |
| Shape | Framework — pages, routing, layouts | Component library | CLI command router | TUI framework (Elm-style) |
| File-based routing for screens | Yes | No | Routes CLI subcommands | No |
| SSH hosting | terminaltui serve | No | No | Via charmbracelet/wish |
| npx distribution | First-class | First-class | First-class | No — Go binary |
| Components included | 42 | Bring your own | Inherits from Ink | Via bubbles |
| Images in-terminal | Yes | No | No | No |
| AI codegen-native | Ships claude/SKILL.md | No | No | No |
4,223 tests across 68 suites. First published 23 Mar 2026.
Playwright, but the browser is a terminal.
Launch the app in a real PTY, send keypresses, assert on what is on screen. The emulator ships in the package.
Every terminal screen on this page was produced with it: boot the demo, drive it, dump the coloured cell grid. That is why they are exact.
import { TUIEmulator } from "terminaltui/emulator";
const app = await TUIEmulator.launch("dist/cli.js");
await app.press("j");
await app.waitForText("Projects");
app.screen.cells();What exists, and what does not.
- ShippedImages in the terminal
- Real PNG and JPEG, drawn as colored cells everywhere and as true pixels on kitty and Ghostty.
- ShippedHeadless terminal emulator
- Drive a real PTY from tests, assert on screen contents. Every screenshot on this site was produced with it.
- ShippedVideo rendering
- Prepacked video with transport controls, Kitty/Ghostty pixels, and a portable coloured-cell fallback.
Planned, not built
- A library you can ssh into
- Comic reader
- Agent manager
- Latency and throughput work
Engineering notes.
- Real pixels in a terminal that has noneDrawing a photograph inside a grid of characters, and why the obvious way to use the kitty graphics protocol was the wrong one.
- A question you cannot un-askHow terminaltui works out what your terminal can do, and why the detection ladder is built as a denylist that writes zero bytes.
- The font that spelled TERHINALTUIAn ASCII banner face drew M, V and W as H, U and H. It shipped, because the bug was only visible in the one place nobody reads carefully: the headline.
Write pages. Ship a terminal app.
MIT, Node >=18, 3 runtime dependencies. First published in March 2026, so it is young. The count below is live, not a badge. Read the source and decide for yourself.
npx terminaltui try