Basic Usage¶
Perspt offers three primary modes of interaction: the TUI (rich interactive terminal UI), simple-chat (plain-text streaming for pipeline integration), and Agent (self-stabilizing autonomous multi-agent coding workflows).
Launching the TUI¶
# Auto-detect provider from env keys
perspt
# Explicit model (provider comes from config or env detection)
perspt chat --model claude-fable
# Use a specific config file
perspt --config ./config.toml chat --model gpt-5.5
The TUI provides:
Markdown rendering (code blocks, headers, lists, bold, italic)
Premium ASCII table rendering with multi-line cell wrapping
Inline LaTeX math transpilation to styled Unicode equations (bold and cyan)
Real-time response streaming
Scroll navigation
Status bar (provider, model, streaming indicator, and reasoning toggles)
Keyboard Shortcuts¶
Key |
Action |
|---|---|
Enter |
Send message |
Ctrl+J |
Insert newline in input |
Page Up / Down |
Scroll chat history by 10 lines |
Shift+Up / Down |
Scroll chat history by 1 line |
Ctrl+Up / Down |
Scroll chat history by 1 line |
Home / End |
Go to start / end of input line |
Ctrl+C / Ctrl+Q |
Quit |
Ctrl+R |
Toggle inner reasoning process display |
Ctrl+A / Ctrl+E |
Go to start / end of input line |
Ctrl+B / Ctrl+F |
Move cursor left / right |
Ctrl+D / Ctrl+H |
Delete / Backspace character |
Ctrl+K / Ctrl+U |
Kill to end / start of line |
Ctrl+W |
Delete word before cursor |
Slash Commands (Directives)¶
Both CLI and TUI modes support slash commands typed directly in the input box:
Command |
Description |
|---|---|
|
Exit the application session |
|
Reset the active conversation history |
|
Switch the active LLM model on the fly |
|
Export full conversation history to a markdown file |
|
Show MCP configuration state, discovery failures, policy rejections, and admitted operation names without contacting the model |
|
Answer a pending MCP elicitation request |
|
Print the menu of available slash commands |
The chat TUI can use latest MCP tools, resources, prompts, completions,
sampling, elicitation, subscriptions, and tasks from any [[external_tools]]
server entry in config.toml with modes = ["chat"] or
modes = ["agent", "chat"] is considered for read-only admission. Every
allowed remote tool also needs an exact local policy table. Tool activity is
shown as a concise transient status only while a call is active. MCP protocol
events, arguments, results, discovery notices, and subscription traces do not
become conversation or reasoning content. The selected model chooses an
admitted tool automatically when needed; /mcp is the explicit diagnostic
surface. Tool results are labeled as untrusted content before returning to the
model. Ctrl+R continues to control genuine model reasoning, including
tool-aware turns. Unicode and multiline terminal clipboard paste is inserted
at the input cursor. See Model Context Protocol (MCP) for configuration and the security
boundary.
Simple CLI Mode¶
For a minimal text interface suitable for piping and logging:
perspt simple-chat
perspt simple-chat --model gpt-4o-mini
perspt simple-chat --log-file session.txt
Type your message, press Enter. Responses stream to stdout. Type exit or
press Ctrl+D to quit.
Autonomous Agent Mode¶
For complex software engineering and coding jobs that require self-stabilizing, multi-file edits:
perspt agent "Implement a parsing logic for custom CSV formats in src/csv.rs"
This starts the multi-agent orchestration loop. The system automatically plans, executes, and verifies the changes using local verification commands. You can specify custom models and configure validation parameters to match your codebase. Refer to Agent Mode for details.
Provider Auto-Detection¶
Perspt checks environment variables in this priority order:
Env Variable |
Provider |
Default Model |
|---|---|---|
|
Vertex AI |
|
|
Gemini |
|
|
OpenAI |
|
|
Anthropic |
|
|
Groq |
|
|
Cohere |
|
|
xAI |
|
|
DeepSeek |
|
(none) |
Ollama (local) |
|
See Providers for full provider details.