Run

Run agents from files or prompts

The run command executes agents from YAML configuration files or direct prompts.

The same modern engine also handles bare prompts with run-supported flags: praisonai "fix bug" --model gpt-4o is equivalent to praisonai run "fix bug" --model gpt-4o. See CLI Dispatcher for how routing is decided.

Usage

praisonai run [OPTIONS] [TARGET]

Arguments

TARGET may be a YAML/agent file path or a direct prompt. When you type the verb explicitly (praisonai run TARGET), the router hands TARGET to the modern agent runner whenever it ends in .yaml / .yml (even if the file does not exist yet — the runner is what emits the clear file-not-found error), or it is an existing file on disk. Only a TARGET that is neither of those and is not a reserved async-jobs verb (submit / status / result / cancel / list / stream) falls through to the jobs argparse parser and errors out. For free-text prompts, prefer the bare-prompt shape (praisonai "TARGET"), which reaches the modern engine unconditionally — see CLI Dispatcher.

Bare Prompts and YAML

You can drop the run keyword entirely for one-shot prompts and YAML workflows:

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

# Typo? Wrong directory? You still get a clear error from the runner.
praisonai run typo.yaml
# Error: [Errno 2] No such file or directory: 'typo.yaml'

Both shapes inherit everything run gives you — --output modes, session continuity, credential gate, and permissions.

YAML workflows through the modern run engine

praisonai agents.yaml now flows through the same modern run envelope as praisonai run agents.yaml — the router forwards a .yaml/.yml target to the Typer run engine automatically.

That unlocks the full run surface for plain YAML invocations:

# 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

--framework crewai / --framework autogen is a run option, so multi-framework YAML is carried into the modern envelope too.

Options

Append to the system prompt

--append-system-prompt adds a one-off suffix to the assembled system prompt for a single run. It is never persisted and disappears when the process exits.

# 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

Omit the flag and set the environment variable instead — handy for CI:

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

See Append System Prompt for the full behaviour.

Attach an image (--image)

--image attaches a screenshot, mockup, or diagram to a single praisonai run so a vision-capable agent can see it — no code, no YAML.

1. Attach one image

   praisonai run "Describe this screenshot" --image bug.png

2. Attach multiple images

   Repeat the flag — never comma-separate a single value.

   praisonai run "Which of these two designs has better contrast?" \
     --image mock-a.png --image mock-b.png

3. Attach a remote URL

   Any http:// or https:// URL is accepted verbatim.

   praisonai run "Summarize this architecture diagram" \
     --image https://raw.githubusercontent.com/example/repo/main/arch.png

How it works: the run is routed through the vision path and picks a vision-capable model — defaulting to gpt-4o. Override it with --model, but the model you pick must support vision.

praisonai run "Extract every visible number" --image invoice.jpg --model gpt-4o

Supported formats: .png .jpg .jpeg .gif .webp .bmp .svg .tiff. An unsupported extension or a missing local file fails before any model call.

Delegating to Named Agents

