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.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.
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.
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.
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.
- Interactive TTY
- Headless (--json)
- Keyless + local Ollama
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)
Chat with guardrails
run/YAML/Python. See Capability options.
Chat grounded in your knowledge sources
list[str] and passed as the Agent’s knowledge=.
Chat with planning and web together
Chat without auto-loaded instructions
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-frontAGENTS.md/CLAUDE.mdwalk-up.PRAISON_CONTEXT_BUDGET=<int>— char budget for the subtree hook (0, missing, or non-integer disables the cap). Applies to bothchatandrun. 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)
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
Runningpraisonai with no arguments starts interactive mode:
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
- Interactive TUI - Full TUI interface
- Session - Session management
- Memory - Memory management

