### Try the TerminalTUI tour

Source: https://github.com/omarmusayev/terminaltui/blob/main/index.html

Take a guided tour of the TerminalTUI framework without any installation required. This is a great way to get started.

```bash
npx terminaltui try
```

--------------------------------

### Start development server

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/cli-reference.md

Starts the development preview server. If API routes are defined, a local HTTP server starts automatically. It defaults to looking for config.ts and pages/ in the current directory, or can be pointed to a specific config file.

```bash
terminaltui dev [path]
```

--------------------------------

### GET /search?q=<query>&page=<page>

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/api-routes.md

Example of a GET endpoint for searching resources, with support for query parameters for search terms and pagination.

```APIDOC
## GET /search

### Description
This endpoint facilitates searching for resources. It accepts query parameters for the search term and the desired page number.

### Method
GET

### Endpoint
/search

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query string.
- **page** (number) - Optional - The page number for pagination.

### Response
#### Success Response (200)
- **query** (string) - The search query received.
- **page** (string) - The page number received.

### Response Example
{
  "query": "hello",
  "page": "2"
}
```

--------------------------------

### GET /api/hello

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/api-routes.md

A simple example of a GET endpoint that returns a greeting message.

```APIDOC
## GET /api/hello

### Description
This endpoint serves as a basic example, returning a "Hello from the API!" message.

### Method
GET

### Endpoint
/api/hello

### Response
#### Success Response (200)
- **message** (string) - A greeting message from the API.

### Response Example
{
  "message": "Hello from the API!"
}
```

--------------------------------

### Run a built-in TerminalTUI demo

Source: https://github.com/omarmusayev/terminaltui/blob/main/README.md

This command allows you to try out a pre-built demo application without any installation or project setup. It's a quick way to experience TerminalTUI's capabilities.

```bash
npx terminaltui demo restaurant
```

--------------------------------

### API Route Handler Example (GET)

Source: https://github.com/omarmusayev/terminaltui/blob/main/index.html

API routes are defined in the `api/` directory. This example shows how to export a `GET()` function to handle GET requests for an API endpoint.

```typescript
export function GET() {
  // Handle GET request
}
```

--------------------------------

### API Route Handler Example (GET with Query)

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Defines a GET API endpoint at `/api/search` that accepts query parameters `q` and `page` and returns them in the response.

```typescript
// api/search.ts → GET /api/search?q=hello&page=2
export async function GET(req) {
  return { query: req.query.q, page: req.query.page };
}
```

--------------------------------

### Run Development Server

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/prompt.md

Navigate to the tui/ directory and run this command to start the development server for testing.

```bash
cd tui
npm run dev
```

--------------------------------

### Example Usage of fetcher

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Demonstrates how to initialize the `fetcher` with a URL and configure auto-refresh and retry options.

```typescript
const api = fetcher({ url: "https://api.example.com/data", refreshInterval: 30000, retry: 3 });
```

--------------------------------

### Install TUI Dependencies

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/prompt.md

Navigate into the 'tui' directory and install the project dependencies using npm.

```bash
cd tui && npm install
```

--------------------------------

### Run mac-monitor

Source: https://github.com/omarmusayev/terminaltui/blob/main/demos/mac-monitor/README.md

Install and run mac-monitor directly using npx. No additional setup or configuration is required.

```bash
npx mac-monitor
```

--------------------------------

### Initialize a new project

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/cli-reference.md

Scaffolds a new project from a template. If no template is specified, an interactive prompt will guide the user.

```bash
terminaltui init [template]
```

--------------------------------

### Creating a CardBlock

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Example of how to instantiate and configure a CardBlock with various properties.

```typescript
card({
  title: "My Project",
  subtitle: "★ 200",
  body: "A brief description.",
  tags: ["TypeScript", "Open Source"],
  url: "https://github.com/user/repo",
  action: { navigate: "project", params: { name: "my-project" } },
})
```

