Skip to main content
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

Arguments

Options

As of PR #4912, the bare praisonai interactive launch also accepts --continue / --session / --fork — you can jump into the interactive TUI on a resumed session without going through praisonai chat. See Interactive TUI → Launching with a resumed session.
Eight of the capability options (--knowledge, --guardrails, --web, --reflection, --planning, --context, --execution, --caching) now reach the Agent exactly as they do from run/YAML/Python — see Capability options. Four flags remain unwired (--hooks, --ui-backend, --no-color, --theme); passing one prints a one-line stderr warning and the command still exits 0. See PraisonAI PR #4891.

Options not yet implemented

praisonai chat declares these flags in its help output because the wider CLI shares one option set, but the chat runtime does not consume them yet. Passing one produces a warning on stderr and is otherwise a no-op:
Behaviour change (PraisonAI PR #4943, also #4946). Exactly four options remain unwired — --tools, --toolset, --user-id, --output. They emit a runtime warning instead of being silently accepted, and a repo AST test (_UNWIRED_CHAT_OPTIONS) pins the list in both directions so it cannot under-report again. In the same sweep, --file, --continue, --no-acp, and --no-lsp were genuinely wired: --file forwards attachments to the model through the shared attachments loader (identical to praisonai code --file), and the other three behave like their praisonai code counterparts.
The warning names only options the user actually typed — an untouched default is silent. When one of these is wired up, the warning will drop it automatically (a repo test pins the list to the runtime body).
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.
Omit the flag and set the environment variable instead — handy for CI:
See Append System Prompt for the full behaviour.

Capability options

praisonai chat honours the same capability options as run/YAML/Python — guardrails, knowledge, web, reflection, planning, context, execution, and caching. Each flag maps onto the matching Agent(...) parameter after light coercion. Pick the flag that matches your goal. Every capability flag works in a single command.
The flags flow from the CLI through the async TUI onto the Agent constructor.
Only --knowledge splits a comma-containing value into a list. --guardrails "Be accurate, cite sources" reaches the Agent as one validator prompt, not two — comma-containing prompts survive intact on every other capability flag.

Piped Input

praisonai chat accepts piped stdin as an initial prompt seed.
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.
See First-run Onboarding for the full flow and Setup for the wizard.

Examples

Start a chat session

Chat with initial prompt

Chat with specific model

Chat with memory enabled

Resume a previous session

Output as JSON

Append a one-off instruction (per invocation)

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 with guardrails

The guardrail chain reaches the Agent just as it does from run/YAML/Python. See Capability options.

Chat grounded in your knowledge sources

Comma-separated paths are split into a list[str] and passed as the Agent’s knowledge=.

Chat with planning and web together

Chat without auto-loaded instructions

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

CI example (GitHub Actions)

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.

Interactive Commands

During a chat session, you can use these commands:
As of PR #4943, /clear, /new, /continue, and /import consistently reset or restore both the screen and the agent’s conversation history — they route through the same persist + rebuild path. Previously /clear and /new cleared only the transcript while the agent kept the old context, and /import printed Imported N messages but answered as if none existed.
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:
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

See Also