### Install Setup Wizard Components

Source: https://github.com/arindam200/termui/blob/main/skills/cli-creator/references/patterns.md

Use this command to add the necessary components for building a setup wizard with TermUI.

```bash
npx termui add setup-flow text-input select multi-select spinner
```

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

### TermUI First-time Setup

Source: https://github.com/arindam200/termui/blob/main/README.md

Steps for cloning the repository, installing dependencies, and building the core package.

```bash
git clone https://github.com/Arindam200/termui.git
cd termui
pnpm install

# Build core first — other packages depend on it
pnpm --filter @termui/core build

pnpm test
```

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

### Install Dependencies and Build Core

Source: https://github.com/arindam200/termui/blob/main/CONTRIBUTING.md

Steps to clone the repository, install dependencies using pnpm, build the core package, and run all tests to ensure a working setup.

```bash
git clone https://github.com/<your-username>/termui.git
cd termui

pnpm install

pnpm --filter @termui/core build

pnpm test
```

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

### Install and Run TermUI AI Assistant

Source: https://github.com/arindam200/termui/blob/main/templates/ai-assistant/README.md

Installs project dependencies and starts the development server for the AI chat CLI.

```bash
npm install
npm run dev
```

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

### Install TermUI Components for Login Flow

Source: https://github.com/arindam200/termui/blob/main/skills/cli-creator/references/patterns.md

Installs necessary TermUI components for building login and setup flows, including input fields, spinners, and alerts.

```bash
npx termui add login-flow text-input password-input setup-flow spinner alert
```

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

### Install Community Components

Source: https://github.com/arindam200/termui/blob/main/CONTRIBUTING_COMPONENTS.md

Command to install a published component from the community registry.

```bash
npx termui add @your-handle/my-component
```

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

### Install termui Components

Source: https://github.com/arindam200/termui/blob/main/skills/cli-creator/references/patterns.md

Installs necessary components for building a data browser UI with termui.

```bash
npx termui add app-shell search-input table alert spinner
```

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

### Install and Initialize TermUI Project

Source: https://github.com/arindam200/termui/blob/main/skills/cli-creator/SKILL.md

Commands to set up a new TermUI project, install dependencies, initialize configuration, add specific components, and run the development server.

```bash
cd <project-name>
npm install
npx termui init                     # sets up termui.config.json
npx termui add <component-list>     # install exactly the components you're using
npm run dev                         # run with tsx (hot-reloading)
```

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

### Start TermUI MCP Server

Source: https://github.com/arindam200/termui/blob/main/README.md

Provides commands to start the Model Context Protocol (MCP) server directly using stdio transport or to install the MCP configuration for AI tools.

```bash
# Start the server directly (stdio transport)
npx termui mcp

# Or install the config for your AI tool
npx termui add mcp
```

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

### Implement SetupFlow

Source: https://github.com/arindam200/termui/blob/main/skills/termui/references/components.md

Displays a sequential step-by-step setup process with status indicators.

```tsx
<SetupFlow>
  <SetupFlow.Badge variant="success">v2.0</SetupFlow.Badge>
  <SetupFlow.Step label="Check Node.js version" status="done" />
  <SetupFlow.Step label="Install dependencies" status="active">
    <SetupFlow.Spinner label="npm install…" />
  </SetupFlow.Step>
  <SetupFlow.Step label="Configure project" status="pending" />
</SetupFlow>
// status: 'done'|'active'|'pending'|'error'
```

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

### Install TermUI Components

Source: https://github.com/arindam200/termui/blob/main/skills/cli-creator/references/patterns.md

Use this command to install the necessary TermUI components for building a dashboard.

```bash
npx termui add app-shell tabs bar-chart gauge sparkline spinner status-message
```

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

### SetupFlow Component

Source: https://github.com/arindam200/termui/blob/main/docs/templates.md

A step-by-step setup wizard component for CLI applications.

```APIDOC
## SetupFlow

### Description
A step-by-step setup wizard with connectors between steps, animated spinners, status icons per step, and a multi-select checklist.

### Parameters
#### Props
- **children** (ReactNode) - Required - The content of the setup flow.
- **title** (string) - Optional - The title of the setup flow.
- **titleFont** (BigTextFont) - Optional - The font style for the title (default: 'block').
- **titleColor** (string) - Optional - The color of the title (default: '#888888').
- **connectorChar** (string) - Optional - The character used for connectors (default: '│').
- **connectorColor** (string) - Optional - The color of the connector (default: theme muted).
```

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

### Add WelcomeScreen Component

Source: https://github.com/arindam200/termui/blob/main/docs/templates.md

Install the WelcomeScreen component using the termui CLI.

```sh
npx termui add welcome-screen
```

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

### Full Example: Counter Component Test

Source: https://github.com/arindam200/termui/blob/main/docs/api/testing.md

An example demonstrating how to use TermUI's testing utilities to test a 'Counter' component. It includes setup with Vitest, creating a renderer, and asserting the initial count.

```tsx
import { describe, it, expect, afterEach } from 'vitest';
import React, { useState } from 'react';
import { Text } from 'ink';
import { createTestRenderer, screen, fireEvent, waitFor } from 'termui/testing';

describe('Counter', () => {
  const { render, cleanup } = createTestRenderer();
  afterEach(cleanup);

  it('renders initial count', async () => {
    const result = render(<Counter initialCount={0} />);
    await new Promise((r) => setTimeout(r, 50));
    expect(screen.hasText('Count: 0', result.output)).toBe(true);
  });
});
```

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

### Install simple-git

Source: https://github.com/arindam200/termui/blob/main/docs/adapters.md

Install the simple-git package as a peer dependency for the termui/git library.

```sh
npm install simple-git
```

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

### Install AI Adapter Hooks

Source: https://github.com/arindam200/termui/blob/main/docs/ai.md

Commands to install the core termui package and necessary provider SDKs.

```sh
npm install termui
# plus at least one provider SDK
npm install @anthropic-ai/sdk   # for Anthropic
npm install openai               # for OpenAI
# Ollama needs no extra SDK — it uses fetch
```

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

### List Available Components