--------------------------------

### API Route Handler Example (GET)

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Defines a simple GET API endpoint at `/api/stats` that returns the server's uptime and current timestamp.

```typescript
// api/stats.ts → GET /api/stats
export async function GET() {
  return { uptime: process.uptime(), timestamp: Date.now() };
}
```

--------------------------------

### Run Server Dashboard Demo

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/layouts.md

Execute this command to run the server-dashboard demo, which serves as a comprehensive example of layout usage.

```bash
npx terminaltui demo server-dashboard
```

--------------------------------

### Basic Response Example

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/api-routes.md

Illustrates how to return a JSON-serializable value for a GET request, which will be sent as application/json with a 200 status.

```typescript
"GET /data": async () => {
  return { items: [1, 2, 3], total: 3 };
},
```

--------------------------------

### Home Page Example

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/getting-started.md

An example of a home page component for a terminaltui site. It demonstrates rendering markdown content and a card component.

```typescript
// pages/home.ts
import { card, markdown } from "terminaltui";

export const metadata = { label: "Home", icon: "◆" };

export default function Home() {
  return [
    markdown("Hello world!"),
    card({ title: "Welcome", body: "This is your first terminal app." }),
  ];
}
```

--------------------------------

### API Route: Get Uptime

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Example of an API route that executes a shell command to get the system uptime. Requires the `child_process` module.

```typescript
// api/uptime.ts
import { execSync } from "child_process";

export async function GET() {
  return { uptime: execSync("uptime -p").toString().trim() };
}
```

--------------------------------

### Example Usage of request and shorthand methods

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Shows how to make HTTP requests using the `request` function and its shorthand methods for common HTTP verbs. The last example demonstrates passing headers as a flat object.

```typescript
const res = await request({ url: "https://api.example.com/data", method: "POST", body: { name: "test" } });
// Shorthand methods:
const res = await request.get("https://api.example.com/data");
const res = await request.post("https://api.example.com/data", { name: "test" });
const res = await request.put("https://api.example.com/data/1", { name: "updated" });
const res = await request.delete("https://api.example.com/data/1");
const res = await request.patch("https://api.example.com/data/1", { name: "patched" });
// Third arg is a flat headers object (not { headers: {...} }):
const res = await request.post("https://api.example.com/data", { name: "test" }, { Authorization: "Bearer sk-..." });
```

--------------------------------

### Columns Layout Example

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Example of creating side-by-side panels using the `columns` and `panel` layout components.

```ts
columns([
  panel({ width: "60%", content: [
    table(["Name", "Status"], [["nginx", "running"], ["postgres", "running"]]),
  ]}),
  panel({ width: "40%", content: [
    markdown("## Stats"),
    progressBar("CPU", 45),
    progressBar("Memory", 72),
  ]}),
])
```

--------------------------------

### Project Structure Overview

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/getting-started.md

An example of the file structure created by `terminaltui init`. It includes configuration, pages, and optional API directories.

```text
my-site/
  config.ts          # theme, banner, global settings
  pages/
    home.ts          # the landing page
    about.ts         # /about
    ...
  api/               # optional — file-based HTTP routes
  package.json       # must have "type": "module"
  tsconfig.json
```

--------------------------------

### Complete TUIEmulator Test Example

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/testing.md

A comprehensive example demonstrating a full testing workflow with TUIEmulator, including launching, waiting, navigating, asserting, and cleanup.

