Commands

Built-in commands, custom commands, and pipe chains.

Built-in Commands

These commands are always available. Filesystem commands (ls, cd, tree, open) are registered when you pass the filesystem prop. Theme commands (theme, mode) are registered when you pass the theme prop.

Command Aliases Description
help?Show available commands
clearclsClear terminal history
history—Show command history
echo—Print text to output
lsdirList current directory
cd—Navigate to directory or page
opengotoNavigate to URL or path
tree—Show directory tree
theme—Switch color theme
mode—Toggle dark/light mode
grep—Filter lines matching pattern (pipe target)
head—Show first N lines (pipe target)
tail—Show last N lines (pipe target)
wc—Count lines, words, chars (pipe target)

Custom Commands

Pass an array of Command objects to the commands prop.

custom-command.tsx
import { Terminal, type Command, type CommandResult } from "@trents/terminal"

const greetCommand: Command = {
  name: "greet",
  aliases: ["hello"],
  description: "Say hello",
  usage: "greet [name]",
  execute: (args): CommandResult => ({
    output: [[{ text: `Hello, ${args[0] ?? "world"}!`, color: "main" }]],
  }),
}

<Terminal commands={[greetCommand]} />

Pipe Operators

Commands can be chained with |. The output of one command becomes the stdin of the next.

terminal
# Filter directory listing
ls | grep docs

# First 5 history entries
history | head -n 5

# Chain multiple pipes
ls | grep components | wc

Pipe targets (grep, head, tail, wc) receive piped data via ctx.stdin.

Command Context

Every command receives a CommandContext as its second argument.

types.ts
interface CommandContext {
  cwd: string                    // Current working directory
  history: HistoryEntry[]        // All command history
  resolve: (path: string) => ResolvedNode | null
  terminal: {
    close: () => void            // Close the terminal
    clear: () => void            // Clear history
    setCwd: (cwd: string) => void
    focus: () => void            // Focus the input
  }
  confirm: (msg: string) => Promise<boolean>
  select: (msg: string, options: SelectOption[]) => Promise<string>
  stdin?: OutputLine[]           // Piped input from previous command
}

Async Generators

For streaming output, return an async generator instead of a plain result. Each yield flushes a line to the terminal immediately.

streaming.tsx
const countdown: Command = {
  name: "countdown",
  description: "Count down from N",
  execute: async function* (args) {
    const n = parseInt(args[0] ?? "3", 10)
    for (let i = n; i > 0; i--) {
      yield [{ text: `  ${i}...`, color: "chart-4" }]
      await new Promise((r) => setTimeout(r, 1000))
    }
    return {
      output: [[{ text: "  Go!", color: "main" }]],
    }
  },
}
0