Source: https://github.com/arindam200/termui/blob/main/docs/api/cli.md

List all available components in the registry along with their installation status in your project.

```sh
npx termui list
```

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

### Install termui CLI

Source: https://github.com/arindam200/termui/blob/main/docs/templates.md

Use this command to install the termui CLI tool, which may be required for certain functionalities or project setups.

```sh
npx termui add help-screen
```

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

### Install TermUI Components for Log Viewer

Source: https://github.com/arindam200/termui/blob/main/skills/cli-creator/references/patterns.md

Install the necessary TermUI components for building a log viewer or event feed.

```bash
npx termui add app-shell log status-message badge spinner
```

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

### Start Interactive Demo App

Source: https://github.com/arindam200/termui/blob/main/README.md

Run the interactive demo application using pnpm.

```bash
pnpm --filter @termui/demo start
```

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

### Install Anthropic AI SDK

Source: https://github.com/arindam200/termui/blob/main/templates/ai-assistant/README.md

Installs the necessary SDK for integrating Anthropic's Claude models.

```bash
npm install @anthropic-ai/sdk
```

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

### Keyboard Navigation Example

Source: https://github.com/arindam200/termui/blob/main/docs/api/hooks.md

Example of using the useKeyboardNavigation hook to manage active item selection in a list.

```tsx
function MyMenu({ items }: { items: string[] }) {
  const { activeIndex } = useKeyboardNavigation({
    itemCount: items.length,
    onSelect: (i) => console.log('selected:', items[i]),
    onDismiss: () => setOpen(false),
  });

  return (
    <Box flexDirection="column">
      {items.map((item, i) => (
        <Text key={item} color={i === activeIndex ? 'cyan' : undefined}>
          {item}
        </Text>
      ))}
    </Box>
  );
}
```

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

### Install termui

Source: https://github.com/arindam200/termui/blob/main/docs/api/testing.md

Install the termui package as a development dependency.

```sh
pnpm add -D termui
```

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

### Install AI Components

Source: https://github.com/arindam200/termui/blob/main/docs/ai.md

Command to add individual AI components to your project.

```sh
npx termui add chat-message chat-thread tool-call thinking-block \
  token-usage context-meter tool-approval model-selector file-change
```

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

### Initialize TermUI Project via CLI

Source: https://github.com/arindam200/termui/blob/main/README.md

Launch the interactive TermUI CLI menu or use direct commands for initialization and component addition. This is part of the quick start process.

```bash
# Launch the interactive menu
npx termui

# Or use commands directly
npx termui init
npx termui add spinner
npx termui add table select alert
npx termui list
```

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

### Install MCP Server Configuration

Source: https://github.com/arindam200/termui/blob/main/docs/api/cli.md

Install the MCP server configuration into an AI tool. This command prompts for the installation scope, which can be local project or global for specific AI tools.

```sh
npx termui add mcp
```

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

### Install cfonts Engine for BigText

Source: https://github.com/arindam200/termui/blob/main/docs/typography.md

Instructions for installing the 'cfonts' engine and copying BigText component files in a shadcn-style project.

```bash
npx termui add big-text   # copies BigText.tsx + BigText.font.ts (basic engine)
npm install cfonts        # opt in to engine="cfonts" — only needed for richer fonts
```

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

### Install a component via CLI

Source: https://github.com/arindam200/termui/blob/main/registry/index.html

Use this command to add a specific component to your project.

```bash
npx termui add <component>
```

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

### React Setup Wizard Component

Source: https://github.com/arindam200/termui/blob/main/skills/cli-creator/references/patterns.md

This React component implements a multi-step setup wizard. It uses `useState` for managing the current step and configuration, and `useInput` for handling global key presses like Ctrl+C to exit. Each step conditionally renders different TermUI input components or displays the selected configuration.

```tsx
// src/app.tsx
import React, { useState } from 'react';
import { Text } from 'ink';
import { useInput, useTheme } from 'termui/core';
import { SetupFlow } from '../components/templates/SetupFlow.js';
import { TextInput } from '../components/input/TextInput.js';
import { Select } from '../components/selection/Select.js';
import { MultiSelect } from '../components/selection/MultiSelect.js';

type Step = 'name' | 'framework' | 'features' | 'installing' | 'done';

export function App() {
  const theme = useTheme();
  const [step, setStep] = useState<Step>('name');
  const [config, setConfig] = useState({ name: '', framework: '', features: [] as string[] });

  useInput((input, key) => {
    if (key.ctrl && input === 'c') process.exit(0);
  });

  const isComplete = (s: Step) => {
    const order: Step[] = ['name', 'framework', 'features', 'installing', 'done'];
    return order.indexOf(s) < order.indexOf(step);
  };

  return (
    <SetupFlow title="SETUP" titleColor={theme.colors.primary}>
      <SetupFlow.Badge label="v1.0" bg="cyan" color="black" />

      {/* Step 1 */}
      <SetupFlow.Step status={isComplete('name') ? 'done' : step === 'name' ? 'active' : 'pending'}>
        {step === 'name' ? (
          <TextInput
            label="Project name"
            placeholder="my-app"
            autoFocus
            onSubmit={(name) => {
              setConfig((c) => ({ ...c, name }));
              setStep('framework');
            }}
          />
        ) : (
          <Text>
            Project name: <Text bold>{config.name}</Text>
          </Text>
        )}
      </SetupFlow.Step>

      {/* Step 2 */}
      {(step === 'framework' || isComplete('framework')) && (
        <SetupFlow.Step status={isComplete('framework') ? 'done' : 'active'}>
          {step === 'framework' ? (
            <Select
              label="Framework"
              options={[
                { value: 'react', label: 'React' },
                { value: 'vue', label: 'Vue' },
                { value: 'svelte', label: 'Svelte' },
              ]}
              onSubmit={(framework) => {
                setConfig((c) => ({ ...c, framework }));
                setStep('features');
              }}
            />
          ) : (
            <Text>
              Framework: <Text bold>{config.framework}</Text>
            </Text>
          )}
        </SetupFlow.Step>
      )}

      {/* Step 3 */}
      {(step === 'features' || isComplete('features')) && (
        <SetupFlow.Step status={isComplete('features') ? 'done' : 'active'}>
          {step === 'features' ? (
            <SetupFlow.MultiSelect
              label="Features"
              hint="space to toggle, enter to confirm"
              options={[
                { value: 'ts', label: 'TypeScript', description: 'recommended' },
                { value: 'lint', label: 'ESLint' },
                { value: 'test', label: 'Testing' },
              ]}
              onSubmit={(features) => {
                setConfig((c) => ({ ...c, features }));
                setStep('installing');
                // Simulate install
                setTimeout(() => setStep('done'), 2000);
              }}
            />
          ) : (
            <Text>
              Features: <Text bold>{config.features.join(', ')}</Text>
            </Text>
          )}
        </SetupFlow.Step>
      )}

      {/* Step 4 — async work */}
      {(step === 'installing' || step === 'done') && (
        <SetupFlow.Step status={step === 'done' ? 'success' : 'active'}>
          {step === 'installing' ? (
            <SetupFlow.Spinner label="Installing packages…" />
          ) : (
            <Text color="green">
              ✓ Done! Run <Text bold>cd {config.name} && npm run dev</Text>
            </Text>
          )}
        </SetupFlow.Step>
      )}
    </SetupFlow>
  );
}

```

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