```typescript
import { TUIEmulator } from "terminaltui/emulator";

async function testSite() {
  const emu = await TUIEmulator.launch({
    command: "terminaltui dev",
    cwd: "./my-site",
    cols: 80,
    rows: 24,
  });

  try {
    await emu.waitForBoot();

    // Verify home page loaded
    emu.assert.textVisible("Home");
    emu.assert.noOverflow();

    // Navigate to About page
    await emu.press("down");
    await emu.press("enter");
    await emu.waitForText("About");
    emu.assert.textVisible("About");

    // Check that cards rendered
    const cards = emu.screen.cards();
    if (cards.length === 0) throw new Error("No cards found on About page");

    // Navigate back
    await emu.press("escape");
    await emu.waitForText("Home");

    // Test search input
    await emu.navigateTo("Search");
    await emu.waitForText("Search");
    await emu.press("enter");
    await emu.type("projects");
    await emu.waitForText("Projects");

    console.log("All tests passed.");
  } finally {
    await emu.close();
  }
}

testSite();
```

--------------------------------

### Start Development Preview

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/getting-started.md

Compile and launch an interactive terminal preview of your terminaltui project. This command is used during development to test changes.

```bash
npx terminaltui dev
```

--------------------------------

### Install node-pty

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/testing.md

Install node-pty as a peer dependency for TUIEmulator.

```bash
npm install node-pty
```

--------------------------------

### API Route Handler Example (POST)

Source: https://github.com/omarmusayev/terminaltui/blob/main/index.html

This example demonstrates exporting a `POST()` function to handle POST requests for an API endpoint.

```typescript
export function POST() {
  // Handle POST request
}
```

--------------------------------

### Start Development Preview with Specific Config

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/getting-started.md

Launch the development preview for a terminaltui project using a specific configuration file. Useful when you have multiple configurations.

```bash
npx terminaltui dev path/to/config.ts
```

--------------------------------

### Instantiate Chat Widget

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Example of how to create and configure a chat widget instance with specific settings for endpoint, prompts, and history.

```typescript
chat({
  id: "ai-chat",
  endpoint: "/api/chat",
  placeholder: "Ask a question...",
  suggestedQuestions: ["What do you do?", "Tell me about projects"],
  systemPrompt: "You are a helpful assistant.",
  maxHistory: 50,
})
```

--------------------------------

### Dynamic Route Example

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Example of a dynamic route page file. Parameters are passed to the default export function. Metadata can be used to control visibility.

```typescript
// pages/projects/[slug].ts
export const metadata = { hidden: true };

export default async function Project({ params }: { params: { slug: string } }) {
  const data = await fetchProject(params.slug);
  return [card({ title: data.name, body: data.description })];
}
```

--------------------------------

### Print Installed Version

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/cli-reference.md

Print the installed version of TerminalTUI. This can be invoked using the 'version' subcommand or the '--version' or '-v' flags.

```bash
terminaltui version
```

```bash
terminaltui --version
```

```bash
terminaltui -v
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/omarmusayev/terminaltui/blob/main/CONTRIBUTING.md

Clone the terminaltui repository and install its npm dependencies to set up your development environment.

```bash
git clone https://github.com/OmarMusayev/terminaltui.git
cd terminaltui
npm install
```

--------------------------------

### Install TerminalTUI

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/getting-started.md

Install the terminaltui package globally using npm. This command is used for setting up the development environment.

```bash
npm install terminaltui
```

--------------------------------

### Width Cascade Example

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Illustrates how terminal width is translated into component content width through various rendering stages.

```text
Terminal width (e.g. 120 cols)
  -> createRenderContext(): ctx.width = Math.min(terminalWidth, 100)
    -> renderContentPage(): blockWidth = ctx.width - 1 (focus prefix)
      -> Component gets blockWidth as ctx.width
        -> dims = computeBoxDimensions(ctx.width, COMPONENT_DEFAULTS.componentType)
          -> Text wraps at dims.content
          -> Child blocks receive dims.content as their width
