Run

Run agents from files or prompts

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

For a quick one-off prompt you can omit the run subcommand entirely: praisonai "What is the capital of France?" is equivalent to praisonai run "What is the capital of France?" when the positional argument isn’t an existing file or a .yaml/.yml path. Use praisonai run when you need flags like --output stream-json, --model, --continue, --session, --no-rules, --allow, etc.

Single-word direct prompts that look like reserved commands or common typos now fail fast with a hint on stderr and exit code 2. To send a genuine single word to the model, use praisonai run "<word>" explicitly. See Unknown Command Guard.

praisonai run exits 1 whenever the agent fails to produce a result. Under --output json / --output stream-json the failure surfaces as {"status": "failed", "code": "run_failed"} with an actionable remediation. See Exit Codes for the full table.

praisonai run "..." with no cloud key and no --model picks a reachable local model automatically. If Ollama (or any OpenAI-compatible local server) is running, you’ll see a one-line stderr notice and the run continues:

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

An explicit --model still takes over. See Keyless Local-First Run.

Usage

praisonai run [OPTIONS] [TARGET]

Arguments

Argument	Description
TARGET	Agent file (YAML) or direct prompt text

Bare Prompts

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

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

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

Any invocation with a -/-- flag, or a positional ending in .yaml/.yml, keeps the legacy dispatcher — fully backward-compatible. Multi-token unquoted prompts are joined into a single run positional so praisonai build a weather agent reaches the model as one prompt.

Options

