> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TUI Commands

> CLI commands for PraisonAI TUI

# TUI CLI Commands

Complete reference for all TUI-related CLI commands.

## praisonai tui

Main TUI command group for interactive terminal interface.

### launch

Launch the interactive TUI.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai tui launch [OPTIONS]
```

**Options:**

| Option        | Short | Description                  |
| ------------- | ----- | ---------------------------- |
| `--workspace` | `-w`  | Workspace directory          |
| `--session`   | `-s`  | Resume session ID            |
| `--model`     | `-m`  | Default model                |
| `--debug`     | `-d`  | Enable debug overlays        |
| `--log-jsonl` |       | Write events to JSONL file   |
| `--profile`   |       | Enable performance profiling |

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Basic launch
praisonai tui launch

# Launch with specific model
praisonai tui launch --model gpt-4

# Resume a session
praisonai tui launch --session abc123

# Launch with debug logging
praisonai tui launch --debug --log-jsonl ./events.jsonl
```

### simulate

Run a headless TUI simulation script for testing.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai tui simulate SCRIPT [OPTIONS]
```

**Arguments:**

| Argument | Description                           |
| -------- | ------------------------------------- |
| `SCRIPT` | Path to simulation script (YAML/JSON) |

**Options:**

| Option              | Description                             |
| ------------------- | --------------------------------------- |
| `--mock/--real-llm` | Use mock provider (default) or real LLM |
| `--pretty/--jsonl`  | Output format                           |
| `--assert`          | Validate expected outcomes              |
| `--timeout`         | Max execution time (default: 60s)       |

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Run simulation with mock provider
praisonai tui simulate test_script.yaml

# Run with real LLM (requires PRAISONAI_REAL_LLM=1)
PRAISONAI_REAL_LLM=1 praisonai tui simulate test_script.yaml --real-llm

# Run with assertions
praisonai tui simulate test_script.yaml --assert
```

### snapshot

Print a TUI-like snapshot of current state.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai tui snapshot [OPTIONS]
```

**Options:**

| Option      | Short | Description          |
| ----------- | ----- | -------------------- |
| `--session` | `-s`  | Filter by session ID |
| `--run`     | `-r`  | Filter by run ID     |
| `--json`    | `-j`  | Output as JSON       |

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Get current snapshot
praisonai tui snapshot

# Get snapshot for specific session
praisonai tui snapshot --session abc123

# Get JSON output
praisonai tui snapshot --json
```

### trace

Replay events from persistence like a timeline.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai tui trace ID [OPTIONS]
```

**Arguments:**

| Argument | Description                |
| -------- | -------------------------- |
| `ID`     | Session or run ID to trace |

**Options:**

| Option     | Short | Description                      |
| ---------- | ----- | -------------------------------- |
| `--follow` | `-f`  | Follow new events                |
| `--limit`  | `-n`  | Max events to show (default: 50) |

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Trace a session
praisonai tui trace abc123

# Follow events in real-time
praisonai tui trace abc123 --follow

# Limit to last 10 events
praisonai tui trace abc123 --limit 10
```

## praisonai queue

Queue management commands.

### ls

List queued runs.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai queue ls [OPTIONS]
```

**Options:**

| Option      | Short | Description                                                     |
| ----------- | ----- | --------------------------------------------------------------- |
| `--state`   | `-s`  | Filter by state (queued, running, succeeded, failed, cancelled) |
| `--session` |       | Filter by session ID                                            |
| `--limit`   | `-n`  | Maximum results (default: 20)                                   |
| `--json`    | `-j`  | Output as JSON                                                  |

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# List all runs
praisonai queue ls

# List only running
praisonai queue ls --state running

# List with JSON output
praisonai queue ls --json
```

### cancel

Cancel a queued or running run.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai queue cancel RUN_ID
```

**Arguments:**

| Argument | Description                                |
| -------- | ------------------------------------------ |
| `RUN_ID` | Run ID to cancel (partial match supported) |

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Cancel by full ID
praisonai queue cancel abc12345

# Cancel by partial ID
praisonai queue cancel abc1
```

### retry

Retry a failed run.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai queue retry RUN_ID
```

**Arguments:**

| Argument | Description     |
| -------- | --------------- |
| `RUN_ID` | Run ID to retry |

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai queue retry abc12345
```

### clear

Clear all queued runs.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai queue clear [OPTIONS]
```

**Options:**

| Option    | Short | Description       |
| --------- | ----- | ----------------- |
| `--force` | `-f`  | Skip confirmation |

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Clear with confirmation
praisonai queue clear

# Force clear
praisonai queue clear --force
```

### stats

Show queue statistics.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai queue stats [OPTIONS]
```

**Options:**

| Option      | Description          |
| ----------- | -------------------- |
| `--session` | Filter by session ID |

**Examples:**

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Show all stats
praisonai queue stats

# Show stats for session
praisonai queue stats --session abc123
```

## Environment Variables

| Variable              | Description                                  |
| --------------------- | -------------------------------------------- |
| `PRAISONAI_REAL_LLM`  | Set to `1` to enable real LLM in simulations |
| `PRAISONAI_TUI_DEBUG` | Set to `1` to enable debug mode              |
| `PRAISONAI_TUI_JSONL` | Path for JSONL event logging                 |