```

--------------------------------

### Creating a TimelineBlock

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Example of how to create a vertical timeline with multiple entries.

```typescript
timeline([
  { title: "Senior Engineer", subtitle: "Acme Corp", period: "2023 — present", description: "Leading platform team" },
  { title: "BS Computer Science", subtitle: "University", period: "2017 — 2021" },
])
```

--------------------------------

### Creating a HeroBlock

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Example of a hero section with a title, subtitle, and call-to-action.

```typescript
hero({ title: "Welcome", subtitle: "Build terminal apps.", cta: { label: "Get Started →", url: "https://..." } })
```

--------------------------------

### Serve with Explicit Config Path

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/serve.md

Starts the terminaltui SSH server and specifies a custom path to the configuration file.

```bash
terminaltui serve path/to/config.ts
```

--------------------------------

### Theme Configuration Example

Source: https://github.com/omarmusayev/terminaltui/blob/main/README.md

Sets the theme for the terminal UI site to 'dracula'.

```typescript
export default defineConfig({ theme: "dracula" });
```

--------------------------------

### Applying a Custom Theme

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Example of how to define and apply a custom theme object with specific color values.

```typescript
theme: {
  accent: "#e06c75", accentDim: "#be5046", text: "#abb2bf", muted: "#5c6370",
  subtle: "#3e4452", success: "#98c379", warning: "#e5c07b", error: "#e06c75",
  border: "#5c6370", bg: "#282c34",
}
```

--------------------------------

### Basic terminaltui home page

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

An example of a simple home page for a terminaltui application. It displays 'Hello world!' using markdown.

```typescript
import { markdown } from "terminaltui";

export const metadata = { label: "Home", icon: "◆" };

export default function Home() {
  return [markdown("Hello world!")];
}
```

--------------------------------

### Initialize Project with Template

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/getting-started.md

Scaffold a new terminaltui project from a predefined template. Use this command to quickly set up a project structure.

```bash
npx terminaltui init [template]
```

--------------------------------

### Default Project Configuration

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Example of how to export a default configuration object from `config.ts`. Includes basic site settings and lifecycle hooks.

```typescript
// config.ts
export default defineConfig({
  name: "My Site",
  handle: "@me",
  tagline: "a cool terminal site",
  banner: ascii("My Site", { font: "ANSI Shadow", gradient: ["#ff6b6b", "#4ecdc4"] }),
  theme: "dracula",
  borders: "rounded",
  animations: { boot: true, exitMessage: "Goodbye!", speed: "normal" },
  middleware: [requireEnv(["API_KEY"])],
  onInit: async (app) => { /* setup */ },
  onError: (err, ctx) => [markdown(`Error: ${err.message}`)],
});
```

--------------------------------

### Serve terminaltui App via SSH

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Start a terminaltui application for SSH hosting. Connect to the running application using an SSH client.

```bash
terminaltui serve --port 2222
# Then from any machine:
ssh localhost -p 2222
```

--------------------------------

### Radio Group Example

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Creates a radio group for selecting a subscription plan, with predefined options and a default value set to 'free'.

```typescript
radioGroup({
  id: "plan",
  label: "Select Plan",
  options: [{ label: "Free", value: "free" }, { label: "Pro", value: "pro" }],
  defaultValue: "free",
  onChange: (val) => console.log("Plan:", val),
})
```

--------------------------------

### API Route for GET Request

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/prompt.md

Example of an API route handler for a GET request in 'tui/api/stats.ts'. It returns a JSON object with visitor statistics.

```typescript
// tui/api/stats.ts → GET /api/stats
export async function GET() {
  return { visitors: 1234 };
}
```

--------------------------------

### Start TerminalTUI Development Server

Source: https://github.com/omarmusayev/terminaltui/blob/main/index.html

Launch the development server for a TerminalTUI application. This command is used to serve and test your terminal application locally during development.

```bash
terminaltui dev
```

--------------------------------

### Editor with Preview Layout

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/layouts.md

Example of using columns to create an editor pane alongside a preview pane. Useful for development tools.

```typescript
columns([panel({ width: "30%" }), panel({ width: "70%" })])
```

--------------------------------

### API Route Handler for GET

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Defines a GET request handler for an API route. This example fetches statistics like revenue and user count.

```typescript
export async function GET() {
  return { revenue: "$1.2M", users: 45231 };
}
```

--------------------------------

### 12-Column Grid System Setup

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Demonstrates how to import and use the `row`, `col`, and `container` components for creating responsive layouts. Configure spans, responsive breakpoints, and gaps between columns.

```typescript
import { row, col, container } from "terminaltui";

