Slash Commands

PraisonAI CLI provides interactive slash commands for quick actions during your AI coding sessions. Inspired by Gemini CLI, Codex CLI, and Claude Code, these commands give you powerful control without leaving the terminal.

Overview

Slash commands start with / and provide quick access to common operations in interactive mode.

❯ /help
❯ /tools
❯ /clear
❯ /exit

/cmd invokes registered commands. For a one-shot shell command in the same session, use !cmd (or !!cmd to attach output as context) — see Shell Escape. The ! prefix bypasses the command registry entirely.

Available Commands (Interactive Mode)

When using praisonai chat, these commands are available:

Command	Description
`/help`	Show available commands and features
`/exit`	Exit interactive mode
`/quit`	Exit interactive mode (alias)
`/clear`	Clear the screen
`/tools`	List available tools
`/profile`	Toggle profiling (show timing breakdown)
`/model [name]`	Show or change current model
`/plan`	Toggle read-only plan mode (`/plan off` to exit; `/plan <task>` to plan)
`/code-review [file] [--staged]`	Review the uncommitted diff for bugs — see Code Review & Security Review
`/security-review [file] [--staged]`	Review the uncommitted diff against a security rubric (injection, authz, secrets, path traversal, SSRF, crypto)
`/btw`	Ask a side question in a throwaway context (`--keep` to note it in history) — see /btw side question
`/stats`	Show session statistics (tokens, cost) — every REPL surface
`/compact`	Compress conversation history
`/undo`	Undo last turn (files + conversation when checkpointing on — on by default in interactive)
`/revert [n]`	Revert the last N turns (files + conversation)
`/export [file]`	Export the conversation to a file (session-backed or in-memory fallback)
`/queue`	Show queued messages
`/queue clear`	Clear the message queue
`/queue remove N`	Remove message at index N
`/tasks`	List background tasks (id, name, status, progress)
`/tasks <id>`	Show detail for one background task (incl. result/error)
`/tasks cancel <id>`	Cancel a running background task

Built-in Tools

Interactive mode includes 5 built-in tools that the AI can use:

Tool	Description	Risk Level
`read_file`	Read contents of a file	Low
`write_file`	Write content to a file	High (requires approval)
`list_files`	List files in a directory	Low
`execute_command`	Run shell commands	Critical (requires approval)
`internet_search`	Search the web	Low

❯ /tools
Available tools: 5
  • read_file
  • write_file
  • list_files
  • execute_command
  • internet_search

Usage Examples

Starting Interactive Mode

# Start interactive mode
praisonai chat

# Or use short flag
praisonai -i

Using Help

❯ /help

Commands:
  /help          - Show this help
  /exit          - Exit interactive mode
  /clear         - Clear screen
  /tools         - List available tools
  /profile       - Toggle profiling (show timing breakdown)
  /model [name]  - Show or change current model
  /code-review [file|--staged]     - Review the uncommitted diff for bugs (read-only)
  /security-review [file|--staged] - Audit the uncommitted diff for security issues (read-only)
  /stats         - Show session statistics (tokens, cost)
  /compact       - Compress conversation history
  /undo          - Undo last turn (files + conversation when checkpointing on)
  /revert [n]    - Revert the last N turns (files + conversation)
  /queue         - Show queued messages
  /queue clear   - Clear message queue

@ Mentions:
  @file.txt      - Include file content in prompt
  @src/          - Include directory listing

Features:
  • File operations (read, write, list)
  • Shell command execution
  • Web search
  • Context compression for long sessions
  • Queue messages while agent is processing

Listing Tools

❯ /tools
Available tools: 5
  • read_file
  • write_file
  • list_files
  • execute_command
  • internet_search

Using Tools via Natural Language

# List files
❯ list files in current folder
Here are the files: README.md, main.py, config.yaml

# Read a file
❯ read the contents of README.md
The file contains: # My Project...

# Search the web
❯ search the web for latest AI news
Here are the results from web search...