### Add Components to Project

Source: https://github.com/arindam200/termui/blob/main/docs/api/cli.md

Add one or more components from the registry to your project. You can specify individual components or install all available components.

```sh
npx termui add spinner
```

```sh
npx termui add table select progress-bar
```

```sh
npx termui add --all   # install all 101 components
```

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

### Install @octokit/rest

Source: https://github.com/arindam200/termui/blob/main/docs/adapters.md

Install the @octokit/rest package as a peer dependency for the termui/github library.

```sh
npm install @octokit/rest
```

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

### Install InfoBox component

Source: https://github.com/arindam200/termui/blob/main/docs/templates.md

Add the InfoBox component to your project using the termui CLI.

```sh
npx termui add info-box
```

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

### Add a specific component

Source: https://github.com/arindam200/termui/blob/main/registry/index.html

Example command to add the spinner component.

```bash
npx termui add spinner
```

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

### TermUI CLI Configuration

Source: https://github.com/arindam200/termui/blob/main/docs/interview-guide.md

Example of the termui.config.json file, specifying component directory, registry URL, and the default theme.

```json
{
  "version": "1",
  "componentsDir": "./components/ui",
  "registry": "https://arindam200.github.io/termui",
  "registries": [],
  "theme": "default"
}
```

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

### Start AI Demo App

Source: https://github.com/arindam200/termui/blob/main/README.md

Run the AI demo application using pnpm, specifically filtering for the AI demo package.

```bash
pnpm --filter @termui/ai-demo start
```

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

### Start TermUI MCP Server

Source: https://github.com/arindam200/termui/blob/main/docs/api/cli.md

Start the TermUI MCP server over stdio. This server exposes tools for AI assistants like Claude Code, Cursor, and GitHub Copilot.

```sh
npx termui mcp
```

```sh
npx termui mcp --help
```

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

### Install TermUI Components for CRUD

Source: https://github.com/arindam200/termui/blob/main/skills/cli-creator/references/patterns.md

Use this command to install the necessary TermUI components for building a CRUD manager, including forms, tables, and feedback elements.

```bash
npx termui add app-shell table form form-field text-input select confirm modal alert
```

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

### Install BulletList component

Source: https://github.com/arindam200/termui/blob/main/docs/templates.md

Add the BulletList component to your project using the termui CLI.

```sh
npx termui add bullet-list
```

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

### Install keytar

Source: https://github.com/arindam200/termui/blob/main/docs/adapters.md

Install the keytar package as a peer dependency for the termui/keychain library. Note that keytar is a native module and may require rebuilding.

```sh
npm install keytar
```

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

### Install node-pty

Source: https://github.com/arindam200/termui/blob/main/docs/adapters.md

Install the node-pty package as a peer dependency for the termui/pty library. Note that node-pty is a native module.

```sh
npm install node-pty
```

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

### Basic TermUI Application Structure

Source: https://github.com/arindam200/termui/blob/main/README.md

This example demonstrates the basic structure of a TermUI application using React components. It includes rendering components within a ThemeProvider.

```tsx
import React from 'react';
import { render } from 'ink';
import { ThemeProvider } from 'termui';
import { Spinner, ProgressBar, Alert, Select } from 'termui/components';

function App() {
  return (
    <ThemeProvider>
      <Spinner style="dots" label="Loading…" />
      <ProgressBar value={72} total={100} label="Installing…" />
      <Alert variant="success" title="Done!">
        Your app is ready.
      </Alert>
      <Select
        options={[
          { value: 'npm', label: 'npm' },
          { value: 'pnpm', label: 'pnpm' },
          { value: 'bun', label: 'bun' },
        ]}
        onSubmit={(val) => console.log('Selected:', val)}
      />
    </ThemeProvider>
  );
}

render(<App />);
```

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

### Install Commander Peer Dependency

Source: https://github.com/arindam200/termui/blob/main/docs/adapters.md

Install the `commander` package as a peer dependency before using the TermUI commander adapter.

```sh
npm install commander
```

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

### Add LoginFlow Component

Source: https://github.com/arindam200/termui/blob/main/docs/templates.md

Install the LoginFlow component using the termui CLI.

```sh
npx termui add login-flow
```

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

### Conventional Commits Example

Source: https://github.com/arindam200/termui/blob/main/CONTRIBUTING.md

Examples illustrating the Conventional Commits format for commit messages, including types like 'feat', 'fix', 'docs', and 'chore'.

```text
feat(components): add GanttChart component
fix(testing): use debug mode to capture output in CI
docs(readme): update component count to 101
```

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

### Modal with ARIA Annotations Example

Source: https://github.com/arindam200/termui/blob/main/docs/accessibility.md

Example of using `aria-label` and `aria-description` props on a `Modal` component to provide context for screen readers.

```tsx
<Modal
  isOpen={open}
  onClose={onClose}
  aria-label="Delete confirmation"
  aria-description="Confirm that you want to permanently delete this file"
>
  ...
</Modal>
```

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