// Basic: 2 equal columns (span:6 each = 50%)
row([
  col([card({ title: "Left" })], { span: 6 }),
  col([card({ title: "Right" })], { span: 6 }),
])

// 3-column layout: sidebar + main + aside
row([
  col([menu], { span: 3 }),         // 25%
  col([mainContent], { span: 6 }),   // 50%
  col([aside], { span: 3 }),         // 25%
])

// Responsive — cards reflow based on terminal width
row([
  col([card1], { span: 4, sm: 6, xs: 12 }),  // 33% wide, 50% medium, full narrow
  col([card2], { span: 4, sm: 6, xs: 12 }),
  col([card3], { span: 4, sm: 12, xs: 12 }),
], { gap: 1 })

// Container — centers content with max width
container([
  row([
    col([hero(...)], { span: 12 }),    // full width
  ]),
  row([
    col([sidebar], { span: 3 }),
    col([content], { span: 9 }),
  ]),
], { maxWidth: 100, padding: 2 })
```

--------------------------------

### Run Live Portfolio Demo

Source: https://github.com/omarmusayev/terminaltui/blob/main/README.md

Execute a command to run a live portfolio demo built with terminaltui. This is a quick way to see the framework in action.

```bash
npx omar-musayev
```

--------------------------------

### API Route Handler Example (GET with Params)

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Defines a dynamic GET API endpoint at `/api/items/:id` that captures the ID from the URL parameters and returns it along with a generated name.

```typescript
// api/items/[id].ts → GET /api/items/:id
export async function GET(req) {
  return { id: req.params.id, name: `Item ${req.params.id}` };
}
```

--------------------------------

### TerminalTUI Navigation Examples

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/prompt.md

Demonstrates two methods for navigating between pages in TerminalTUI: declaratively using card actions and programmatically within event handlers.

```typescript
// Declarative (on cards):
card({ title: "Read More", action: { navigate: "blog-1" } })

// Programmatic (in event handlers):
import { navigate } from "terminaltui";
button({ label: "Go", onPress: () => navigate("blog-1") })
```

--------------------------------

### Run Demos from Source

Source: https://github.com/omarmusayev/terminaltui/blob/main/CONTRIBUTING.md

Execute demo applications directly from the source code using npx and tsx.

```bash
npx tsx src/cli/index.ts dev demos/developer-portfolio/site.config.ts
```

```bash
npx tsx src/cli/index.ts dev demos/developer-portfolio/config.ts   # file-based variant
```

--------------------------------

### Serve TUI over SSH

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/cli-reference.md

Hosts the TUI over SSH, allowing network connections without installation. Each connection gets an independent session. Optional peer dependency: ssh2.

```bash
terminaltui serve [path] [options]
```

--------------------------------

### WebSocket Live Data Connection Example

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Demonstrates setting up a real-time data connection using WebSockets with options for message handling, connection events, and automatic reconnection.

```typescript
// WebSocket
const ws = liveData({
  type: "websocket",
  url: "wss://api.example.com/ws",
  onMessage: (data) => { /* handle message */ },
  onConnect: () => console.log("Connected"),
  onDisconnect: () => console.log("Disconnected"),
  onError: (err) => console.error(err),
  reconnect: true,                               // Auto-reconnect (default: false)
  reconnectInterval: 5000,
  protocols: [],
});
```

--------------------------------

### Define a Simple GET API Route

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/api-routes.md

Create a GET endpoint by exporting an async function named GET in a `.ts` file within the `api/` directory. The file path determines the URL.

```typescript
// api/hello.ts 
export async function GET() {
  return { message: "Hello from the API!" };
}
```

--------------------------------

### Convert existing project for AI

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/cli-reference.md

Copies necessary reference documentation files into the current directory for AI-assisted website conversion. This prepares the project for conversion into a TUI format.

```bash
terminaltui convert
```

--------------------------------

### Create a new project interactively

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/cli-reference.md

Launches an interactive prompt builder for creating new projects. It asks a series of questions to generate a tailored AI prompt for scaffolding.

```bash
terminaltui create
```

--------------------------------

### Initialize a new TerminalTUI project

Source: https://github.com/omarmusayev/terminaltui/blob/main/index.html

Scaffold a new project using the terminaltui init command. This command sets up a new project from a template.

```bash
npx terminaltui init my-site
```

--------------------------------

### Initialize a new TerminalTUI project

Source: https://github.com/omarmusayev/terminaltui/blob/main/README.md

Use this command to create a new TerminalTUI project in the specified directory. After initialization, navigate into the project directory and start the development server.

```bash
npx terminaltui init my-site
cd my-site
npx terminaltui dev
```

--------------------------------

### API GET Endpoint

Source: https://github.com/omarmusayev/terminaltui/blob/main/index.html

Defines a GET endpoint for an API route that returns statistics such as users, uptime, and requests.

```typescript
// api/stats.ts becomes GET /api/stats