Let a running agent delegate sub-tasks to your own named agents in .praisonai/agents/*.md. Pass --subagents to opt agents in for a single run, or mark agents with mode: subagent to expose them on every run.

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

See Named Agent Delegation for the full guide.

Isolated Runs (Git Worktree)

Add --worktree and each run gets its own git branch and checkout — concurrent runs never clobber each other’s edits.

sequenceDiagram
    participant User
    participant Run as praisonai run --worktree
    participant Worktree as Isolated Worktree
    participant Agent

    User->>Run: praisonai run --worktree "prompt"
    Run->>Worktree: create fresh branch + checkout
    Worktree-->>Agent: isolated working directory
    Agent->>Worktree: edit files
    Worktree->>Run: commit changes to branch on exit
    Run-->>User: "Review/merge with: git merge <branch>"

    classDef user fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef tree fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef result fill:#10B981,stroke:#7C90A0,color:#fff

    class User,Agent user
    class Run,Worktree tree

# 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" &

What happens on exit depends on what the run produced:

Committed changes to branch '<branch>'. Review/merge with: git merge <branch>

No changes on '<branch>'.

Worktree kept at <path> (branch '<branch>'). Review/merge then remove with: git worktree remove.

This CLI flag wraps the same core primitive documented for the Python API. Pick the layer that fits:

Piped Input

praisonai run composes in Unix pipelines. Piped stdin is merged with your prompt argument (prompt first, then piped body).

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

Piped input is skipped when:

• TARGET is an existing .yaml / .yml file (case-insensitive).
• --agent or --command is used.
• --restore is set (the command exits before ingestion).

See Piped Input for the full behaviour.

Output Modes

--output controls how results and events are written to stdout.

praisonai run "What is the capital of France?"

praisonai run --output actions "What is the capital of France?"

praisonai run --output json "What is the capital of France?"
# {"result": "Paris", "status": "ok"}

praisonai run --output stream "What is the capital of France?"
# Paris

praisonai run --output stream-json "Find the weather in London"

{"event":"run.retry","data":{"schema_version":1,"attempt":2,"max_attempts":5,"delay":4.0,"reason":"rate_limit"}}

praisonai run --output silent "Run tests" && echo "passed"

praisonai run --output verbose "What is the capital of France?"

Partial-answer stdout on exit 2

On a blocked / truncated run (exit 2), the mode-specific stdout payload is written before the exit reporter runs, so a pipe or redirect never loses it.

The --output stream quiet-mode suppression keeps --quiet honest in the exit-2 path. The --output json envelope writes on every outcome (ok, failed, truncated, content_filtered, refused, length_truncated), so a scripting consumer can always parse .status out of stdout (via PR #5685).

Exit Codes

praisonai run returns a non-zero exit code whenever the agent fails to produce a result, so CI pipelines and scripts can branch on the exit code instead of scraping stderr.

Unified envelope (--output json)

Every outcome prints a single-line {"result": "<text or null>", "status": "<outcome>"} envelope on stdout — success included:

{"result": "Paris", "status": "ok"}

The subsections below document each non-ok outcome; they all share this envelope shape.

Failure payload (--output json / --output stream-json)

When the agent produces no result, the CLI emits a machine-readable failure object and exits 1:

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

The paired error event carries the same status and an error code:

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

The human-facing stderr line includes an actionable remediation:

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

Truncated payload (--output json / --output stream-json)

When a run hits its max_iter / max_steps budget, the CLI keeps the wrap-up summary but marks the run truncated and exits 2:

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

In interactive (non-JSON) mode the CLI also prints a one-line stderr notice so a human knows the answer is partial:

Run hit the step/iteration limit; the answer above is a summary of partial progress, not a completed task. Raise the budget with ExecutionConfig(max_steps=...) on the agent (or `execution: {max_steps: ...}` in the YAML) and re-run.

JSON / stream-JSON consumers do not receive this stderr warning (the CLI checks output.is_json_mode) — the status: "truncated" field is the machine signal.

See Step Budget for how max_steps truncation works, and Agent Run Outcomes → CLI Mapping for the SDK-to-CLI status mapping.

Provider-block payload (--output json / --output stream-json)

When the model’s finish_reason / refusal signals a content-filter block, safety refusal, or length cutoff, the CLI preserves any partial text but marks the run with the specific reason and exits 2:

{"status": "content_filtered", "result": "<partial text or null>"}
{"status": "refused", "result": "<partial text or null>"}
{"status": "length_truncated", "result": "<partial text or null>"}

In interactive (non-JSON) mode the CLI prints the matching human-readable warning to stderr:

Run blocked: the provider's content filter blocked the response.
Run refused: the model declined to answer (safety refusal).
Run truncated: the response hit the model's output length limit.

JSON / stream-JSON consumers do not receive the stderr warning — the status field carries the machine signal. A provider block wins over a generic empty-result failure, so an actionable reason is never masked as a plain run_failed. See Provider block outcomes for the SDK-level classifier and precedence.

CI usage

Test the run in-process first — the CLI’s exit-code contract mirrors this success test.

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

The CLI does the same success test for you and returns exit 1 on failure:

# 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

Branch on the .status field of the unified envelope — every outcome carries one:

result=$(praisonai run --output json "Refactor the auth module and add tests")
status=$(echo "$result" | jq -r '.status')
case "$status" in
  ok)               echo "done" ;;
  truncated)        echo "hit the step limit; raise ExecutionConfig(max_steps=…) and re-run"; exit 2 ;;
  content_filtered) echo "provider blocked the response; try rephrasing"; exit 2 ;;
  refused)          echo "model declined; try a different model"; exit 2 ;;
  length_truncated) echo "response cut off; re-run with a higher --max-tokens"; exit 2 ;;
  failed)           echo "$result" | jq -r '.result // "run failed"'; exit 1 ;;
esac

Or branch on the exit code directly:

praisonai run "…big task…"
case $? in
  0) echo "done" ;;
  1) echo "run failed" ;;
  2) echo "incomplete run (truncated / content_filtered / refused / length_truncated) — check --output json status" ;;
esac

See Step Budget for the truncation contract, and Agent Run Outcomes → CLI Mapping for how the SDK-level statuses map to these exit signals.

Standalone vs wrapper

On a standalone pip install praisonai-code install, default run "…" and the human-readable text modes (--output plain/verbose/silent) route through the in-process Agent (PR #2853) — the same path used by the structured modes (--output actions|json|stream|stream-json). As of PR #3818, chat and code also open their resident interactive TUI standalone — pip install praisonai-code alone delivers run, chat, and code:

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

Every text mode — default run "…" and --output plain|verbose|silent|actions|json|stream|stream-json — plus interactive chat/code runs with no wrapper. The structured-mode in-process dispatch and the per-mode stdout contract (the {result, status} envelope for json, partial-answer-before-exit for stream) were cemented by PR #5685. The wrapper (pip install praisonai) still adds the gateway, channel bots, and the richer legacy interactive dispatch. See the PraisonAI Code CLI standalone-limits table for the full command matrix.

Examples

Run a built-in preset (no YAML required)

# 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"

Run with a custom agent

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

Run with delegatable subagents

Let the running agent hand named sub-tasks to your other .praisonai/agents/*.md agents, each under its own model/tools/permissions.

# 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"

Wiring is a no-op when no delegatable agents exist — default runs are unchanged. See Named Agent Delegation.

Run with a custom agent and CLI permission override

# 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 *'

Run with reasoning effort

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"

--thinking applies across direct-prompt, actions-mode, and custom-agent paths. See Thinking.

Run with a custom command

praisonai run --command summarise "Long text here"

Session flags (--continue, --session, --fork, --no-save) work with --agent.

Run from YAML file

praisonai run agents.yaml

To gate a workflow file with the same --allow / --deny / --approval rules you use on a prompt run, see YAML Workflows Are Permission-Gated.

Run with a prompt

praisonai run "What is the capital of France?"

Run in read-only planning mode

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

--plan denies every mutating tool (write/edit/delete/shell/exec). See Permission Modes and Permissions.

Run in a monorepo

Touching a nested package auto-loads that package’s AGENTS.md — no config, same as chat.

# 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

Run with specific model

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

Run in interactive mode

praisonai run agents.yaml

Run with memory enabled

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

Run with verbose output

praisonai run agents.yaml --verbose

Run with custom tools

# 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

In run actions mode, --tools and --toolset are now wired end-to-end (previously silently dropped). The same is now true for run --agent <name> — --tools/--toolset merge into the agent’s frontmatter tools: list instead of being dropped (#3047).

Run with project-local tools

Local .praisonai/tools/*.py files require an opt-in because loading them executes Python:

# 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"

If tool files exist but neither is set, run prints a one-line hint naming the location(s) and enable step — no more silent skip. See Project-Local Tools.

Resume a previous session

Continue where you left off in your current project:

praisonai run "now add tests" --continue

Resume a specific session by ID:

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

Fork from a session to try a different approach:

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

Pick a session to resume

No id handy? Use --pick (alias --interactive-session) to choose a recent session from a picker, then run a new prompt against it:

# Pick a recent session interactively, then run a new prompt against it
praisonai run --pick "now add tests"

# Alias
praisonai run --interactive-session "now add tests"

--pick opens the same picker as session resume. It is a no-op when --session or --continue already names a session, and silently ignored under --json or a non-TTY so scripts and CI keep today’s behaviour. On a TTY with no --session / --continue, cancelling or an empty store aborts the run with exit code 1 rather than falling through to a fresh run.

Run without saving the session:

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

Run without project instruction files

By default, praisonai run auto-loads AGENTS.md, CLAUDE.md, PRAISON.md, etc. from the project root and attaches nested-subtree instruction files as the agent touches them. Use --no-rules (or PRAISON_NO_RULES=true) to opt out of both:

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

Use --verbose to see which instruction files were loaded:

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

Isolated worktree runs

Pass --worktree to run the agent on a fresh git branch and worktree so its output never touches your working tree. Add --keep to retain the worktree and branch for review.

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

See Run in an Isolated Worktree for the full teardown behaviour matrix and rejected-combination rules.

Live session attach

Tag a warm-runtime run with a session id so other terminals can stream its events with praisonai attach.

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

# Terminal B
praisonai attach my-session

Isolated Runs (--worktree)

Add --worktree to run the agent on a fresh git branch and worktree so its edits never touch your working tree.

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>

--worktree provisions a fresh git worktree on a new branch, chdirs into it, runs the agent, then prints the branch name and a git status --short summary. Every other flag (--tools, --model, --session, --thinking, --memory) applies unchanged.

How teardown protects your output

sequenceDiagram
    participant User
    participant CLI as praisonai run
    participant Git
    participant Agent
    participant Workspace as Original cwd

    User->>CLI: praisonai run --worktree "prompt"
    CLI->>Git: git worktree add (fresh branch)
    Git-->>CLI: worktree ready
    CLI->>Workspace: chdir(worktree)
    CLI->>Agent: run(...)
    Agent-->>CLI: done (files changed?)

    alt changes present
        CLI->>Git: git add -A && git commit --no-verify
        CLI->>Git: git worktree remove (checkout only)
        CLI-->>User: "Committed changes to branch 'praisonai/...'. Review/merge with: git merge praisonai/..."
    else no changes
        CLI->>Git: git worktree remove + delete branch
        CLI-->>User: "No changes on 'praisonai/...'."
    end

    classDef user fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef cli fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef git fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef agent fill:#10B981,stroke:#7C90A0,color:#fff

    class User user
    class CLI cli
    class Git,Workspace git
    class Agent agent

Changes are detected with git status --porcelain, so brand-new untracked files count. When the agent produced output, the CLI auto-commits everything to the branch (praisonai run: <target>, --no-verify) and retains the branch — only the worktree checkout is pruned. A run with no changes is torn down completely.

If the auto-commit fails (for example no user.email/user.name is configured, or a hook rejects it), the worktree checkout is kept in place with a Could not commit isolated changes; worktree kept at <path> (branch '<branch>') for manual review. warning — your output is never lost.

What happens on teardown

The run detects changes with git status --porcelain, so brand-new (untracked) files are never lost.

When to use it

Recipes

# 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

A short uuid4 token is appended to each run’s branch name (e.g. praisonai/agents.yaml-a1b2c3d4), so concurrent runs of the same target never collide.

Compatibility

The CLI rejects incompatible combinations at parse time.

Best practices

See Workspace Isolation for the underlying GitWorktreeAdapter and the Python API.

Project context

By default, praisonai run 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. In a monorepo it also attaches a nested packages/foo/AGENTS.md the first time the agent touches a file under packages/foo/ (parity with chat, wired in PR #3552). Pass --no-context (or set PRAISON_NO_CONTEXT=true) to disable the up-front walk-up, or --no-rules (or PRAISON_NO_RULES=true) to disable both. See Context Files for details.

Declared instruction sources

To declare extra instruction sources — files, globs, or URLs — that load on every run, use the top-level instructions: config key or the repeatable --instructions flag. Config sources merge first, then --instructions flags append on top; the result is prepended to the agent’s backstory as # Project Instructions. See Instruction Sources.

# 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"

The --agent and --command paths honour declared instructions too:

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

--no-rules (or PRAISON_NO_RULES=true) suppresses these declared sources along with the auto-discovered walk-up.

Environment variables

These env vars gate the same context behaviour as the flags, for CI and scripted runs.

First-run Credential Check

praisonai run verifies credentials are configured before doing any work. With no cloud key, it first checks for a reachable local endpoint and adopts it automatically — the prompt below only appears when nothing is reachable.

If no cloud key and no local endpoint is found, you’ll see:

Interactive (TTY):

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

Local model reachable (no cloud key needed):

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

CI / non-interactive (no key and no local endpoint):

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

When no cloud key is set, PraisonAI probes for a local OpenAI-compatible endpoint (Ollama or any /v1-speaking server) and adopts it automatically before falling back — see Keyless local-first fallback. Non-TTY/CI still exits 1 when nothing is detected, so pipelines fail safe.

Exit code is 1 in CI mode. Set any supported env var to bypass the check entirely:

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

“Supported env var” now means any of the 14 credential keys in the Credential → default-model map, so MISTRAL_API_KEY (or any catalogue key) also silences the credential gate:

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

Local model fallback

When no cloud key is configured, praisonai run "..." probes for a reachable local endpoint (Ollama or any OpenAI-compatible server) and adopts its model + base URL for the run — no --model needed. A cloud key always wins; the local probe only runs as a fallback.

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.

See Auth, First-run Onboarding, and Keyless Local-First Run for the full behaviour matrix and CI examples.

Session Continuity

Pick up where you left off — praisonai run remembers per-project conversations and tracks cumulative token usage and cost.

Continue / session runs attach to the warm daemon

When a warm daemon is running, --continue and --session <id> runs now attach to it and reuse a warm, per-session agent instead of paying cold-start each turn. The first turn rehydrates history from the project session store; subsequent turns run against the retained warm agent. On failure the warm agent is dropped and the next turn rehydrates cleanly from the store, so recovery semantics match the in-process path. Fork (--fork) still runs the first turn in-process to mint the new id, then attaches warm on later turns against that id. See Daemon for the full warm-runtime lifecycle.

Usage footer

When running with an active session (--session <id> or --continue), a compact footer appears after each answer:

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

The footer is suppressed in --json / --output json mode, but usage is still persisted into the session record. Totals accumulate across runs and survive resume. See Cost & Token Tracking for the full breakdown.

1. Continue the last run

   Continue the most recent session for your current project:

   praisonai run --continue "now add tests"

   --continue searches both the project store and the global default store, so it resolves the genuinely most-recent root session — including ones created by chat, gateway, TUI, API, or a bare Agent(memory={"session_id": "..."}). If no previous session exists, a warning is shown and a new session starts.

2. Resume a specific session

   Resume a specific session by ID (find IDs with praisonai session list):

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

   Errors out if the session ID does not exist in the current project.

3. Try a different approach without losing history

   Fork from an existing session to try alternatives:

   praisonai run --fork --session abc123 "try Postgres instead of SQLite"

   Creates a new session ID copied from the source. Both sessions evolve independently.

4. What gets restored on –continue / –session

   When you use --continue or --session <id>, every prior user, assistant, assistant-tool-call, and tool-result message in that session is replayed into the agent’s chat history before your new prompt runs. The agent answers with full awareness of what was discussed and what tools it called — no manual context-passing required. Tool-call persistence in the default JSON store landed in PraisonAI PR #3099.

   sequenceDiagram
       participant User
       participant CLI
       participant PS as Project session store
       participant GS as Global default store
       participant Agent
   
       User->>CLI: praisonai run --continue "..."
       CLI->>PS: list_sessions(limit)
       CLI->>GS: list_sessions(limit)
       Note over CLI: merge + dedup by session_id, freshest wins, prefer root sessions
       CLI->>PS: get_chat_history(session_id)
       PS-->>CLI: prior turns
       CLI->>Agent: pre-populate chat_history, then run new prompt
       Agent-->>User: response (aware of prior turns)
   
       classDef cli fill:#8B0000,stroke:#7C90A0,color:#fff
       classDef store fill:#189AB4,stroke:#7C90A0,color:#fff
       classDef result fill:#10B981,stroke:#7C90A0,color:#fff
   
       class User,CLI cli
       class PS,GS store
       class Agent result

   Restored automatically: user, assistant, assistant-tool-call, and tool-result chat_history messages; auto_save continues for the resumed session.

   Not restored: intermediate scratchpad beyond the persisted tool turns; file artefacts from earlier runs remain on disk but are not re-emitted.

   Restored	From
   Chat history (user + assistant + tool-call + tool-result messages)	Project store: ~/.praisonai/sessions/projects/<project_id>/<session_id>.json — or global store: ~/.praisonai/sessions/<session_id>.json (used when --continue picks up a session created by chat, gateway, TUI, API, or a bare Agent(memory={"session_id": "..."}))
   Auto-save bookmark (only new messages appended)	Same file the session lives in
   Session ID	--session <id> flag, or the last root session across both stores for --continue

Choosing between the flags

# First run
praisonai run "Build a FastAPI todo app"

# Continue tomorrow
praisonai run --continue "now add tests"

# Continue with specific session
praisonai run --session abc123 "deploy it to Fly.io"

# Resume while emitting structured tool actions (JSON stream)
praisonai run --session abc123 --output actions "deploy it to Fly.io"

# First run
praisonai run agents.yaml

# Continue with YAML file
praisonai run agents.yaml --continue

# Continue with specific session
praisonai run agents.yaml --session abc123

# Fork a YAML run to try a variation
praisonai run agents.yaml --fork --session abc123

Session usage footer

After every prompt run inside an active session, a single-line footer shows cumulative token and cost totals:

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

The format is:

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

• Totals are cumulative since session start — not just the last prompt.
• Best-effort: if usage cannot be read or priced, the footer is silently skipped.
• Suppressed in JSON mode (--output json, --output stream-json). There is no --no-usage flag.
• Usage is persisted to ~/.praisonai/sessions/<id>.json so resuming with --continue or --session <id> rehydrates the totals and keeps accumulating.

JSON mode — the footer is suppressed; the stdout envelope carries result and status, and usage is attached when the run records it:

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

The minimal envelope is {"result": "...", "status": "ok"}; session_id and usage are added on paths that record them.

Troubleshooting session continuity

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

sequenceDiagram
    participant User
    participant CLI as praisonai run
    participant CP as Checkpoint Engine
    participant Agents

    User->>CLI: praisonai run agents.yaml
    CLI->>CP: auto-checkpoint (run:<id>)
    CP-->>CLI: ✅ saved
    CLI->>Agents: execute
    Agents-->>User: results

    User->>CLI: praisonai run --restore last
    CLI->>CP: restore last checkpoint
    CP-->>User: workspace rewound

    classDef user fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef cli fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef cp fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef agents fill:#10B981,stroke:#7C90A0,color:#fff

    class User user
    class CLI cli
    class CP cp
    class Agents agents

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

# No --approval, but the deny rule still activates a console backend
praisonai run workflow.yaml --deny "bash:rm *"

praisonai run workflow.yaml --approve-all-tools --approval-timeout 120