Chat

Interactive chat mode with AI agents

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

Usage

praisonai chat [OPTIONS] [PROMPT]

Arguments

Options

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:

$ praisonai chat "hi" --theme dark --no-color
warning: praisonai chat does not implement --theme, --no-color yet; the value was ignored.

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

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.

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.

# Guardrails preset
praisonai chat --guardrails strict "Draft a public API note"

# Guardrails with a validator prompt (comma survives — one string, not a list)
praisonai chat --guardrails "Be accurate, cite sources" "Summarise the release"

# Knowledge — comma-separated sources are split into a list
praisonai chat --knowledge docs/,notes.md "What did we decide about caching?"

# Planning + web together
praisonai chat --planning auto --web true "Compare Postgres vs SQLite for our use case"

# Reflection loop for a self-critique pass
praisonai chat --reflection true "Write a launch tweet"

# Explicit disable (bool coercion from string)
praisonai chat --caching false "One-off question, don't cache the answer"

The flags flow from the CLI through the async TUI onto the Agent constructor.

Restricting tools in an interactive session

By default, praisonai chat loads the full interactive tool set (ACP + LSP + interactive helpers). Pass --tools or --toolset to narrow that set to exactly the callables you want the session to have — resolved through the same ToolResolver path as praisonai run, YAML, and Python.

When neither flag is supplied, the interactive default tool groups load unchanged. When at least one flag is supplied, the resolved callables replace the defaults so the flag is a genuine restriction, not merely an addition.

Examples

# Restrict interactive chat to a single named tool
praisonai chat --tools internet_search

# Restrict interactive chat to the "web" toolset group
praisonai chat --toolset web

# Combine a toolset group with an extra named tool
praisonai chat --toolset web --tools github

# Load callables from a local tools.py file
praisonai chat --tools ./my_tools.py

# Works in single-prompt profiled mode too
praisonai chat "Summarise renewable energy news" --profile --tools internet_search --toolset web

How the flags flow into the session

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.

$ 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

Output as JSON

praisonai chat --json "Summarize this text"

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

praisonai chat --guardrails strict "Draft a public API note"

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

Chat grounded in your knowledge sources

praisonai chat --knowledge docs/,notes.md "What did we decide about caching?"

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

Chat with planning and web together

praisonai chat --planning auto --web true "Compare Postgres vs SQLite for our use case"

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.

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.

Interactive Commands

During a chat session, you can use these commands:

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

See Also

• Interactive TUI – Full TUI interface
• Session – Session management
• Memory – Memory management