export async function GET() {
  return {
    users:     45_231,
    uptime:    99.97,
    requests:  1_284_512,
  };
}
```

--------------------------------

### GET /api/stats

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

This API route retrieves statistics, such as revenue and user count. It is defined by exporting an async GET function in `api/stats.ts`.

```APIDOC
## GET /api/stats

### Description
Retrieves site statistics like total revenue and user count.

### Method
GET

### Endpoint
/api/stats

### Response
#### Success Response (200)
- **revenue** (string) - The total revenue.
- **users** (number) - The total number of users.

#### Response Example
{
  "revenue": "$1.2M",
  "users": 45231
}
```

--------------------------------

### Running TerminalTUI Demos

Source: https://github.com/omarmusayev/terminaltui/blob/main/llms.txt

Execute built-in demos directly using npx, specifying the demo name and optionally a theme.

```bash
npx terminaltui demo developer-portfolio
```

```bash
npx terminaltui demo restaurant
```

```bash
npx terminaltui demo dashboard
```

```bash
npx terminaltui demo server-dashboard
```

```bash
npx terminaltui demo startup
```

```bash
npx terminaltui demo conference
```

```bash
npx terminaltui demo band
```

```bash
npx terminaltui demo coffee-shop
```

```bash
npx terminaltui demo freelancer
```

--------------------------------

### Start SSH Server

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/serve.md

Starts the terminaltui SSH server on a specified port. This command is used to make your terminaltui app accessible via SSH.

```bash
terminaltui serve --port 2222
```

--------------------------------

### Quick Start SSH Server

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/serve.md

Launches the terminaltui SSH server with default settings. It will listen on the default port 2222 and auto-generate a host key if one doesn't exist.

```bash
terminaltui serve
# → SSH server listening on :2222
# → Host key: .terminaltui/host_key (auto-generated as Ed25519)
```

--------------------------------

### Create Project with AI Assistance

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/getting-started.md

Initiate a new terminaltui project by describing your desired features to an AI. This command leverages AI to build the project based on your input.

```bash
npx terminaltui create
```

--------------------------------

### Server-Sent Events (SSE) Live Data Connection Example

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Shows how to establish a real-time data connection using Server-Sent Events, including URL and header configuration, and message handling.

```typescript
// SSE
const sse = liveData({
  type: "sse",
  url: "https://api.example.com/events",
  onMessage: (event) => { /* event.data, event.type, event.lastEventId */ },
  headers: { Authorization: "Bearer ..." },
});
```

--------------------------------

### Nested Layout Example

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/layouts.md

Demonstrates composing layout components to create complex UIs. This example nests columns, rows, and panels with markdown and tables.

```typescript
columns([
  { width: "25%", title: "Nav", content: [
    link("Dashboard", "#"),
    link("Logs", "#"),
    link("Settings", "#"),
  ]},
  { width: "75%", content: [
    rows([
      { height: "60%", content: [
        markdown("## Main Content"),
        table(["Name", "Status"], [["nginx", "running"]]),
      ]},
      { height: "40%", title: "Logs", content: [
        markdown("Log output here..."),
      ]},
    ]),
  ]},
])
```

--------------------------------

### Run a built-in demo

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/cli-reference.md

Executes a pre-packaged demo from the published terminaltui package. Demos are compiled on the fly using esbuild.

```bash
terminaltui demo <name>
```

--------------------------------

### API Route Handler for Dynamic GET

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Handles GET requests for dynamic routes, such as /api/projects/:id. It extracts the ID from the route parameters to find a specific project.

```typescript
export async function GET({ params }: { params: { id: string } }) {
  return projects.find(p => p.id === params.id) ?? { error: "Not found" };
}
```

--------------------------------

### Generating a Pre-made ASCII Art Scene

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Example of generating a decorative ASCII art scene using the `asciiArt.scene()` function. This example generates a 'mountains' scene with a specified width.

```typescript
const art = asciiArt.scene("mountains", { width: 60 });
```

--------------------------------

### Convert Existing Site Command

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/getting-started.md

Navigate to your existing website's directory and run the convert command to prepare it for AI-assisted conversion to a terminaltui application.

```bash
cd your-existing-site
npx terminaltui convert
```

--------------------------------

### Creating a QuoteBlock

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Example of a block quote with text and attribution.

```typescript
quote("The best way to predict the future is to invent it.", "— Alan Kay")
```

--------------------------------

### Development Build Commands

Source: https://github.com/omarmusayev/terminaltui/blob/main/CONTRIBUTING.md

Commands for type-checking, building the project, and running a development server with watch mode.

```bash
npm run typecheck        # type-check without emitting
npm run build            # full bundle to dist/ (tsup + bundle-demos)
npm run dev              # tsup --watch on src/index.ts
```

--------------------------------

### Run Built-in TerminalTUI Demos

Source: https://github.com/omarmusayev/terminaltui/blob/main/README.md

Execute any of the pre-built terminaltui demos directly using npx. Some demos may have platform-specific requirements, like the macOS-only system monitor.

```bash
npx terminaltui demo restaurant
npx terminaltui demo dashboard
npx terminaltui demo band
npx terminaltui demo coffee-shop
npx terminaltui demo conference
npx terminaltui demo developer-portfolio
npx terminaltui demo freelancer
npx terminaltui demo startup
npx terminaltui demo server-dashboard
npx terminaltui demo mac-monitor   # macOS only — live system stats
```

--------------------------------

### POST /api/users

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/api-routes.md

Example of a POST endpoint for creating or adding user data.

```APIDOC
## POST /api/users