### TermUI CLI Component Installation

Source: https://github.com/arindam200/termui/blob/main/docs/interview-guide.md

Use this command to add TermUI components directly into your project. This approach avoids runtime lock-in and allows for full customization.

```bash
npx termui add spinner
```

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

### Theme Provider Setup

Source: https://github.com/arindam200/termui/blob/main/docs/interview-guide.md

Wraps the application with a ThemeProvider to apply a specific theme. It automatically detects dark/light mode based on the COLORFGBG environment variable.

```tsx
<ThemeProvider theme={draculaTheme}>
  <App />
</ThemeProvider>
```

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

### In-App Notification Provider Setup

Source: https://github.com/arindam200/termui/blob/main/docs/api/hooks.md

Set up the notification system by calling `useNotificationsProvider` in a parent component. This provides the necessary context for the notification queue.

```tsx
// In root component:
const { value } = useNotificationsProvider();
return (
  <NotificationsContext.Provider value={value}>
    <App />
    <NotificationCenter />
  </NotificationsContext.Provider>
);
```

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

### Custom File List with Keyboard Navigation

Source: https://github.com/arindam200/termui/blob/main/docs/accessibility.md

Example of creating a custom file list component that utilizes the `useKeyboardNavigation` hook to manage active item selection and handle file opening or dismissal.

```tsx
import { useKeyboardNavigation } from 'termui';
import { Box, Text } from 'ink';

function FileList({ files }: { files: string[] }) {
  const { activeIndex } = useKeyboardNavigation({
    itemCount: files.length,
    onSelect: (i) => openFile(files[i]!),
    onDismiss: () => setOpen(false),
  });

  return (
    <Box flexDirection="column">
      {files.map((file, i) => (
        <Text key={file} color={i === activeIndex ? 'cyan' : undefined}>
          {i === activeIndex ? '> ' : '  '}
          {file}
        </Text>
      ))}
    </Box>
  );
}
```

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

### WelcomeScreen Template

Source: https://github.com/arindam200/termui/blob/main/skills/termui/references/components.md

The WelcomeScreen template creates a two-panel welcome dashboard, typically used for initial setup or overview. It separates content into left and right panels, allowing for greetings, logos, metadata, and sections with lists.

```tsx
<WelcomeScreen appName="MyApp" version="1.0.0">
  <WelcomeScreen.Left>
    <WelcomeScreen.Greeting>Welcome back, Arindam!</WelcomeScreen.Greeting>
    <WelcomeScreen.Logo>
      <BigText font="block">MA</BigText>
    </WelcomeScreen.Logo>
    <WelcomeScreen.Meta data={{ Plan: 'Pro', Org: 'Studio1hq' }} />
  </WelcomeScreen.Left>
  <WelcomeScreen.Right>
    <WelcomeScreen.Section title="Recent Projects">
      <List items={projects} />
    </WelcomeScreen.Section>
  </WelcomeScreen.Right>
</WelcomeScreen>
```

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

### Spawn a pseudo-terminal with termui/pty

Source: https://github.com/arindam200/termui/blob/main/packages/adapters/pty/README.md

Initializes a pseudo-terminal process and handles output data. Ensure node-pty is installed as a peer dependency.

```ts
import { spawnPty, usePtyOutput } from 'termui/pty';

const p = await spawnPty('bash', ['-c', 'echo hi'], { cols: 80, rows: 24 });
if (p) {
  p.onData((d) => process.stdout.write(d));
  p.onExit(() => {});
}
```

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

### Build an Interactive Chat UI with useChat Hook

Source: https://github.com/arindam200/termui/blob/main/docs/ai.md

Combine `ChatThread`, `TextInput`, and `useChat` to create a minimal interactive chat UI. This example demonstrates setting up a chat with a system prompt, handling user input, and displaying messages and token usage. The `isStreaming` flag controls the placeholder text in the input field.

```tsx
import React, { useState } from 'react';
import { render } from 'ink';
import { useChat } from 'termui/ai';
import { ChatThread, ChatMessage, TokenUsage, TextInput } from 'termui/components';

function ChatApp() {
  const [input, setInput] = useState('');
  const { messages, sendMessage, isStreaming, tokenUsage } = useChat({
    provider: 'anthropic',
    model: 'claude-sonnet-4-6',
    systemPrompt: 'You are a helpful terminal assistant. Be concise.',
  });

  const handleSubmit = async (value: string) => {
    if (!value.trim() || isStreaming) return;
    setInput('');
    await sendMessage(value.trim());
  };

  return (
    <>
      <ChatThread maxHeight={30}>
        {messages.map((msg, i) => (
          <ChatMessage key={i} role={msg.role} streaming={isStreaming && i === messages.length - 1}>
            {msg.content}
          </ChatMessage>
        ))}
      </ChatThread>

      {tokenUsage && (
        <TokenUsage
          prompt={tokenUsage.prompt}
          completion={tokenUsage.completion}
          model="claude-sonnet-4-6"
          showCost
        />
      )}

      <TextInput
        value={input}
        onChange={setInput}
        onSubmit={handleSubmit}
        placeholder={isStreaming ? 'Waiting for response…' : 'Ask something…'}
      />
    </>
  );
}

render(<ChatApp />);
```

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

### Use TermUI Ora Spinner

Source: https://github.com/arindam200/termui/blob/main/docs/adapters.md

Instantiate and control an ora spinner. Start the spinner, perform an asynchronous operation, and then finalize with `succeed`, `fail`, `warn`, or `info`.

```typescript
import { ora } from 'termui/ora';

const spinner = ora({ text: 'Loading data…', color: 'cyan' }).start();

await fetchData();

spinner.succeed('Data loaded');
// or spinner.fail('Request failed');
```

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

### Use useTerminalSize in Vue

Source: https://github.com/arindam200/termui/blob/main/docs/adapters.md

Use the useTerminalSize composable in a Vue 3 script setup block to get reactive terminal dimensions.

