TUI Commands

CLI commands for PraisonAI TUI

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

python
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.

Diagram

Input

Agent

Output

TUI CLI Commands

Complete reference for all TUI-related CLI commands.

Quick Start

  1. Launch the TUI
    bash
    praisonai tui launch --model gpt-4
  2. Run a headless simulation
    bash
    praisonai tui simulate test_script.yaml --assert

praisonai tui

Main TUI command group for interactive terminal interface.

launch

Launch the interactive TUI.

bash
praisonai tui launch [OPTIONS]

Options:

OptionShortDescription
--workspace-wWorkspace directory
--session-sResume session ID
--model-mDefault model
--debug-dEnable debug overlays
--log-jsonlWrite events to JSONL file
--profileEnable performance profiling

Examples:

bash
# 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
praisonai tui simulate SCRIPT [OPTIONS]

Arguments:

ArgumentDescription
SCRIPTPath to simulation script (YAML/JSON)

Options:

OptionDescription
--mock/--real-llmUse mock provider (default) or real LLM
--pretty/--jsonlOutput format
--assertValidate expected outcomes
--timeoutMax execution time (default: 60s)

Examples:

bash
# 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
praisonai tui snapshot [OPTIONS]

Options:

OptionShortDescription
--session-sFilter by session ID
--run-rFilter by run ID
--json-jOutput as JSON

Examples:

bash
# 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
praisonai tui trace ID [OPTIONS]

Arguments:

ArgumentDescription
IDSession or run ID to trace

Options:

OptionShortDescription
--follow-fFollow new events
--limit-nMax events to show (default: 50)

Examples:

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

CommandDescription
/diffShow file changes this session (--turn for the last turn, <file> for one file). Requires checkpoints.auto.
/undoRoll 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.

praisonai queue

Queue management commands.

ls

List queued runs.

bash
praisonai queue ls [OPTIONS]

Options:

OptionShortDescription
--state-sFilter by state (queued, running, succeeded, failed, cancelled)
--sessionFilter by session ID
--limit-nMaximum results (default: 20)
--json-jOutput as JSON

Examples:

bash
# 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
praisonai queue cancel RUN_ID

Arguments:

ArgumentDescription
RUN_IDRun ID to cancel (partial match supported)

Examples:

bash
# Cancel by full ID
praisonai queue cancel abc12345

# Cancel by partial ID
praisonai queue cancel abc1

retry

Retry a failed run.

bash
praisonai queue retry RUN_ID

Arguments:

ArgumentDescription
RUN_IDRun ID to retry

Examples:

bash
praisonai queue retry abc12345

clear

Clear all queued runs.

bash
praisonai queue clear [OPTIONS]

Options:

OptionShortDescription
--force-fSkip confirmation

Examples:

bash
# Clear with confirmation
praisonai queue clear

# Force clear
praisonai queue clear --force

stats

Show queue statistics.

bash
praisonai queue stats [OPTIONS]

Options:

OptionDescription
--sessionFilter by session ID

Examples:

bash
# Show all stats
praisonai queue stats

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

Environment Variables

VariableDescription
PRAISONAI_REAL_LLMSet to 1 to enable real LLM in simulations
PRAISONAI_TUI_DEBUGSet to 1 to enable debug mode
PRAISONAI_TUI_JSONLPath for JSONL event logging

Best Practices

Use simulation flags in CI

Run praisonai simulate with mock providers to avoid live API spend in pipelines.

Enable JSONL logging for audits

Set PRAISONAI_TUI_JSONL when you need structured event replay after failures.

Keep debug mode off in production

PRAISONAI_TUI_DEBUG=1 is for local troubleshooting only — it adds verbose noise.

Document slash commands for your team

Share a cheatsheet of /context, queue, and simulate commands so operators behave consistently.

Related