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

# TUI Commands

> CLI commands for PraisonAI TUI

Slash commands and CLI flags control models, sessions, and layout inside the TUI.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

agent = Agent(name="tui-assistant", instructions="Use TUI slash commands effectively.")
agent.start("Which /model should I pick for fast replies?")
```

The user types slash commands such as `/help` and `/model` while the agent streams responses in the TUI.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    U[Input] --> A[Agent]
    A --> O[Output]

    classDef agent fill:#8B0000,color:#fff
    classDef tool fill:#189AB4,color:#fff

    class A agent
    class U,O tool
```

# TUI CLI Commands

Complete reference for all TUI-related CLI commands.

## Quick Start

<Steps>
  <Step title="Launch the TUI">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai tui launch --model gpt-4
    ```
  </Step>

  <Step title="Run a headless simulation">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai tui simulate test_script.yaml --assert
    ```
  </Step>
</Steps>

## 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
```

## In-session slash commands (checkpoint-aware)

Inside a running TUI session, `/diff` and `/undo` inspect and roll back workspace file changes.

| Command | Description |
| - | - |
| `/diff` | Show file changes this session (`--turn` for the last turn, `<file>` for one file). Requires `checkpoints.auto`. |
| `/undo` | Roll back the last turn's file changes (and conversation history when a session store is wired). Requires `checkpoints.auto`. |

These commands are also available in the legacy `praisonai code` REPL and are backed by the same engine, so behaviour is identical.

<Note>
  See [Checkpoints](/docs/features/checkpoints) for the full API and config precedence, and [Slash Commands](/docs/cli/slash-commands) for the slash-command overview.
</Note>

## 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 |

## Best Practices

<AccordionGroup>
  <Accordion title="Use simulation flags in CI">
    Run `praisonai simulate` with mock providers to avoid live API spend in pipelines.
  </Accordion>

  <Accordion title="Enable JSONL logging for audits">
    Set `PRAISONAI_TUI_JSONL` when you need structured event replay after failures.
  </Accordion>

  <Accordion title="Keep debug mode off in production">
    `PRAISONAI_TUI_DEBUG=1` is for local troubleshooting only — it adds verbose noise.
  </Accordion>

  <Accordion title="Document slash commands for your team">
    Share a cheatsheet of `/context`, queue, and simulate commands so operators behave consistently.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="TUI Overview" icon="terminal" href="/docs/features/tui/overview">
    Interactive terminal interface
  </Card>

  <Card title="TUI Simulation" icon="flask-vial" href="/docs/features/tui/simulation">
    Headless testing and CI
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.