Chat

The chat command starts an interactive chat session with an AI agent.

As of PR #3818, praisonai chat runs its resident split-pane TUI directly from pip install praisonai-code — no wrapper required. Install the full praisonai wrapper only for gateway/bot channels.

Usage

praisonai chat [OPTIONS] [PROMPT]

Arguments

Argument	Description
`PROMPT`	Initial prompt for the chat session

Options

Option	Short	Description	Default
`--model`	`-m`	LLM model to use	provider-aware default
`--verbose`	`-v`	Verbose output	`false`
`--memory`		Enable memory persistence	`false`
`--tools`	`-t`	Comma-separated tool names (e.g. `web_search,github`) or a `tools.py` file path
`--user-id`		User ID for memory isolation
`--session`	`-s`	Session ID to resume
`--workspace`	`-w`	Workspace directory	current dir
`--debug`		Enable debug logging to `~/.praisonai/async_tui_debug.log`	`false`
`--safe` / `--no-safe`		Safe mode: require approval for file writes and commands (default: on). Use `--no-safe` to disable.	`true`
`--autonomy/--no-autonomy`		Enable agent autonomy for complex tasks	`true`
`--ui-backend`		UI backend: `auto`, `plain`, `rich`, `mg`	`auto`
`--json`		Output JSON (forces plain backend)	`false`
`--no-color`		Disable colors	`false`
`--theme`		UI theme: `default`, `dark`, `light`, `minimal`	`default`
`--compact`		Compact output mode	`false`
`--no-rules`		Disable auto-injection of project instruction files	`false`
`--no-context`		Disable AGENTS.md/CLAUDE.md auto-loading into system prompt	`false`
`--append-system-prompt`		Append text (literal or `@file`) to the system prompt for this invocation only. Env fallback: `PRAISONAI_APPEND_SYSTEM_PROMPT`. Never persisted. See Append System Prompt.	`None`
`--pure` / `--no-plugins`		Skip discovery/loading of external plugins for this run only (equivalent to `PRAISONAI_NO_PLUGINS=1`); persisted enable/disable state is unchanged.	`false`
`--append-system-prompt`		Append text (or `@file`) to the system prompt for this invocation only. Env fallback: `PRAISONAI_APPEND_SYSTEM_PROMPT`. See Append System Prompt.

Pass --pure (alias --no-plugins) to skip external-plugin discovery for a single run without touching your saved enable/disable state — see Pure Mode.

praisonai chat with no --model picks a default that matches your active provider credential — it no longer always falls back to gpt-4o-mini. See Setup → What happens if you skip --model for the precedence ladder.

Append to the system prompt

--append-system-prompt adds a one-off suffix to the assembled system prompt for a single chat session. It is never persisted and disappears when the process exits.

# Literal text
praisonai chat --append-system-prompt "Always answer in French"

# Read the suffix from a file (@file form)
praisonai chat --append-system-prompt @policy.md

Omit the flag and set the environment variable instead — handy for CI:

export PRAISONAI_APPEND_SYSTEM_PROMPT="Reply in strict JSON, no prose."
praisonai chat

See Append System Prompt for the full behaviour.

Piped Input

praisonai chat accepts piped stdin as an initial prompt seed.

echo "$STACKTRACE" | praisonai chat "Explain this"

Prompt argument is merged first, piped body second. The interactive REPL still opens for follow-up turns. See Piped Input.

First-run credential gate

praisonai chat routes first-run onboarding through the shared credential gate, so a keyless newcomer is offered the setup wizard (interactive) or exits with a hint (headless) instead of dead-ending on a raw provider error. The model resolver runs before the gate — explicit --model > most-recently-used > provider-aware default — so onboarding validates the exact model the TUI will dispatch. Headless is triggered by --json or piped stdin — chat has no -p flag. The interactive TUI path only runs the gate when the wrapper is present; on a standalone pip install praisonai-code (no wrapper), interactive praisonai chat (no prompt) delegates to the wrapper-resident TUI, which surfaces its own install hint. Single-prompt chat "…" always runs the gate.