Python API

You can also use slash commands programmatically:

from praisonai.cli.features import SlashCommandHandler

# Create handler
handler = SlashCommandHandler()

# Check if input is a command
if handler.is_command("/help"):
    result = handler.execute("/help")
    print(result)

# Get completions for auto-complete
completions = handler.get_completions("/he")
# Returns: ["/help"]

Custom Commands

File-based commands in .praisonai/commands/*.md (and .claude/commands/*.md / .agents/commands/*.md when present) auto-register in interactive mode with kind=CommandKind.CUSTOM. Disable discovery with SlashCommandHandler(discover_custom=False). See Custom Agents & Commands.

Unified Command Registry

Inside praisonai code (and the REPL / async TUI) a single CommandRegistry aggregates every command source into one /name namespace — built-ins, your .praisonai/commands/*.md files (plus .claude/commands/*.md and .agents/commands/*.md when present), skills, MCP prompts, and pip-installed command packs all appear together.

Source	Where commands come from
`BuiltinCommandSource`	Built-in `/help`, `/undo`, `/sessions`, etc.
`CustomCommandSource`	`.praisonai/commands/*.md` files (same path as `praisonai run --command`)
`SkillCommandSource`	Skills exposed as `/name`
`MCPPromptCommandSource`	MCP prompts exposed as `/name`
`praisonai.commands` entry point	Any pip-installed command pack

Custom commands work inside `praisonai code`

Create .praisonai/commands/mydeploy.md:

Deploy to {{env}}: run tests, build the image, push to registry.

Then invoke it inside the interactive session:

> /mydeploy staging

This runs the exact interpolated template that praisonai run --command mydeploy staging would — full parity between interactive and CLI invocation.

/help lists every discovered command and command list --all shows the same unified namespace. Later sources override earlier ones on a name collision, matching user/project override semantics.

Ship a command pack as a pip package

[project.entry-points."praisonai.commands"]
my_commands = "my_package.commands:make_source"

The registry discovers it on start — no user code needed. A broken pack is logged and skipped, never taking down the registry. Register programmatic slash commands:

from praisonai.cli.features.slash_commands import (
    SlashCommand, SlashCommandHandler, CommandKind
)

# Define custom command
def my_command(args, context):
    return {"type": "custom", "message": f"Args: {args}"}

custom_cmd = SlashCommand(
    name="mycommand",
    description="My custom command",
    handler=my_command,
    kind=CommandKind.ACTION,
    aliases=["mc"]
)

# Register it
handler = SlashCommandHandler()
handler.register(custom_cmd)

# Use it
result = handler.execute("/mycommand arg1 arg2")

Command Context

Provide context for commands that need session data:

from praisonai.cli.features.slash_commands import CommandContext

# Create context with session data
context = CommandContext(
    total_tokens=5000,
    total_cost=0.015,
    prompt_count=10,
    current_model="gpt-4o",
    session_start_time=time.time() - 300
)

# Set context on handler
handler.set_context(context)

# Now /cost will show real data
result = handler.execute("/cost")

Integration with Interactive Mode

Slash commands are automatically available in interactive mode:

praisonai chat

>>> Hello, help me with my code
[AI responds...]

>>> /cost
Session: abc12345
Tokens: 1,500
Cost: $0.0045

>>> /model gpt-4o-mini
Model changed to: gpt-4o-mini

>>> /exit
Goodbye!

Command Reference

/help

Show help information.

/help              # Show all commands
/help <command>    # Show help for specific command

/cost

Display session cost and token statistics.

/cost              # Show full statistics

/model

Manage the AI model.

/model             # Show current model
/model <name>      # Change to specified model

/plan

Toggle a persistent read-only mode — writes, edits, deletions, and shell commands are denied until you leave the mode.

Usage	What it does
`/plan`	Toggle on/off. First call enters read-only mode; second call exits and restores your launch-time policy.
`/plan off`	Explicit exit. Writes/edits/commands are allowed again.
`/plan <task>`	Enter read-only mode and produce a step-by-step plan for `<task>` under enforcement. Run `/plan off` to execute.

> /plan
[PLAN] Plan mode enabled — read-only. Writes/edits/commands are denied until you /plan off.

> /plan refactor the auth module
[PLAN] Creating plan (read-only) for: refactor the auth module
...

> /plan off
Plan mode disabled. Writes/edits/commands are allowed again.

While plan mode is active, the status bar shows [PLAN].

/plan flips the live approval backend into PermissionMode.PLAN, which unconditionally denies write / edit / delete / bash / shell tool calls. Exiting restores the launch-time policy (e.g. accept-edits, bypass) — not default — so a session that started with --approval accept-edits keeps that policy after /plan off.Launch a session already in plan mode with praisonai chat --approval plan (or praisonai code --plan). See Permission Modes for the full mode reference.

Real-world flow:

Open on an unfamiliar codebase

Start praisonai chat with your default policy.

Enter read-only mode

Type /plan — the status bar flips to [PLAN] and writes/edits are denied.

Explore freely

Ask read src/auth/*.py and summarise the auth flow — the agent uses read-only tools only.

Plan a fix under enforcement

Type /plan design a fix for the token-refresh bug — the agent produces a step-by-step plan with no accidental edits mid-plan.

Exit and execute

Type /plan off — the status bar clears and your launch-time policy returns. Now apply the plan writes and edits normally.

/diff

Show workspace file changes made this session, from the session-start baseline to the working directory.

/diff              # all changes since session start
/diff --turn       # only the last turn's changes (alias: -t)
/diff <file>       # changes to a single file since session start

/diff is backed by the checkpoint engine, so it requires auto-checkpointing: set checkpoints.auto: true in config or PRAISONAI_CHECKPOINTS=on. When disabled, /diff prints an enable hint and does nothing else.

See Checkpoints for the underlying engine and the “In-session /diff” deep-dive, including the --turn vs. session-scope decision guide.

/commit

Commit changes with an AI-generated message.

/commit            # Auto-generate commit message
/commit "message"  # Use custom message

/profile

Toggle profiling to see timing breakdown.

/profile           # Toggle profiling on/off

When enabled, shows timing after each response:

─── Profiling ───
Import:      0.1ms
Agent setup: 0.3ms
LLM call:    1,234.5ms
Display:     15.2ms
Total:       1,250.1ms

/stats

Show session statistics.

/stats             # Show token usage and cost

Output:

Session Statistics
  Model:          gpt-4o-mini
  Requests:       5
  Input tokens:   1,234
  Output tokens:  2,567
  Total tokens:   3,801
  Estimated cost: $0.0023
  History turns:  10

/stats works on every REPL surface — the legacy REPL, the async TUI (praisonai code), and praisonai chat. In the async TUI it shares the same renderer as /cost, so both print the same panel and you don’t need to remember which command works where.

/compact

Compress conversation history to save tokens.

/compact           # Summarize older history

This command:

Keeps the last 2 conversation turns intact
Summarizes older turns using the LLM
Reduces token usage for long sessions

/undo

Undo the last turn. What /undo restores depends on whether checkpointing and the session store are wired in.

/undo              # roll back the last turn

Checkpointing	Session store	`/undo` effect
Off (default)	n/a	Removes the last assistant + user message pair from history. Workspace files untouched.
On, no session store	n/a	Restores workspace files to the previous turn’s checkpoint. Conversation history untouched (file-only fallback).
On, session store wired (default in `praisonai` interactive mode and `praisonai code`)	wired	Restores workspace files and rewinds `chat_history` to the message boundary captured at `checkpoint_turn()`. Diff preview shown first.

The deep-dive lives in Checkpoints → In-session /undo and /revert.

/revert

Revert the last N turns — files and conversation together. Mirrors /undo but takes a turn count.

/revert            # roll back the last 1 turn
/revert 3          # roll back the last 3 turns
/revert last       # explicit alias for the last 1 turn

A diff preview is shown before restore, and /revert refuses to run beyond the recorded turn count (Can only revert 1..N turn(s).). Checkpointing is on by default in praisonai interactive mode and praisonai code, so /revert works out of the box.

The deep-dive lives in Checkpoints → In-session /undo and /revert.

/export

Export the current conversation to a file — available in the legacy REPL (the surface praisonai code runs by default).

/export              # write to a default file (conversation.md)
/export out.md       # write to a caller-supplied path
/export out.json     # a .json path exports JSON

/export picks one of two paths automatically:

Path	When	Result
Session-backed	A session id resolves	Routes through the canonical `session export` renderer — byte-for-byte identical to `praisonai session export <id>` on the CLI.
In-memory fallback	No session is persisted (e.g. `--no-session`)	Writes the in-memory chat history so `/export` still produces a transcript instead of failing.

You don’t need to --session first — the fallback means /export always produces something useful. See praisonai session export for the same renderer on the CLI.

/queue

Manage the message queue. Queue messages while the AI agent is processing and they’ll be executed in order.

/queue             # Show all queued messages
/queue clear       # Clear the entire queue
/queue remove N    # Remove message at index N

Output when messages are queued:

❯ /queue
⏳ Processing...

Queued Messages (2):
  0. ↳ Add docstrings to the function
  1. ↳ Create unit tests

Use /queue clear to clear, /queue remove N to remove

Type new messages while the agent is processing. They’ll be queued and executed automatically in FIFO order.

/tasks

Inspect and cancel background tasks without leaving the conversation — parity with the CLI-only praisonai background list.

/tasks               # List background tasks (id, name, status, progress)
/tasks <id>          # Show detail for one task (incl. result/error)
/tasks cancel <id>   # Cancel a running task

/tasks reuses the same process-wide runner (get_background_runner()) as praisonai background list, so it shows the same tasks across the REPL, TUI, and bots. When there are no tasks, it prints the empty state:

❯ /tasks
No background tasks

cancel stops the underlying future, not just the task record — a running task is actually interrupted.

In bot chats, /tasks is per-user scoped: a caller only ever sees and cancels tasks whose metadata["user_id"] matches theirs (fail-closed). See Bot Chat Commands → /tasks.

Best Practices

Use aliases - /h is faster than /help
Check costs regularly - Use /cost to monitor spending
Explore unfamiliar code with /plan first - Read-only enforcement prevents accidental writes while you form a plan; run /plan off when you’re ready to execute
Commit frequently - Use /commit after each logical change

Message Queue - Full message queue documentation
Interactive TUI - Full interactive terminal interface
Background Tasks - /tasks and praisonai background list
Cost Tracking - Detailed cost monitoring
Git Integration - Git operations

​Slash Commands

​Overview

​Available Commands (Interactive Mode)

​Built-in Tools

​Usage Examples

​Starting Interactive Mode

​Using Help

​Listing Tools

​Using Tools via Natural Language

​Python API

​Custom Commands

​Unified Command Registry

​Custom commands work inside praisonai code

​Ship a command pack as a pip package

​Command Context

​Integration with Interactive Mode

​Command Reference

​/help

​/cost

​/model

​/plan

​/diff

​/commit

​/profile

​/stats

​/compact

​/undo

​/revert

​/export

​/queue

​/tasks

​Best Practices

​Related Features

Slash Commands

Overview

Available Commands (Interactive Mode)

Built-in Tools

Usage Examples

Starting Interactive Mode

Using Help

Listing Tools

Using Tools via Natural Language

Python API

Custom Commands

Unified Command Registry

Custom commands work inside `praisonai code`

Ship a command pack as a pip package

Command Context

Integration with Interactive Mode

Command Reference

/help

/cost

/model

/plan

/diff

/commit

/profile

/stats

/compact

/undo

/revert

/export

/queue

/tasks

Best Practices

Related Features