### Description
This endpoint is designed to handle POST requests, typically used for creating new user resources or submitting user-related data.

### Method
POST

### Endpoint
/api/users

### Parameters
#### Request Body
- **req** (object) - The request object, which may contain user data for creation or submission.

### Response
#### Success Response (200)
- (Details not specified in source, but typically returns created resource or success status)

### Request Example
(Request body structure not specified in source)
```

--------------------------------

### Static Page Example with Metadata

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/routing.md

Defines a static page (`/about`) with optional metadata for menu configuration. The default export returns an array of content blocks.

```typescript
// pages/about.ts
import { card, timeline } from "terminaltui";

export const metadata = {
  label: "About",       // menu label (defaults to title-cased filename)
  icon: "◈",
  order: 2,             // menu sort order (lower first)
  hidden: false,        // hide from auto-generated menu
};

export default function About() {
  return [
    card({ title: "About Me", body: "Full-stack developer." }),
    timeline([{ date: "2024", title: "Started terminaltui" }]),
  ];
}
```

--------------------------------

### API Route Handler Example (POST)

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Defines a POST API endpoint at `/api/deploy` that expects a JSON body containing `image` and `name`, and returns a success message.

```typescript
// api/deploy.ts → POST /api/deploy
export async function POST(req) {
  const { image, name } = req.body as any;
  return { success: true, message: `Deployed ${name}` };
}
```

--------------------------------

### About Page Component

Source: https://github.com/omarmusayev/terminaltui/blob/main/README.md

Example of creating an 'About' page using card and timeline components.

```typescript
import { card, timeline } from "terminaltui";