Situation	Outcome
Configured	Runs normally with the resolved model.
Keyless + reachable local endpoint (no `--model`)	Adopts the local model; one-line stderr notice; continues.
Keyless + `--json` OR piped stdin	Exits `1` with `Error: No API key configured. Run: praisonai setup`.
Keyless + interactive TTY + wrapper installed	Prompts `Would you like to run the setup wizard now?`.
Keyless + interactive TTY + standalone `praisonai-code` (no wrapper)	Gate is skipped; TUI surfaces its own `pip install praisonai[tui]` hint.

Interactive TTY
Headless (--json)
Keyless + local Ollama

$ praisonai chat "add a test for foo"
No API key configured.
Would you like to run the setup wizard now? [Y/n]: Y
🚀 PraisonAI Setup Wizard
Choose your LLM provider: 1
Enter API key (hidden): ****
Verifying your setup...
✅ Verified — your agent is working!
[chat session starts]

$ praisonai chat --json "add a test for foo"
Error: No API key configured. Run: praisonai setup
or set environment variables like OPENAI_API_KEY
(a running local endpoint such as Ollama would be used automatically)
$ echo $?
1

$ praisonai chat "add a test for foo"
No cloud key found; using local model ollama/llama3.2. Run `praisonai setup` to add a hosted provider.
[chat session starts against local Ollama]

See First-run Onboarding for the full flow and Setup for the wizard.

Examples

Start a chat session

praisonai chat

Chat with initial prompt

praisonai chat "Hello, how can you help me today?"

Chat with specific model

praisonai chat --model gpt-4o "Explain machine learning"

Chat with memory enabled

praisonai chat --memory "Remember my name is Alice"

Resume a previous session

praisonai chat --session abc123

Use plain text output (no colors)

praisonai chat --ui-backend plain "What is 2+2?"

Output as JSON

praisonai chat --json "Summarize this text"

Use middle-ground UI (enhanced streaming)

praisonai chat --ui-backend mg

Append a one-off instruction (per invocation)

praisonai chat --append-system-prompt "Be brief. No preamble."

The text is appended to the end of the system prompt for this session only — never written to any agent file. See Append System Prompt.

Chat without auto-loaded instructions

praisonai chat --no-rules "Hello, ignore project rules"

The chat session normally inherits AGENTS.md/CLAUDE.md/PRAISON.md from the working directory. --no-rules runs the assistant with only its built-in instructions. The env-var equivalent is PRAISON_NO_RULES=true (1 / true / yes, case-insensitive), which also skips the on-demand subtree hook. Related env vars:

PRAISON_NO_RULES=true — same as --no-rules; skips both the up-front load and the subtree hook.
PRAISON_NO_CONTEXT=true — same as --no-context; skips only the up-front AGENTS.md/CLAUDE.md walk-up.
PRAISON_CONTEXT_BUDGET=<int> — char budget for the subtree hook (0, missing, or non-integer disables the cap). Applies to both chat and run. See Context Files → Token budget.

Exit codes

praisonai chat returns a non-zero exit code on failure so shell scripts and CI can detect problems without parsing stderr.

Exit code	Meaning
`0`	Prompt executed successfully.
`1`	Authentication failed (invalid or missing API key), the agent raised an exception, or a profiled run finished with no response and a logged auth error.

Exit-code semantics apply to single-prompt / non-interactive invocations (praisonai chat "..." and praisonai chat --profile ...). The interactive TUI (praisonai chat with no prompt) always exits 0 when you leave the session.

Headless-keyless invocations (--json or piped stdin) now exit 1 at the first-run credential gate with a setup hint (Run: praisonai setup) — not just a bare “authentication failed”.

Detect failures in a script

if ! praisonai chat "Summarize the changelog" >/dev/null; then
  echo "chat failed — check credentials or provider status" >&2
  exit 1
fi

CI example (GitHub Actions)

- name: Smoke-test chat
  run: praisonai chat "Say hello" > /tmp/chat.out
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

The step fails automatically if the key is invalid — no extra parsing needed.

Project context