```ts
import type { SelectProps, TableProps } from 'termui/vue';
import { useTerminalSize } from 'termui/vue';

// In a Vue 3 <script setup> block:
const { columns, rows } = useTerminalSize();
// columns and rows are Vue refs that update on terminal resize
```

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

### Implement SetupFlow component

Source: https://github.com/arindam200/termui/blob/main/docs/templates.md

Use the SetupFlow component to create a step-by-step CLI wizard with progress indicators and interactive selection.

```tsx
import { SetupFlow } from 'termui/components';

<SetupFlow title="setup">
  <SetupFlow.Badge label="WELCOME" bg="cyan" color="black" />
  <SetupFlow.Step status="success">Project directory created</SetupFlow.Step>
  <SetupFlow.Step status="active">Installing dependencies</SetupFlow.Step>
  <SetupFlow.Spinner label="Resolving packages..." />
  <SetupFlow.MultiSelect
    label="Select features to enable"
    hint="Space to toggle, Enter to confirm"
    options={[
      { value: 'ts', label: 'TypeScript' },
      { value: 'lint', label: 'ESLint', description: 'recommended' },
    ]}
    onSubmit={(vals) => configureFeatures(vals)}
  />
</SetupFlow>;
```

```sh
npx termui add setup-flow
```

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

### Manage TermUI via CLI

Source: https://github.com/arindam200/termui/blob/main/skills/termui/SKILL.md

Use these commands to scaffold projects, initialize TermUI, add components, and manage themes.

```bash
npx termui create my-app            # scaffold a new project (4 templates: minimal, cli, dashboard, wizard)
npx termui init                     # setup termui in an existing project
npx termui add spinner table select # add components (copies source into project)
npx termui list                     # browse all components
npx termui theme dracula            # switch project theme
npx termui preview <component>      # live preview
```

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

### List all TermUI components

Source: https://github.com/arindam200/termui/blob/main/README.md

Use the 'termui list' command to see all available components. Use 'termui preview' to see them in action.

```bash
npx termui list
```

```bash
npx termui preview
```

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

### Focus Trap Example

Source: https://github.com/arindam200/termui/blob/main/docs/api/hooks.md

Example demonstrating the use of useFocusTrap within a modal component to manage focus.

```tsx
function Modal({ isOpen, onClose }: { isOpen: boolean; onClose: () => void }) {
  useFocusTrap({
    focusableIds: ['modal-confirm', 'modal-cancel'],
    isActive: isOpen,
  });

  const { isFocused: confirmFocused } = useFocus({ id: 'modal-confirm' });
  const { isFocused: cancelFocused } = useFocus({ id: 'modal-cancel' });

  useInput(
    (_, key) => {
      if (key.escape) onClose();
    },
    { isActive: isOpen }
  );

  return (
    <Box flexDirection="column">
      <Text>Confirm this action?</Text>
      <Text color={confirmFocused ? 'cyan' : 'gray'}>[Yes]</Text>
      <Text color={cancelFocused ? 'cyan' : 'gray'}>[No]</Text>
    </Box>
  );
}
```

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

### Initialize TermUI Project

Source: https://github.com/arindam200/termui/blob/main/docs/index.md

Run this command to initialize TermUI in your project. It sets up the necessary configurations.

```sh
npx termui init
```

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

### Implement HelpScreen

Source: https://github.com/arindam200/termui/blob/main/skills/termui/references/components.md

Provides a full-screen overlay for displaying keyboard shortcuts.

```tsx
<HelpScreen
  title="Help — MyApp"
  sections={[
    { heading: 'Navigation', shortcuts: [{ key: '↑↓', description: 'Move up/down' }] },
    {
      heading: 'Actions',
      shortcuts: [
        { key: 'Enter', description: 'Select' },
        { key: 'q', description: 'Quit' },
      ],
    },
  ]}
  onClose={() => setHelp(false)}
/>
```

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

### Help Component

Source: https://github.com/arindam200/termui/blob/main/docs/utility.md

Context-sensitive help panel with keyboard shortcuts.

```APIDOC
## Help

### Description
Context-sensitive help panel with keyboard shortcuts.

### Parameters
- **isOpen** (boolean) - Required - Visibility state
- **onClose** (() => void) - Required - Close handler
- **shortcuts** (Shortcut[]) - Required - List of shortcuts
- **title** (string) - Optional - Panel title (default: 'Keyboard Shortcuts')
```

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

### Apply a theme

Source: https://github.com/arindam200/termui/blob/main/registry/index.html

Use this command to configure the visual theme of your components.

```bash
npx termui theme
```

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

### Create Commander Program with TermUI Styling

Source: https://github.com/arindam200/termui/blob/main/docs/adapters.md

Use `createCommanderProgram` to set up a Commander program with TermUI's themed help output. Configure name, version, description, and theme color.

```typescript
import { createCommanderProgram } from 'termui/commander';

const { program } = createCommanderProgram({
  name: 'mycli',
  version: '1.0.0',
  description: 'My TermUI CLI',
  themeColor: '#00d7ff',
});

((await program) as any).command('build').action(() => console.log('building…'));
((await program) as any).parse();
```

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

### Preview Components

Source: https://github.com/arindam200/termui/blob/main/docs/api/cli.md

Launch an interactive component gallery in your terminal. This allows you to browse all components and edit their props live.

```sh
npx termui preview
```

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

### WelcomeScreen Component

Source: https://github.com/arindam200/termui/blob/main/docs/templates.md

A two-panel welcome screen component for CLI applications, featuring branding and quick-start sections.

```APIDOC
## WelcomeScreen

### Description
A two-panel welcome screen with a titled border, a left panel for branding or a logo, and a right panel for sections, quick-start info, or metadata.

### Parameters
#### Props
- **appName** (string) - Required - The name of the application.
- **children** (ReactNode) - Required - The content to render within the screen.
- **appNameColor** (string) - Optional - Color of the app name.
- **version** (string) - Optional - Version string.
- **borderStyle** ('single' | 'round' | 'double' | 'bold') - Optional - Style of the border.
- **leftWidth** (number) - Optional - Width of the left panel.
```

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

### Render a DirectoryTree component

Source: https://github.com/arindam200/termui/blob/main/docs/data.md