export const metadata = { label: "About", icon: "?" };

export default function About() {
  return [
    card({ title: "About Me", body: "Full-stack developer based in Portland." }),
    timeline([
      { date: "2024", title: "Started terminaltui" },
      { date: "2023", title: "Joined Acme Corp" },
    ]),
  ];
}
```

--------------------------------

### PUT /api/items/[id]

Source: https://github.com/omarmusayev/terminaltui/blob/main/docs/api-routes.md

Example of a PUT endpoint for updating a specific item identified by its ID.

```APIDOC
## PUT /api/items/:id

### Description
This endpoint handles PUT requests to update a specific item. The item is identified by an ID present in the URL path.

### Method
PUT

### Endpoint
/api/items/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the item to be updated.
#### Request Body
- **req** (object) - The request object, which may contain the updated data for the item.

### Response
#### Success Response (200)
- (Details not specified in source, but typically returns the updated resource or success status)

### Request Example
(Request body structure not specified in source)
```

--------------------------------

### Using API Routes with fetcher/request

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Illustrates how to use the `fetcher` and `request` utilities to interact with API routes, including auto-refreshing data and imperative POST requests.

```APIDOC
## Using API Routes with fetcher/request

Relative URLs in `fetcher()`, `request.*()`, and `liveData()` auto-resolve to the local API server:

```ts
// In a dynamic block — fetcher with auto-refresh
dynamic(["stats"], () => {
  const data = fetcher({ url: "/stats", refreshInterval: 5000 });
  if (data.loading) return markdown("Loading...");
  if (data.error) return markdown(`Error: ${data.error.message}`);
  return markdown(`Uptime: ${data.data.uptime}`);
}),

// In a form onSubmit — imperative POST
form({
  id: "deploy",
  onSubmit: async (data) => {
    const res = await request.post("/deploy", { image: data.image });
    if (res.ok) return { success: "Deployed!" };
    return { error: (res.data as any)?.error || "Deploy failed" };
  },
  fields: [
    textInput({ id: "image", label: "Docker Image" }),
    button({ label: "Deploy", style: "primary" }),
  ],
}),
```
```

--------------------------------

### GET /api/projects/:id

Source: https://github.com/omarmusayev/terminaltui/blob/main/claude/SKILL.md

Retrieves a specific project by its ID. This is a dynamic route, where ':id' is a path parameter.

```APIDOC
## GET /api/projects/:id

### Description
Retrieves a specific project based on its unique identifier.

### Method
GET

### Endpoint
/api/projects/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the project.

### Response
#### Success Response (200)
- **(project object or error)** - Returns the project details if found, or an error object if not.

#### Response Example
{
  "id": "123",
  "name": "Example Project",
  "description": "This is a sample project."
}

#### Error Response (e.g., 404 Not Found)
{
  "error": "Not found"
}
```

--------------------------------

### API Route Definition

Source: https://github.com/omarmusayev/terminaltui/blob/main/README.md

Defines a GET endpoint for '/api/stats' that returns user count and uptime data.

```typescript
// api/stats.ts
export async function GET() {
  return { users: 45231, uptime: 99.97 };
}
```