Terminal (TUI)

The pa command runs Posit Assistant as a terminal user interface (TUI). It features a rich interactive mode with image support, as well as a headless mode for scripting and automation.

Interactive pa session in the terminal

Interactive Mode

Run pa with no prompt to start an interactive session:

pa

The interactive TUI provides a full chat experience in your terminal — markdown rendering, syntax-highlighted code blocks, tool confirmation dialogs, and inline images.

Flags

FlagDescription
-m <model>Model to use, in provider/model-id format.
--autoEnable Auto mode.
--yoloSkip tool confirmations (enable YOLO mode).
-vEnable debug logging.
-vvEnable trace logging.
-h, --helpShow help.

Examples

pa -m positai/claude-sonnet-4-6
pa --auto
pa --yolo

Images in the Terminal

When the assistant generates plots or works with images, the TUI renders them directly in your terminal. It automatically detects your terminal’s graphics capabilities and picks the best available protocol:

ProtocolTerminals
KittyKitty, Ghostty, and terminals supporting the Kitty graphics protocol
SixeliTerm2, xterm (with sixel enabled), mlterm, foot, and others
ANSI artAny terminal (fallback — renders images as colored block characters)

If none of the graphics protocols are supported, images are rendered using a lower-quality ANSI art fallback using block characters.

Posit Assistant TUI displaying data and an R plot in the terminal

You can Click or press Space on an image while focused to expand it in a full-screen viewer. Click or press Space again to close.

💡 Positron and VS Code

If you’re running pa in the Positron or VS Code integrated terminal, enable image support with these settings: "terminal.integrated.enableImages": true and "terminal.integrated.gpuAcceleration": "on".

Headless Mode

Pass a prompt as an argument to run in headless mode. The assistant processes the prompt, streams the response to stdout, and exits.

pa "What is the capital of France?"

Headless mode is designed for scripting and automation. The conversation ID is printed to stderr for reference.

Flags

All interactive flags are available, plus:

FlagDescription
--id <id>Conversation ID for resuming a previous conversation.

Examples

# Simple question
pa "Summarize the data in sales.csv"

# Use a specific model
pa -m positai/claude-sonnet-4-6 "Explain this error"

# Classifier-based approval
pa --auto "Run the project tests and summarize any failures; do not publish or push."

# Resume a conversation
pa --id abc123 "Now filter to Q4 only"

# Pipe input
echo "Fix this code" | pa

Behavior

  • Tool calls are auto-approved for safe operations; dangerous commands are denied (no interactive prompt in headless mode).
  • With --auto, a classifier reviews eligible tool calls. If it blocks a call or the review fails, that call is declined. See Auto Mode for details.
  • Use --yolo to auto-approve most tool calls, including ones the assistant flagged as dangerous. Deny rules remain enforced. Calls requiring a person’s confirmation and requests to run outside the sandbox are still denied.
  • Exit code is 0 on success, 1 on error.
  • Logs are written to ~/.posit/assistant/logs/headless.log (or ~/.positai/logs/headless.log in older versions) (only when -v or -vv is specified).
  • -- ends option parsing, so the argument after it is always the prompt, even one starting with -: pa -- "-1 is negative". Only one prompt argument may follow --.