Browser for filesystem paths. The root prop defines the starting directory.

```tsx
import { DirectoryTree } from 'termui/components';

<DirectoryTree root={process.cwd()} onSelect={(path) => console.log(path)} />;
```

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

### BigText with cfonts Engine

Source: https://github.com/arindam200/termui/blob/main/docs/typography.md

Opt-in to the 'cfonts' engine for richer fonts and features. Requires 'cfonts' to be installed.

```tsx
// Opt in to cfonts for a richer look
<BigText engine="cfonts" font="tiny">HELLO</BigText>
```

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

### Use TermUI Clack Prompts and Spinners

Source: https://github.com/arindam200/termui/blob/main/docs/adapters.md

Utilize `intro` and `outro` for banners, `text` for input, `confirm` for boolean choices, and `spinner` for progress indication. Includes `deploy` and `log` helpers.

```typescript
import { intro, outro, text, confirm, spinner } from 'termui/clack';

intro('Deploy Tool');
const name = await text({ message: 'Project name?', placeholder: 'my-app' });
const ok = await confirm({ message: `Deploy ${name}?` });
if (ok) {
  const s = spinner();
  s.start('Deploying…');
  await deploy(name);
  s.stop('Done');
}
outro('Deployment complete');
```

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

### Usage of ChatThread Component

Source: https://github.com/arindam200/termui/blob/main/docs/ai.md

Example of using ChatThread to stack multiple ChatMessage components in a scrollable column.

```tsx
import { ChatThread, ChatMessage } from 'termui/components';

<ChatThread maxHeight={20}>
  {messages.map((msg) => (
    <ChatMessage key={msg.id} role={msg.role}>
      {msg.content}
    </ChatMessage>
  ))}
</ChatThread>;
```

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

### Create an AI Assistant Tool with TermUI

Source: https://github.com/arindam200/termui/blob/main/README.md

Scaffold a new project specifically designed for an AI assistant tool using a dedicated TermUI template. This command sets up the project with relevant configurations.

```bash
npx termui create my-ai-tool --template ai-assistant
```

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

### Usage of ChatMessage Component

Source: https://github.com/arindam200/termui/blob/main/docs/ai.md

Examples of rendering user, assistant, system, and error messages using the ChatMessage component.

```tsx
import { ChatMessage } from 'termui/components';

// User turn
<ChatMessage role="user" timestamp={new Date()}>
  Explain how React Server Components work.
</ChatMessage>

// Assistant reply — live while streaming
<ChatMessage role="assistant" streaming={isStreaming}>
  {partialText}
</ChatMessage>

// System instruction (dimmed)
<ChatMessage role="system">
  You are a helpful CLI assistant.
</ChatMessage>

// Error state
<ChatMessage role="error">
  Rate limit exceeded. Retry in 30s.
</ChatMessage>
```

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

### BigText with cfonts Gradient

Source: https://github.com/arindam200/termui/blob/main/docs/typography.md

Applies a gradient effect across characters when using the 'cfonts' engine. Requires 'cfonts' to be installed.

```tsx
// Gradient across characters (cfonts only)
<BigText engine="cfonts" font="tiny" gradient={['red', 'magenta']} transitionGradient>
  TERMUI
</BigText>
```

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

### WelcomeScreen Component Usage

Source: https://github.com/arindam200/termui/blob/main/docs/templates.md

Use the WelcomeScreen component to create a two-panel application entry point. It requires an appName and children. Customize borders and panel widths as needed.

```tsx
import { WelcomeScreen } from 'termui/components';

<WelcomeScreen appName="myapp" version="v2.1.0">
  <WelcomeScreen.Left>
    <WelcomeScreen.Logo>{'  ██╗\n  ╚═╝'}</WelcomeScreen.Logo>
    <WelcomeScreen.Meta items={['TypeScript', 'MIT']} dim />
  </WelcomeScreen.Left>
  <WelcomeScreen.Right>
    <WelcomeScreen.Greeting>Good morning, Arindam</WelcomeScreen.Greeting>
    <WelcomeScreen.Section title="Quick Start">
      Run `myapp init` to get started.
    </WelcomeScreen.Section>
  </WelcomeScreen.Right>
</WelcomeScreen>
```

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

### Apply a TermUI Theme

Source: https://github.com/arindam200/termui/blob/main/docs/index.md

Change the visual theme of your TermUI components by applying one of the built-in themes. For example, to apply the 'dracula' theme.

```sh
npx termui theme dracula
```

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

### useKeymap

Source: https://github.com/arindam200/termui/blob/main/docs/api/hooks.md

Allows for declarative registration of keybindings. You can define key combinations and associate them with specific actions, along with optional descriptions for documentation.

```APIDOC
## `useKeymap(bindings)`

### Description
Allows for declarative registration of keybindings. You can define key combinations and associate them with specific actions, along with optional descriptions for documentation.

### Parameters
#### Arguments
- **bindings** (`KeyBinding[]`) - Required - An array of keybinding configurations.

### KeyBinding Object
#### Fields
- **key** (`string`) - Required - The key to bind (e.g., 'a', 'enter', 'escape').
- **ctrl** (`boolean`) - Optional - If `true`, requires the Ctrl modifier.
- **action** (`() => void`) - Required - The function to execute when the keybinding is triggered.
- **description** (`string`) - Optional - A description of the keybinding's action.
```

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

### DirectoryTree for Filesystem Navigation

Source: https://github.com/arindam200/termui/blob/main/skills/termui/references/components.md

Use DirectoryTree to display a file system directory structure. Specify the starting 'path' and handle file/directory selection with 'onSelect'.

```tsx
<DirectoryTree path="/Users/me/project" onSelect={(filePath) => openFile(filePath)} />
```

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

### Apply Catppuccin Theme via CLI

Source: https://github.com/arindam200/termui/blob/main/README.md

Applies the Catppuccin theme to TermUI from the command line.

```bash
npx termui theme catppuccin
```

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

### Svelte framework type bridges

Source: https://github.com/arindam200/termui/blob/main/README.md

Import TermUI component prop types for use in Svelte projects. Example shows importing 'AlertProps' and 'SelectProps' from 'termui/svelte'.

