A framework for building beautiful, interactive terminal websites and apps. Write a config, get a TUI, distribute via npx.
npm install -g terminaltui # install
terminaltui init # create a new project
terminaltui dev # preview it
terminaltui build && npm publish # now anyone can: npx your-project-nameterminaltui create
# Answer a few questions → get a tailored AI prompt → paste into Claude Codecd ~/my-website
terminaltui convert
# paste the prompt into Claude Code — it reads your site and generates the TUI versionimport { defineSite, page, markdown, card, link } from "terminaltui";
export default defineSite({
name: "My Site",
theme: "dracula",
pages: [
page("home", {
title: "Home",
icon: "◆",
content: [
markdown("# Hello World\nWelcome to my terminal."),
card({ title: "My Project", body: "Something cool", tags: ["typescript"] }),
link("GitHub", "https://github.com/me"),
],
}),
],
});npx omar-musayevA real portfolio built with terminaltui — AI chat, blog posts with parameterized routes, interactive forms, and a custom orange-on-black theme.
| Demo | Run it | Theme |
|---|---|---|
| Developer Portfolio | terminaltui dev demos/developer-portfolio/site.config.ts |
cyberpunk |
| Restaurant | npx demo-tui-restaurant |
gruvbox |
| Coffee Shop | npx demo-tui-cafe |
catppuccin |
| Live Dashboard | terminaltui dev demos/dashboard/site.config.ts |
hacker |
| Startup Landing | terminaltui dev demos/startup/site.config.ts |
tokyoNight |
| Conference | terminaltui dev demos/conference/site.config.ts |
nord |
| Band Page | terminaltui dev demos/band/site.config.ts |
rosePine |
| Freelancer Studio | terminaltui dev demos/freelancer/site.config.ts |
custom |
| Tetris | npx tsx demos/tetris/index.ts |
cyberpunk |
Card, Timeline, Table, Hero, Gallery, Tabs, Accordion, Quote, Badge, ProgressBar, Link, List, Section, Divider, Image, and more.
TextInput, TextArea, Select, Checkbox, Toggle, RadioGroup, NumberInput, SearchInput, Button — with validation, submission, and notifications.
14 fonts, 15 scenes, 32 icons, 12 patterns, 9 shapes, 5 data visualizations. Image-to-ASCII conversion with braille mode.
cyberpunk, dracula, nord, monokai, solarized, gruvbox, catppuccin, tokyoNight, rosePine, hacker. Plus custom themes.
createState, computed, dynamic blocks, fetcher with auto-refresh, request HTTP client, WebSocket/SSE via liveData. Build real applications, not just static sites.
Define backend endpoints directly in your config — no separate server needed:
api: {
"GET /stats": async () => {
const uptime = execSync("uptime -p").toString().trim();
return { uptime, timestamp: Date.now() };
},
"POST /deploy": async (req) => {
execSync(`docker run -d ${(req.body as any).image}`);
return { success: true };
},
}Run shell commands, read files, query databases — anything Node can do. The framework starts a local server automatically. fetcher({ url: "/stats" }) just works. See API Routes docs for the full reference.
route("project", {
title: (params) => `Project: ${params.id}`,
content: async (params) => {
const data = await fetch(`/api/projects/${params.id}`).then(r => r.json());
return [card({ title: data.name, body: data.description })];
},
});const store = createPersistentState({
path: ".terminaltui/state.json",
defaults: { theme: "cyberpunk", favorites: [] },
});
// Survives app restartsterminaltui test --sizes --verboseHeadless TUI emulator — like Puppeteer for terminals. Test every page programmatically.
| Key | Action |
|---|---|
| ↑↓ / jk | Navigate between items |
| Enter / → | Select / activate |
| ← / Esc | Back |
| q | Quit |
| : | Command mode |
| 1-9 | Jump to page |
When focused on a text input, just start typing — it auto-enters edit mode. Press Escape to return to navigation.
- Getting Started
- API Routes
- Components
- Themes
- ASCII Art
- State & Data
- Routing & Middleware
- Testing
- CLI Reference
- Create Command
- TypeScript — fully typed with strict mode
- Zero dependencies — pure Node.js 18+
- 1,572 tests across 10 suites (
npm test) - Apple Terminal compatible — auto-detects and falls back to 256-color
terminaltui is a v1 framework — the API is ambitious and some features are foundational implementations that will deepen over time. Contributions welcome.
See CONTRIBUTING.md for setup instructions.