Run

praisonai run [OPTIONS] [TARGET]

praisonai "Find the weather in London"       # equivalent to: praisonai run "Find the weather in London"
praisonai build a weather agent               # unquoted multi-token prompt also works
praisonai "fix the auth bug" --model gpt-4o   # run-supported flag → still modern engine
praisonai agents.yaml                         # equivalent to: praisonai run agents.yaml
praisonai agents.yaml --continue --output json  # run flags apply to YAML too

# YAML with structured output + a named session
praisonai agents.yaml --output json --session mysess

# Resume the last run of this workflow
praisonai agents.yaml --continue

# Branch off an existing session without mutating it
praisonai agents.yaml --session mysess --fork

# Permission-gated YAML workflow
praisonai agents.yaml --plan
praisonai agents.yaml --allow "bash:git *" --approval console

# Literal text
praisonai run "Refactor this module" --append-system-prompt "Always answer in French"

# Read the suffix from a file (@file form)
praisonai run "Refactor this module" --append-system-prompt @policy.md

export PRAISONAI_APPEND_SYSTEM_PROMPT="Reply in strict JSON, no prose."
praisonai run "Summarise the changelog"

praisonai run --agent lead --subagents researcher,reviewer "Draft and review a brief on X"

# Prompt run on a fresh branch — output committed to the branch on exit
praisonai run --worktree "Refactor the auth module and add tests"

# YAML file run — same isolation, YAML loaded from the original checkout
praisonai run --worktree agents.yaml

# Keep the worktree checkout for in-place review after the run
praisonai run --worktree --keep "Draft a migration plan"

# Two concurrent runs of the same target get independent worktrees/branches
praisonai run --worktree "task A" &
praisonai run --worktree "task A" &

cat error.log | praisonai run "Diagnose the root cause"
git diff       | praisonai run "Review these changes for bugs"

{"status": "failed", "result": null}

{"code": "run_failed", "status": "failed", "message": "Run failed: the agent did not produce a result."}

Run failed: the agent did not produce a result.
Re-run with --verbose to see the underlying error, or check credentials with: praisonai setup

{"status": "truncated", "result": "…wrap-up summary text preserved verbatim…"}

Run hit the step/iteration limit; the answer above is a summary of partial progress, not a completed task. Re-run with a higher --max-iter/max_steps to finish.

from praisonaiagents import Agent

agent = Agent(instructions="Answer succinctly")
result = agent.start("Summarise yesterday's PRs")

if not (result and (not isinstance(result, str) or result.strip())):
    raise SystemExit("Agent run failed")

# Fails the CI job when the agent swallows an error
if ! praisonai run "Summarise yesterday's PRs"; then
  echo "Agent run failed"
  exit 1
fi

result=$(praisonai run --output json "Refactor the auth module and add tests")
status=$(echo "$result" | jq -r '.status // "success"')
case "$status" in
  success)   echo "done" ;;
  truncated) echo "hit the step limit; consider re-running with a higher --max-iter"; exit 2 ;;
  failed)    echo "$result" | jq -r '.message'; exit 1 ;;
esac

praisonai run "…big task…"
case $? in
  0) echo "done" ;;
  1) echo "run failed" ;;
  2) echo "truncated — partial answer above" ;;
esac

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

# Read-only planner — never modifies files
praisonai run --agent plan "explore the codebase"

# Code reviewer that asks before shell commands
praisonai run --agent review "review the recent diff"

# Full toolset
praisonai run --agent build "add a /health endpoint"

praisonai run --agent researcher "Find info on X"

# Expose named agents with `mode: subagent` in frontmatter
praisonai run --agent lead "Research 3 vector DBs, then draft an eval script"

# Or opt any named agents in explicitly
praisonai run --agent lead --subagents researcher,coder "Research 3 vector DBs, then draft an eval script"

# Agent definition has mode: review (bash:*: ask)
# --allow overrides to let git commands run without prompting
praisonai run --agent reviewer "review the diff" --allow 'bash:git *'

praisonai run --thinking medium "Plan a release checklist for v4.7"

# Works with custom agents too
praisonai run --agent researcher --thinking high "Deep dive on vector DB options"

praisonai run --command summarise "Long text here"

praisonai run agents.yaml

praisonai run "What is the capital of France?"

# Read-only run — the agent explores but writes nothing
praisonai run --plan "Audit the auth module and propose a refactor"

# From the repo root, touching a nested package auto-loads packages/foo/AGENTS.md
praisonai run "refactor packages/foo/bar.py to use the new logger"

# Opt out for a one-off run
praisonai run --no-rules "just print the file, don't apply project rules"

# Or globally in CI
export PRAISON_NO_RULES=true

praisonai run "Explain quantum computing" --model gpt-4o