```typescript
import type { AlertProps, SelectProps } from 'termui/svelte';
```

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

### Develop CLI Package

Source: https://github.com/arindam200/termui/blob/main/README.md

Run the development command for the CLI package from the repository root.

```bash
pnpm --filter @termui/cli dev
```

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

### Vue framework type bridges

Source: https://github.com/arindam200/termui/blob/main/README.md

Import TermUI component prop types for use in Vue projects. Example shows importing 'SpinnerProps' and 'TableProps' from 'termui/vue'.

```typescript
import type { SpinnerProps, TableProps } from 'termui/vue';
```

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

### Help Component Usage

Source: https://github.com/arindam200/termui/blob/main/docs/utility.md

Displays a context-sensitive help panel containing keyboard shortcuts.

```tsx
import { Help } from 'termui/components';

<Help isOpen={showHelp} onClose={() => setHelp(false)} shortcuts={shortcuts} />;
```

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

### Implement UsageMonitor

Source: https://github.com/arindam200/termui/blob/main/skills/termui/references/components.md

Creates a real-time dashboard for monitoring system resources like CPU and memory.

```tsx
<UsageMonitor
  title="SYSTEM MONITOR"
  refreshInterval={1000}
  metrics={[
    {
      label: 'CPU',
      value: cpuPct,
      max: 100,
      unit: '%',
      color: '#7C3AED',
      status: cpuPct > 80 ? 'warn' : 'ok',
    },
    { label: 'Memory', value: memUsed, max: memTotal, unit: 'GB', color: '#10B981' },
  ]}
  distribution={{
    label: 'Disk',
    segments: [
      { label: 'Used', value: 60, color: '#7C3AED' },
      { label: 'Free', value: 40 },
    ],
  }}
  predictions={[{ label: 'Est. completion', value: '4m 30s', color: '#10B981' }]}
  statusBar={{ clock: true, session: 'Production', exitHint: 'q: quit' }}
/>
```

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

### Toast with ARIA Live Region

Source: https://github.com/arindam200/termui/blob/main/docs/accessibility.md

Example of using the `aria-live="assertive"` prop on a `Toast` component for urgent messages that should be immediately announced by screen readers.

```tsx
<Toast message="File deleted" aria-live="assertive" />
```

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

### Develop with Parallel Package Watch

Source: https://github.com/arindam200/termui/blob/main/README.md

Initiate development mode with parallel package watching using Turborepo.

```bash
pnpm dev
```

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

### Use useKeychain hook

Source: https://github.com/arindam200/termui/blob/main/docs/adapters.md

Utilize the useKeychain hook for accessing the OS keychain. It provides methods to get, set, and delete credentials. Gracefully degrades if keytar is unavailable.

```tsx
import { useKeychain } from 'termui/keychain';

function TokenManager() {
  const { available, get, set, del } = useKeychain('my-cli');
  if (!available) return <Text dim>Keychain unavailable</Text>;

  const handleSave = async () => {
    await set('github-token', 'ghp_…');
  };
  return <Text>Keychain ready — <Text onPress={handleSave}>Save token</Text></Text>;
}
```

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

### Import termui/pty hooks

Source: https://github.com/arindam200/termui/blob/main/docs/adapters.md

Import spawnPty and usePtyOutput from the termui/pty library for pseudo-terminal interaction.

```ts
import { spawnPty, usePtyOutput } from 'termui/pty';
```

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

### Spinner Component Example

Source: https://github.com/arindam200/termui/blob/main/docs/interview-guide.md

A functional React component that displays a spinning indicator. It uses hooks for theme, motion, and unicode support, and renders Ink primitives with flexbox layout.

```tsx
export function Spinner({ style = 'dots', label, fps = 10 }: SpinnerProps) {
  const theme = useTheme();
  const { reduced } = useMotion();
  const unicode = useUnicode();
  const frame = useAnimation(fps);

  if (reduced) return <Text>{label ?? '...'}</Text>;

  const frames = unicode ? FRAMES[style] : ASCII_FRAMES[style];
  return (
    <Text color={theme.colors.primary}>
      {frames[frame % frames.length]} {label}
    </Text>
  );
}
```

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

### Scaffold a New CLI Project with TermUI

Source: https://github.com/arindam200/termui/blob/main/README.md

Create a new command-line interface project using a specific TermUI template. This command scaffolds the project structure and initial files.

```bash
# 1. Scaffold a new project
npx termui create my-cli --template cli

# 2. Add components
cd my-cli
npx termui add spinner table select

# 3. Run your app
npm run dev
```

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

### Write Headless Component Tests with Vitest

Source: https://github.com/arindam200/termui/blob/main/CONTRIBUTING.md

Example of writing headless component tests using Vitest and the @termui/testing package. Ensure props are typed and the component respects the theme.

```typescript
import { describe, it, expect } from 'vitest';
import React from 'react';
import { renderToString } from '@termui/testing';
import { MyComponent } from '../MyComponent.js';

describe('MyComponent', () => {
  it('renders expected text', async () => {
    const output = await renderToString(React.createElement(MyComponent, { label: 'Hello' }));
    expect(output).toContain('Hello');
  });
});
```

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

### Import TermUI Clack Helpers

Source: https://github.com/arindam200/termui/blob/main/docs/adapters.md

Import `intro`, `outro`, `text`, `confirm`, `select`, `spinner`, and `log` from `termui/clack` for creating interactive CLI prompts.

```typescript
import { intro, outro, text, confirm, select, spinner, log } from 'termui/clack';
```

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

### Conditional Rendering based on Reduced Motion

Source: https://github.com/arindam200/termui/blob/main/docs/accessibility.md

Example of using the `reduced` value from `useMotion` to conditionally render a simple text indicator instead of an animated spinner when reduced motion is preferred.

```tsx
import { useMotion } from 'termui';
import { Spinner } from 'termui';
import { Text } from 'ink';

function LoadingIndicator() {
  const { reduced } = useMotion();
  if (reduced) return <Text>[loading...]</Text>;
  return <Spinner />;
}
```

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

### Build CLI applications with args