Option	Short	Description	Default
--output	-o	Output mode: text, json, stream-json, silent, verbose	text
--model	-m	LLM model to use	gpt-4o-mini
--framework	-f	Framework: praisonai, crewai, autogen	praisonai
--interactive	-i	Enable interactive mode	false
--verbose	-v	Verbose output	false
--stream		Stream output	true
--no-stream		Disable streaming
--trace		Enable tracing	false
--memory		Enable memory	false
--tools	-t	Comma-separated tool names (e.g. web_search,github) or a tools.py file path (resolved via ToolResolver)
--toolset		Comma-separated named toolset groups to load
--allow-local-tools		Load project-local .praisonai/tools/*.py for this run only (equivalent to PRAISONAI_ALLOW_LOCAL_TOOLS=true, but strictly per-invocation)	false
--max-tokens		Maximum output tokens	16000
--continue	-c	Continue the most recent session for this project	false
--session	-s	Resume a specific session ID
--fork		Fork from the specified session (requires --session)	false
--no-save		Don’t auto-save the session after execution	false
--no-rules		Disable auto-injection of project instruction files (AGENTS.md, CLAUDE.md, etc.)	false
--no-context		Disable AGENTS.md/CLAUDE.md auto-loading into system prompt	false
--agent	-a	Use a named custom agent from .praisonai/agents/
--subagents		Comma-separated named agents (.praisonai/agents/*.md) the running agent may delegate to. Omit to expose agents marked mode: subagent.
--thinking		Reasoning effort for this invocation: off, minimal, low, medium, high
--command		Execute a named custom command; TARGET becomes $ARGUMENTS
--allow		Allow a permission pattern (e.g. 'bash:git *'); repeatable
--deny		Deny a permission pattern; repeatable
--permissions		Path to a YAML permission rules file
--permission-default		Default action for unmatched patterns: allow, deny, or ask
--approval		Approval backend mode: console, plan, accept-edits, bypass
--restore		Restore workspace to a checkpoint (id, last, or latest) and exit
--no-checkpoint		Disable automatic pre-run checkpoint for this invocation	false
--attach		Run on the warm runtime under this session id so other terminals can observe via praisonai attach
--worktree		Run on an isolated git worktree/branch (branch-per-task); no-op outside a git repo	false
--keep		With --worktree, keep the worktree/branch after the run for review instead of tearing it down	false

For workflow guidance, see Isolated Runs or the flag-focused guide at Run —worktree.

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.

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

Changes produced (default)

The run commits everything (git add -A + git commit --no-verify) to the isolated branch, then removes the worktree checkout while keeping the branch. You’ll see:

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

If the commit can’t be made (e.g. no git identity configured), the worktree is kept in place with a warning so output is never lost.

No changes produced

The worktree checkout and its branch are torn down entirely — nothing is left behind.

No changes on '<branch>'.

--keep set

The worktree checkout stays in place for in-place review, regardless of whether changes were made.

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

--worktree is a no-op outside a git repository — it prints Not a git repository; running without worktree isolation. and runs in place, so it’s safe to add unconditionally. Change detection uses git status --porcelain, so brand-new untracked output counts as a change.

Isolation applies to direct prompt and YAML file runs only. These combinations are rejected up front (exit code 1):

• --worktree + --attach — the warm runtime is a separate process whose working directory can’t be redirected.
• --worktree + --agent / --command / --profile / --profile-deep — only prompt and YAML runs are supported.
• --keep without --worktree — --keep requires --worktree.

When --worktree is used with a warm-runtime-eligible prompt, the run falls back to in-process execution so it never attaches to a cached warm agent.

Human-facing worktree messages are suppressed under --output json / --output stream-json, so structured runs stay machine-parseable.

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

Python API — GitWorktreeAdapter

Provision worktrees directly from Python for concurrent agents.

Per-Kanban-Task Worktrees

Give each kanban task its own worktree with workspace_kind="worktree".

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.

text (default)

Rich-formatted human-readable output in the terminal.

praisonai run "What is the capital of France?"

json

Emits a single JSON object at the end of the run containing the final result.

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

stream-json

Emits one JSON object per line (NDJSON) as the run progresses — one event per agent action. Ideal for CI pipelines, scripts, and observability tooling.

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

Transient rate limits surface as a run.retry event before the wait, so a rate-limited run shows a live countdown instead of a silent hang:

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

See Stream Events for the full event protocol reference.

silent

No stdout output — useful when you only need the exit code.

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

verbose

Includes diagnostic details alongside normal output. Useful for debugging.

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

---

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.

Exit	When	Emitted where
0	Agent returned a non-empty result	All modes
1	Agent returned None or empty (swallowed LLM/auth error, guardrail block, tool failure, max_iter without completion)	All run modes (direct prompt, YAML file, --agent, --attach, --profile, --profile-deep)
1	No API key configured in CI mode	Direct prompt
1	Worktree flag combined with --attach, --agent, --command, or --profile	Direct prompt
1	Warm-runtime major-version mismatch on --attach	--attach <id>
2	Single-word direct prompt collides with a reserved command / typo guard	Direct prompt

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

The failure contract applies to every run path — direct prompt, YAML file, --agent, --attach, --profile, and --profile-deep. Profiled runs still print the profiling report before exiting non-zero, so you keep the profile even on failure.

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

# Or branch on the JSON status
result=$(praisonai run --output json "Summarise yesterday's PRs")
status=$(echo "$result" | jq -r '.status')
if [ "$status" = "failed" ]; then
  echo "$result" | jq -r '.message'
  exit 1
fi

See Agent Run Outcomes → CLI Mapping for how the SDK-level statuses collapse into this single exit signal.

---

Standalone vs wrapper

On a standalone pip install praisonai-code install, default run "…" and the human-readable text modes (--output plain/verbose/silent) now route through the in-process Agent (PR #2853) — the same path used by the structured modes (--output actions|json|stream|stream-json). Only chat and code still require the praisonai wrapper and surface an install hint.

Error: chat requires the praisonai wrapper. Install the full wrapper: pip install praisonai

Every text mode — default run "…" and --output plain|verbose|silent|actions|json|stream|stream-json — runs in-process with no wrapper. See the PraisonAI Code CLI standalone-limits table for the full command matrix.

run --output actions honours --tools and --toolset. These flags were previously dropped in actions mode; they now reach parity with the default, YAML, and Python surfaces. The same ToolResolver path resolves comma-separated names, and tools.py file paths continue to load as before.

praisonai run --output actions --tools tavily_search,github "Research the latest release"

run --agent honours --tools, --toolset, and auto-discovers .praisonai/tools/*.py. These were previously silently dropped when --agent was used. The --agent path now composes its toolset by unioning the agent’s frontmatter tools: list with --tools/--toolset and (when PRAISONAI_ALLOW_LOCAL_TOOLS=true or --allow-local-tools is set) auto-discovered project-local tools, dedup’d by callable identity. Fixes #3047.

praisonai run --agent researcher \
  --tools github,tavily_search \
  --allow-local-tools \
  "Greet Ada, then research WebAssembly 3.0"

---

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

Run with a prompt

praisonai run "What is the capital of France?"

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

Run without saving the session:

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

After every run with an active session, a compact usage footer prints to stdout:

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

This footer is silenced under --output json. Token and cost totals accumulate across resumed runs — they are never reset. See Cost Tracking for per-session totals.

Run without project instruction files

By default, praisonai run auto-loads AGENTS.md, CLAUDE.md, PRAISON.md, etc. from the project root. Use --no-rules to opt out:

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

--attach is supported for direct prompt runs only — not YAML files, --agent, or --command. Requires a compatible warm runtime (praisonai daemon start). Major-version mismatch falls back to in-process execution for run, or exit code 1 for attach.

---

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

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.

Situation	Worktree checkout	Branch	Reported
No changes	Removed	Removed	No changes on '<branch>'.
Any change (tracked or untracked)	Pruned	Retained with auto-commit	Committed changes to branch '<branch>'. Review/merge with: git merge <branch>
--keep	Retained	Retained	Worktree kept at <path> (branch '<branch>'). Review/merge then remove with: git worktree remove.
Commit fails (e.g. no git identity)	Retained for manual review	Retained	Warning: Could not commit isolated changes; worktree kept at <path> ...
Cwd is not a git repo	n/a (no-op)	n/a	Warning: Not a git repository; running without worktree isolation.

--worktree never destroys the agent’s output. On any change the branch is committed and retained even without --keep — only the worktree checkout is pruned.

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.

Combined with	Behaviour
--attach <id>	❌ Error: --worktree cannot be combined with --attach — isolated runs stay in-process, but --attach targets the warm runtime (a separate process).
--keep without --worktree	❌ Error: --keep requires --worktree — --keep is meaningless without isolation.
--agent <name>	❌ Error: --worktree is only supported for direct prompt and YAML file runs — the custom-agent flow has its own execution path.
--command <name>	❌ Same error — the custom-command flow has its own execution path.
--profile / --profile-deep	❌ Same error — the profiling flow has its own execution path.
--session <id> / --continue	✅ Works — session state is stored outside the worktree.
--tools, --toolset, --model, --thinking, --memory	✅ Works — orthogonal to isolation.
Warm runtime (praisonai daemon start)	⚠️ Bypassed — isolated runs always execute in-process, even when a warm runtime is available.

A short random 8-char token is appended to every branch/worktree name, so two runs of the same target never collide — run praisonai run "..." --worktree twice in parallel and each gets its own branch and directory.

Best practices

Auto-commit means your output is never lost

On completion, any tracked or untracked change is committed to the branch and the branch is retained. Even if the auto-commit fails (missing user.email/user.name, hook rejection), the worktree checkout is kept in place — you never have to fight the CLI for your agent’s output.

Use --keep for inspection, not for saving output

Auto-commit already preserves your work on a branch. --keep is for cases where you want to review files in place before merging — compare screenshots, or run a local dev server against the checkout.

Non-git directories still work

The flag is a transparent no-op outside git. Wire it into every project script without conditionals: praisonai run --worktree "..." runs in the current cwd if there’s no repo, printing Not a git repository; running without worktree isolation.

Cleaning up abandoned worktrees

--keep never auto-removes. When you’re done: git worktree remove <path> && git branch -D praisonai/…. To see leftovers from all runs: git worktree list.

Three ways to get worktree isolation, one shared primitive:

• CLI (this page) — praisonai run --worktree for one-off human-driven runs.
• Kanban — set workspace_kind="worktree" on a task so dispatched workers each get one (Per-Task Worktree Isolation).
• Library — instantiate GitWorktreeAdapter yourself for programmatic isolation (Workspace Isolation).

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. Pass --no-context (or set PRAISON_NO_CONTEXT=true) to disable. See Context Files for details.

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"

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.

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

   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(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

   As of the fix for PraisonAI #2655, --continue searches both the project-scoped store and the global default store, so sessions created by chat, gateway, TUI, API, or a bare Agent(session_id=...) are all resumable. Sub-agent / forked child sessions are skipped in favour of the last root session.

   History restore and save wiring landed in PR #1963. Earlier builds discovered the session but silently dropped prior history on resume — upgrade praisonai if --continue returns empty context.

Choosing between the flags

Prompt mode

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

YAML mode

# 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

--continue / --session / --fork / --no-save work for YAML/team runs identically to prompt runs. Prior team conversation — per-agent chat history and shared team state — is replayed. The flags are honored regardless of whether agents.yaml sets memory: true; session continuity opts the team into shared memory automatically. See YAML / Team Session Continuity.

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 but usage is included in the payload:

$ 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}}

Troubleshooting session continuity

`--continue` runs but the agent has no memory of the previous turn

Fixed in PR #1963 — sessions were discovered but history was not loaded. Upgrade praisonai and re-run.

`--output actions --session <id>` raised TypeError about resume_session

Fixed by PR #1963. Upgrade praisonai.

`--output actions` with `--auto-save` raised TypeError about `auto_save`

Fixed by commit 7016bfa (issue #2700). The actions-output branch of run re-imported build_cli_memory_config / apply_cli_session_continuity from praisonai_code.cli.utils.project, shadowing the correct praisonai_code.cli.state.project_sessions versions. The stale variant lacked the auto_save keyword, so wiring session continuity in actions mode raised TypeError: apply_cli_session_continuity() got an unexpected keyword argument 'auto_save'. Upgrade praisonai-code and re-run.

Session continuity works in prompt mode but not with agents.yaml

Also fixed by PR #1963 — YAML and file-mode runs use the same project session store as prompt-mode runs.

`--no-save` together with `--session <id>`

--no-save wins — the run still resumes from the named session (agent has context), but new messages are not persisted. Useful for read-only follow-ups on an existing thread.

Sessions are scoped to the current project — detected from the git root, or the current directory if you’re not in a repo. Two projects never see each other’s sessions.

---

Agent File Format

Create an agents.yaml file:

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

Session Management

Sessions are scoped to the current project (git root, or current directory if not a git repository). Each run auto-saves to a generated session-<uuid8> unless --no-save is set.

Use praisonai session list to view saved sessions for the current project, or praisonai session list --all to see sessions across all projects.

---

Checkpoint & Rewind

praisonai run auto-checkpoints your workspace before YAML-file runs so a bad turn can be rewound with one command.

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

Auto-checkpoint behaviour:

• Runs before any YAML-file execution (*.yaml / *.yml targets only).
• Label: run:<run_id> (or "auto checkpoint before run" as a fallback).
• Workspace: the directory of the target YAML file, not the current directory.
• Plain-prompt runs are skipped to avoid empty-checkpoint noise.
• Best-effort — failures are swallowed and never block the run. Use --verbose to see "Auto-checkpoint skipped: …" on failure.
• Gated by checkpoints.auto (default true) in your project config; override per-run with --no-checkpoint.
• Reads checkpoints.storage_dir from your project config so the auto-checkpoint/restore path shares the same store as praisonai code --checkpoints sessions. See Checkpoints for the config block.

New checkpoint flags:

Flag	Description	Default
--restore <id|last|latest>	Restore the workspace to a checkpoint and exit — nothing runs.	—
--no-checkpoint	Disable the automatic pre-run checkpoint for this invocation.	false

--restore rewinds the workspace and exits before any agent execution — it is a pure undo, not a run. See Checkpoints and Checkpoint CLI for managing checkpoints directly.

---

See Also

• Isolated Runs (--worktree) - Run on a fresh git branch per run
• Session - Session management commands
• Project-Scoped Sessions - How project sessions work
• Checkpoints - Auto-checkpoint and rewind feature
• Checkpoint CLI - Checkpoint subcommands
• Agents - Agent management
• Custom Agents, Commands & Tools - Define agents and how their tools compose on --agent
• Project-Local Tools - Auto-discovered .praisonai/tools/*.py on run and run --agent
• Workspace Isolation - --worktree per-run git isolation and the GitWorktreeAdapter Python API
• Workflow - Workflow execution
• Interactive TUI - Interactive terminal interface
• Attach - Stream live events from a warm-runtime session
• Workspace Isolation - Per-agent git worktree adapter (the SDK primitive --worktree exposes)