By default, praisonai chat walks up from the current directory to your git root and prepends any AGENTS.md / CLAUDE.md / agents.md / .agents/AGENTS.md it finds to the agent’s system prompt, layered on top of ~/.praisonai/AGENTS.md. Pass --no-context (or set PRAISON_NO_CONTEXT=true) to disable. See Context Files for details.

UI Backends

The --ui-backend flag controls how output is rendered:

Backend	Description
`auto`	Auto-select best available (default)
`plain`	Plain text, no colors, works everywhere
`rich`	Rich formatting with colors and panels
`mg`	Middle-ground: enhanced streaming with no flicker

Environment variable: Set PRAISONAI_UI_SAFE=1 to force plain backend.

Interactive Commands

During a chat session, you can use these commands:

Command	Description
`/help`	Show available commands
`/exit`, `/quit`	Exit the chat session
`/clear`	Clear conversation history
`/new`	Start new conversation
`/session`	Show current session info
`/sessions`	List all saved sessions
`/continue`	Continue most recent session
`/model [name]`	Show or change model
`/cost`	Show token usage and cost
`/history`	Show conversation history
`/export [file]`	Export conversation to file
`/import <file>`	Import conversation from file
`/status`	Show ACP/LSP runtime status
`/auto`	Toggle autonomy mode (auto-delegate complex tasks)
`/debug`	Toggle debug logging to `~/.praisonai/async_tui_debug.log`
`/plan <task>`	Create a step-by-step plan for a task
`/handoff <type> <task>`	Delegate to specialized agent (code/research/review/docs)
`/compact`	Toggle compact output mode
`/multiline`	Toggle multiline input mode
`/files`	List workspace files for @ mentions
`/queue`	Show pending prompts in queue

Ctrl-C during a running turn now stops the agent cooperatively — the partial output is kept and the warm agent / session survive so you can immediately type the next prompt. Press twice to bail out of a stuck step. See Interrupting a Turn for the full behaviour.

Quick Start

Running praisonai with no arguments starts interactive mode:

praisonai

This is equivalent to praisonai chat.

Features

The interactive chat mode includes:

ASCII Art Logo - Beautiful PraisonAI branding on startup
Status Bar - Shows model, session info, and keyboard shortcuts
Auto-completion - Tab completion for commands and file paths
Command History - Navigate previous commands with arrow keys
Markdown Rendering - Rich formatted responses with syntax highlighting
Streaming Output - Real-time response streaming

CLI

Usage

Arguments

Options

Append to the system prompt

Piped Input

First-run credential gate

Examples

Start a chat session

Chat with initial prompt

Chat with specific model

Chat with memory enabled

Resume a previous session

Use plain text output (no colors)

Output as JSON

Use middle-ground UI (enhanced streaming)

Append a one-off instruction (per invocation)

Chat without auto-loaded instructions

Exit codes

Detect failures in a script

CI example (GitHub Actions)

Project context

UI Backends

Interactive Commands

Quick Start

Features

See Also

​Usage

​Arguments

​Options

​Append to the system prompt

​Piped Input

​First-run credential gate

​Examples

​Start a chat session

​Chat with initial prompt

​Chat with specific model

​Chat with memory enabled

​Resume a previous session

​Use plain text output (no colors)

​Output as JSON

​Use middle-ground UI (enhanced streaming)

​Append a one-off instruction (per invocation)

​Chat without auto-loaded instructions

​Exit codes

​Detect failures in a script

​CI example (GitHub Actions)

​Project context

​UI Backends

​Interactive Commands

​Quick Start

​Features

​See Also

Usage

Arguments

Options

Append to the system prompt

Piped Input

First-run credential gate

Examples

Start a chat session

Chat with initial prompt

Chat with specific model

Chat with memory enabled

Resume a previous session

Use plain text output (no colors)

Output as JSON

Use middle-ground UI (enhanced streaming)

Append a one-off instruction (per invocation)

Chat without auto-loaded instructions

Exit codes

Detect failures in a script

CI example (GitHub Actions)

Project context

UI Backends

Interactive Commands

Quick Start

Features

See Also