Source: https://github.com/arindam200/termui/blob/main/docs/adapters.md

Define CLI commands and parse arguments using createCLI or createCLIv2 for advanced handler support.

```typescript
import { createCLI, createCLIv2, createOutput, withGracefulExit } from 'termui/args';
```

```typescript
import { createCLI } from 'termui/args';

const cli = createCLI({
  name: 'mycli',
  version: '1.0.0',
  description: 'My CLI tool',
  commands: {
    build: {
      name: 'build',
      description: 'Build the project',
      args: { out: { description: 'Output dir', default: 'dist' } },
    },
  },
});

const result = cli.parse();
if (result) console.log(result.command, result.args);
```

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

### termui/commander

Source: https://github.com/arindam200/termui/blob/main/docs/adapters.md

Commander wrapper with TermUI-styled help output.

```APIDOC
## termui/commander

### Description
Wraps the Commander library to provide TermUI-themed help output and colored errors. Requires the commander peer dependency.

### Usage
```ts
import { createCommanderProgram } from 'termui/commander';
const { program } = createCommanderProgram({ name: 'mycli', themeColor: '#00d7ff' });
```
```

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

### Package JSON Template for CLI Project

Source: https://github.com/arindam200/termui/blob/main/skills/cli-creator/SKILL.md

This is a template for the package.json file, defining project name, version, scripts for development, build, and start, along with dependencies and devDependencies for a TermUI CLI project.

```json
{
  "name": "<project-name>",
  "version": "0.1.0",
  "type": "module",
  "bin": { "<project-name>": "./dist/index.js" },
  "scripts": {
    "dev": "tsx src/index.tsx",
    "build": "tsc",
    "start": "node dist/index.js"
  },
  "dependencies": {
    "ink": "^5.0.0",
    "react": "^18.0.0",
    "termui": "latest"
  },
  "devDependencies": {
    "typescript": "^5.4.0",
    "tsx": "^4.7.0",
    "@types/react": "^18.0.0"
  },
  "engines": { "node": ">=18.0.0" }
}
```

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

### Using the Profiler Component

Source: https://github.com/arindam200/termui/blob/main/docs/utility.md

Wrap your components with the Profiler to enable live render timing stats. Ensure the 'id' prop is provided.

```tsx
import { Profiler } from 'termui/components';

<Profiler id="MyList" show>
  <MyList items={data} />
</Profiler>
```

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

### TermUI Adapters Package Overview

Source: https://github.com/arindam200/termui/blob/main/docs/interview-guide.md

Highlights key adapters available in the `@termui/adapters` package. These adapters allow existing CLI libraries to integrate with TermUI theming without significant code rewrites.

```plaintext
chalk
ora
clack
inquirer
commander / meow
ai
voice
pty
git / github
```

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

### Show Component Diff

Source: https://github.com/arindam200/termui/blob/main/docs/api/cli.md

Show the differences between the local version of a component and the version available in the registry.

```sh
npx termui diff table
```

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

### TermUI Entry Point with ThemeProvider

Source: https://github.com/arindam200/termui/blob/main/skills/cli-creator/SKILL.md

The main entry point for a TermUI application, rendering the root component within a ThemeProvider to ensure consistent styling. Requires React and Ink.

```tsx
#!/usr/bin/env node
import React from 'react';
import { render } from 'ink';
import { ThemeProvider } from 'termui/core';
import { draculaTheme } from 'termui/core';
import { App } from './app.js';

render(
  <ThemeProvider theme={draculaTheme}>
    <App />
  </ThemeProvider>
);
```

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

### Preview TermUI Components

Source: https://github.com/arindam200/termui/blob/main/docs/index.md

Open the TermUI component gallery in your terminal to browse and preview available components.

```sh
npx termui preview
```

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

### Render HelpScreen with Sections and Rows

Source: https://github.com/arindam200/termui/blob/main/docs/templates.md

Use this component to display comprehensive help information. Import HelpScreen and its sub-components from 'termui/components'. Configure title, tagline, and usage, then populate sections with rows of flags and descriptions.

```tsx
import { HelpScreen } from 'termui/components';

<HelpScreen
  title="myapp"
  tagline="The fastest way to ship CLI tools"
  usage="myapp <command> [flags]"
>
  <HelpScreen.Section label="Commands">
    <HelpScreen.Row flag="init" description="Initialise a new project" />
    <HelpScreen.Row flag="add <component>" description="Copy a component into your project" />
    <HelpScreen.Row flag="preview" description="Launch the interactive gallery" />
  </HelpScreen.Section>
  <HelpScreen.Section label="Global flags">
    <HelpScreen.Row flag="--help, -h" description="Show this help screen" />
    <HelpScreen.Row flag="--version, -v" description="Print version number" />
  </HelpScreen.Section>
</HelpScreen>;
```

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

### Import TermUI Chalk

Source: https://github.com/arindam200/termui/blob/main/docs/adapters.md

Import the chalk adapter from `termui/chalk`. This provides a chalk-compatible chainable ANSI color API.

```typescript
import { chalk } from 'termui/chalk';
```

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

### Implement ToolApproval

Source: https://github.com/arindam200/termui/blob/main/skills/termui/references/components.md

Creates an interactive permission gate for sensitive AI actions.

```tsx
<ToolApproval
  name="run_command"
  description="Run shell command"
  args={{ command: 'rm -rf node_modules && npm install' }}
  risk="medium" // 'low'|'medium'|'high' — affects border color
  onApprove={() => runCommand()}
  onDeny={() => skipCommand()}
  onAlwaysAllow={() => setAlwaysAllow(true)}
  timeout={30} // auto-deny after N seconds
/>
// Keys: y approve, n deny, a always-allow
```

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

### Apply Nord Theme via CLI

Source: https://github.com/arindam200/termui/blob/main/README.md

Applies the Nord theme to TermUI from the command line.

```bash
npx termui theme nord
```

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

### Run Tests for a Single Package

Source: https://github.com/arindam200/termui/blob/main/CONTRIBUTING.md

Command to run tests specifically for the '@termui/components' package using pnpm filters.

```bash
pnpm --filter @termui/components test
```