CLI Reference

All commands are available via npx terminaltui <command> or, if installed globally, terminaltui <command>.

Commands at a glance

Command	Purpose
`init`	Scaffold a new project from a template
`create`	Interactive prompt builder for AI scaffolding
`convert`	Drop reference docs into an existing project so an AI can convert it
`validate`	Lint a file-based routing project for common mistakes
`dev`	Run your TUI locally with on-the-fly compilation
`serve`	Host your TUI over SSH (anyone can connect)
`build`	Bundle for npm publish
`demo`	Run a built-in demo
`test`	Run automated tests on the site in the current directory
`art`	Manage ASCII art assets
`help` / `version`	Help and version output

init

Scaffold a new project from a template.

terminaltui init [template]

Templates: minimal, portfolio, landing, restaurant, blog, creative.

If no template is specified, you’ll get an interactive prompt.

create

Interactive prompt builder for new projects.

terminaltui create

Asks 10 questions about your project (name, description, pages, content, theme, style, ASCII art, interactive features, animations, extras), then generates a tailored AI prompt. See Create Command for details.

convert

Drop terminaltui reference docs into your project for AI-assisted website conversion.

terminaltui convert

Copies TERMINALTUI_SKILL.md and TERMINALTUI_PROMPT.md into the current directory with paths pre-filled. Open Claude (or another AI coding assistant) and point it at these files to convert your existing website into a TUI in a tui/ subdirectory.

validate

Lint a file-based routing project for common issues.

terminaltui validate

Catches missing default exports, dynamic-route name collisions, layout files in unreachable positions, and similar mistakes. Exits non-zero if any errors are found (warnings still pass). Only runs against config.ts + pages/ projects.

dev

Start the development preview. If your project defines API routes (files under api/), a local HTTP server starts automatically.

terminaltui dev [path]

With no argument, looks for config.ts alongside a pages/ directory in the current working directory. Pass an explicit path to force a specific config file.

serve

Host your TUI over SSH. Anyone on the network can connect via ssh host -p PORT and use the app interactively, no install required. Each connection gets an independent session.

terminaltui serve [path] [options]

Flag	Default	Description
`--port <N>`	`2222`	SSH port
`--host-key <path>`	`.terminaltui/host_key`	Host key path (auto-generated as Ed25519 on first run)
`--max-connections <N>`	`100`	Max simultaneous connections

You can also configure these in your project via the serve field on defineConfig(). See SSH Hosting for the full guide, including auth, color-mode handling, and security notes.

ssh2 is an optional peer dependency — install it with npm install ssh2 if it’s not already pulled in.

build

Bundle the site for npm publishing.

terminaltui build [path]

After building, run npm publish to make your site available via npx your-package-name. Build validation checks that the bundle contains a runSite() call and warns about hardcoded absolute paths.

demo

Run a built-in demo from the published package — no install or scaffolding required.

terminaltui demo <name>

Available demos:

Name	Theme	Highlights
`restaurant`	gruvbox	Tabbed menu, reservation form, split layout
`dashboard`	hacker	Live API data, persistent state, parameterized routes
`band`	rosePine	Album cards, tour dates, mailing list
`coffee-shop`	catppuccin	Tabbed menu, catering form
`conference`	nord	Schedule tabs, speaker grid, sponsor tiers
`developer-portfolio`	cyberpunk	Skill bars, sparklines, project grid
`freelancer`	custom	Testimonial quotes, contact form
`startup`	tokyoNight	Pricing tiers, feature accordion
`server-dashboard`	hacker	System metrics, container table, log stream

Demo sources ship inside the published terminaltui package under demos/<name>/ (config.ts + pages/). The CLI compiles them on the fly via esbuild.

test

Run automated tests on the site in the current directory using the headless emulator.

terminaltui test [options]

Flag	Description
`--cols=N`	Test at a specific terminal width (default: 80)
`--sizes`	Test at multiple widths: 40, 80, 120, 200
`--verbose`, `-v`	Show screen output during tests

art

Manage ASCII art assets.

terminaltui art <subcommand>

Subcommands: list, preview, create, validate.

help

Show the help message.

terminaltui help
terminaltui --help
terminaltui -h

version

Print the installed version.

terminaltui version
terminaltui --version
terminaltui -v