praisonai run agents.yaml

praisonai run "Remember my name is John" --memory

praisonai run agents.yaml --verbose

# By name — the agent picks up built-in tools, no file needed
praisonai run "Summarise today's AI news" --tools "web_search,github"

# Or from a file
praisonai run agents.yaml --tools tools.py

# Discoverable per-invocation flag (recommended)
praisonai run --allow-local-tools "use the greet tool"

# Env-var equivalent (persists for the shell)
PRAISONAI_ALLOW_LOCAL_TOOLS=true praisonai run "use the greet tool"

# --agent runs also auto-discover .praisonai/tools/*.py now
praisonai run --agent researcher --allow-local-tools "use the greet tool to greet Ada"

praisonai run "now add tests" --continue

praisonai run "what were we working on?" --session abc12345

praisonai run "try a different approach" --fork --session abc12345

praisonai run "one-off question" --no-save

praisonai run "Quick one-off task" --no-rules

praisonai run "What does this codebase do?" --verbose
# > Loaded project instructions: AGENTS.md, CLAUDE.md

praisonai run "Refactor the auth module" --worktree
praisonai run agents.yaml --worktree --keep

# Terminal A
praisonai daemon start --background
praisonai run "Research topic X" --attach my-session

# Terminal B
praisonai attach my-session

praisonai run "refactor auth to use bcrypt" --worktree
# > Isolated run on branch 'praisonai/refactor-auth-<uid>' (./.praisonai/worktrees/refactor-auth-<uid>)
# ... agent runs ...
# > Committed changes to branch 'praisonai/refactor-auth-<uid>'.
# > Review/merge with: git merge praisonai/refactor-auth-<uid>

# Run an agent on a fresh branch, then merge if you like the result
praisonai run agents.yaml --worktree
# → prints:  Committed changes to branch 'praisonai/agents.yaml-a1b2c3d4'.
#            Review/merge with: git merge praisonai/agents.yaml-a1b2c3d4
git merge praisonai/agents.yaml-a1b2c3d4

# Keep the worktree open for hands-on review
praisonai run agents.yaml --worktree --keep
# → prints:  Worktree kept at /path (branch 'praisonai/...').
#            Review/merge then remove with: git worktree remove.

# Run several agents in parallel on the same repo — each gets its own branch
praisonai run "Add tests to lib/api" --worktree &
praisonai run "Refactor lib/db"      --worktree &
wait

# One-off: layer an extra rules file on top of AGENTS.md for this run only
praisonai run --instructions docs/rules.md "explain this codebase"

# Repeatable: multiple sources merge in order
praisonai run \
  --instructions ~/company/ai-rules.md \
  --instructions docs/standards/*.md \
  "review the diff"

praisonai run --agent lead --instructions docs/rules.md "task"
praisonai run --command review --instructions docs/rules.md "task"

No API key configured.
Would you like to run the setup wizard now? [Y/n]:

No cloud key found; using local model ollama/llama3.2. Run `praisonai setup` to add a hosted provider.

Error: No API key configured. Run: praisonai setup
(a running local endpoint such as Ollama would be used automatically)

export OPENAI_API_KEY=sk-...
praisonai run "hello"

export MISTRAL_API_KEY=...
praisonai run "hello"
# Uses mistral/mistral-large-latest — no --model, no wizard.

ollama serve
praisonai run "Summarise this file"
# stderr: No cloud key found; using local model ollama/llama3.2. Run `praisonai setup` to add a hosted provider.

1,240 in / 3,980 out · $0.0140

$ praisonai run "Summarise yesterday's PRs"
... (agent output) ...
1,240 in / 3,980 out · $0.0140

{input_tokens:,} in / {output_tokens:,} out · ${cost:.4f}

$ praisonai run --output json "Summarise yesterday's PRs"
{"session_id":"abc12345","output":"...","usage":{"input_tokens":1240,"output_tokens":3980,"total_tokens":5220,"cost":0.0140,"requests":1}}

framework: praisonai
topic: Research Assistant
roles:
  researcher:
    backstory: Expert research analyst
    goal: Find accurate information
    role: Researcher
    tasks:
      research_task:
        description: Research the given topic
        expected_output: Comprehensive research summary

praisonai run agents.yaml            # auto-checkpoint, then run
praisonai run --restore last         # rewind workspace, exit
praisonai run agents.yaml --no-checkpoint   # skip the auto-checkpoint

praisonai run --revert                        # last turn, files-only preview
praisonai run --revert last --session my-feat # last turn, rewinds my-feat conversation too
praisonai run --revert 3    --session my-feat # last 3 turns

praisonai run workflow.yaml \
  --deny "bash:rm *" \
  --allow "bash:pytest *" \
  --approval console \
  --approval-timeout 60