PraisonAI Code CLI

Standalone agentic terminal CLI: run agents, chat, and code without the full wrapper

praisonai-code is the terminal-native agent CLI — install it on its own for a smaller footprint when you only need agentic commands.

# Standalone install — no wrapper needed
from praisonaiagents import Agent

Agent(instructions="Summarise this URL").start("https://arxiv.org/abs/2409.12345")

# Same result from the CLI, standalone (PR #2853)
pip install praisonai-code
praisonai-code run "Summarise https://arxiv.org/abs/2409.12345"

The user runs a terminal prompt; praisonai-code executes the agent in-process and prints the reply.

Interactive chat and code also run from praisonai-code alone — no wrapper (PR #3818):

pip install praisonai-code
praisonai chat        # opens the split-pane async TUI, no wrapper required
praisonai code        # opens the resident code TUI, no wrapper required

Which install do I need?

Both praisonai-code (console script) and python -m praisonai_code call the same entry point: configure logging, register commands, then run the Typer app.

Interactive Chat & Code (resident TUI)

A single pip install praisonai-code is enough for an interactive session — the split-pane async TUI ships inside the package (PR #3818).

pip install praisonai-code
praisonai chat        # opens the split-pane async TUI, no wrapper required
praisonai code        # opens the resident code TUI, no wrapper required

The wrapper is never required for the baseline TUI — it only upgrades code to the richer legacy dispatch. Instruction loading is now resident: praisonai_code.integration.context_files ships inside the package, so the subtree hook and --instructions globs/URLs work standalone without routing through _wrapper_bridge. When the wrapper (or praisonai_bot) is installed, the CLI prefers that copy.

Native rules + project instructions

rules list/add/clear and subtree instruction loading run natively on a standalone pip install praisonai-code (PR #4338) — no praisonai_bot or praisonai needed.

pip install praisonai-code
praisonai rules add my_rule "Always use type hints"   # workspace-scoped rule
praisonai rules list                                   # native, backed by RulesManager
praisonai rules clear                                  # clears workspace rules only

• rules list/add/clear run natively via praisonaiagents.memory.RulesManager.
• Subtree AGENTS.md/CLAUDE.md auto-attach and --instructions globs/URLs both work standalone via praisonai_code.integration.context_files.
• clear is scoped to workspace rules only — hand-authored AGENTS.md/CLAUDE.md/PRAISON.md, global rules, git-root rules, and nested subdir rules are never removed.

Deep dives: Rules, Instruction Sources, and Context Files.

Quick Start

1. Install standalone

   pip install praisonai-code
   praisonai-code version

   The panel lists PraisonAI Code, PraisonAI Agents, and Python. When the full wrapper is installed, a PraisonAI Wrapper line appears as well.

   Use --version for a quick one-liner (package version only, no panel):

   praisonai-code --version

   Run your first agent:

   praisonai-code run "Summarise the top 3 arXiv papers on RAG this week"

   Every text mode — default run "…" and --output plain|verbose|silent|actions|json|stream|stream-json — runs standalone via the in-process Agent path. As of PR #3818, chat and code also open their resident interactive TUI standalone — the wrapper adds only the richer legacy dispatch for code and the gateway/bot channels.

2. Upgrade later if you need bots or gateway

   pip install praisonai

   The same praisonai-code binary keeps working. Wrapper-only commands (gateway, bot, onboard, pairing, identity, kanban, claw, dashboard) become available through the composed install.

How It Works

Every text-mode run reaches the in-process Agent path on a standalone install. The sole carve-out is --image: vision routes through the wrapper’s ImageHandler, so run --image fails fast with a targeted hint when the wrapper is absent. For every other text run the CLI checks wrapper_available() — when the wrapper is present it delegates to the richer handle_direct_prompt (existing users see zero change, including vision); when it is absent it renders in-process from the same Agent the structured --output modes already build. chat and code open their resident TUI standalone (PR #3818); when the wrapper is installed, code prefers the richer legacy dispatch (PraisonAI._start_interactive_mode). Plugin discovery is vendored inside praisonai-code, so plugin-related flows keep working without the wrapper.

The --image carve-out is enforced by _require_wrapper_for_default_run; every other text-mode run reaches the in-process Agent branch when the wrapper is absent (PR #5687).

Output presets map as plain → plain, silent/default → silent, verbose → verbose; silent-style presets print the final text. chat and code open their resident interactive TUI standalone (PR #3818) — pip install praisonai-code alone delivers full interactive sessions. When the praisonai wrapper is installed, code prefers its richer legacy dispatch (PraisonAI._start_interactive_mode):

pip install praisonai-code
praisonai-code chat
praisonai-code code "Refactor this function"

The vendored _registry module means plugins work even without the wrapper installed. Version resolution reads from the praisonai-code package metadata directly, not the wrapper.

Standalone agent parity

Default run "…" and the structured --output modes share one agent surface (_wire_run_agent_config), so the same inputs reach the in-process Agent on a standalone install (PR #5687).

# Standalone install — no wrapper needed
from praisonaiagents import Agent

agent = Agent(
    name="DevHelper",
    instructions="Diagnose developer errors",
    tools=["file.read", "shell.run"],
)
agent.start("Explain this stack trace")

# Same inputs the CLI wires into the in-process Agent (PR #5687)
pip install praisonai-code
praisonai-code run \
  --tools file.read,shell.run \
  --session my-debug \
  --instructions ./AGENTS.md \
  "Explain this stack trace"

Command matrix

Three tiers decide what a command needs: fully standalone, wrapper-boosted (works standalone but gains a richer path with the wrapper), and wrapper-only (not listed without the wrapper).

chat and code open their resident TUI standalone (PR #3818); code prefers the richer legacy dispatch when the wrapper is installed. Wrapper-only names stay out of --help entirely and do not load a Typer module.

The 13 stub groups below are a special mixed case — their legacy entry points are wrapper-required, but native subcommands stay standalone-safe. rules is not in this list — rules list/add/clear are native standalone (PR #4338):

Standalone limits

On a pip install praisonai-code-only install:

chat, code, and every run output mode work on a praisonai-code-only install (PR #2853, PR #3818, PR #5685, PR #5687). PR #5687 completed the picture by making the default run "…" (no --output flag) self-sufficient — previously it hard-failed with an install hint on a standalone install. Installing the wrapper (pip install praisonai) adds the richer legacy dispatch for code, the gateway, and channel bots — it is no longer required for the baseline interactive experience.

--image is the only text-mode feature that still requires pip install praisonai. Every other run text mode — default / plain / verbose / silent / actions / json / stream / stream-json — runs in-process via the shared _wire_run_agent_config surface, so --tools, --toolset, MCP servers, --session/--continue, --instructions, and the approval surface all reach the standalone Agent (PR #5687).

praisonai-code doctor returns exit 0 on a healthy standalone install — wrapper-presence checks (performance_praisonai_import, acp_module, praisonai_package_structure, console_script_execution) SKIP rather than FAIL (PR #2851).

Stub command groups on standalone

Run agents standalone without the wrapper — the SDK works directly:

from praisonaiagents import Agent

Agent(instructions="Summarise this URL").start("https://arxiv.org/abs/2409.12345")

# Same result from the CLI, standalone (in-process)
pip install praisonai-code
praisonai-code run --output actions "Summarise https://arxiv.org/abs/2409.12345"

Thirteen command groups — agents, workflow, registry, memory, skills, hooks, eval, package, templates, todo, research, commit, and call — delegate to the praisonai wrapper for their legacy entry points. rules is not among them — rules list/add/clear run natively on standalone (PR #4338). On a standalone pip install praisonai-code (PR #2854) those entry points exit 1 with a single-line install hint — no Rich traceback:

agents requires the full wrapper. Install the full wrapper: pip install praisonai

The <group> name changes per command (workflow requires the full wrapper. …, registry requires the full wrapper. …, and so on).

Wrapper-command loading

Wrapper-only commands (bot, gateway, pairing, identity, onboard, kanban, dashboard, claw, daemon) are Typer sub-apps whose implementations live in the praisonai wrapper. When you install praisonai-code standalone, these commands are not listed in --help and are not resolvable — get_command() returns None instead of loading a module that doesn’t exist in praisonai_code.

# Standalone install, wrapper-only command
$ pip install praisonai-code
$ praisonai-code bot --help
Error: No such command 'bot'.

To use bot, gateway, pairing, identity, onboard, kanban, dashboard, claw, or daemon, install the full wrapper:

pip install praisonai

Configuration and environment

Version commands

praisonai-code version

Shows the full version panel:

PraisonAI Code: 0.0.4
PraisonAI Wrapper: 1.x.x   ← only shown when praisonai is installed
PraisonAI Agents: 1.6.x
Python: 3.12.x

praisonai-code version --json

Returns structured JSON:

{
  "praisonai-code": "0.0.4",
  "praisonai": "1.x.x",
  "praisonaiagents": "1.6.x",
  "python": "3.12.x"
}

The praisonai key is omitted when the wrapper is not installed.

praisonai-code version check

Queries PyPI and returns update status:

{
  "current": "0.0.4",
  "latest": "0.0.5",
  "update_available": true
}

Best Practices

Related