Attach - PraisonAI

praisonai attach subscribes to a live agent session on the warm runtime and streams its events in real time from a second terminal — read-only, with multiple observers supported.

Quick Start

Start the warm runtime

praisonai daemon start --background

Run an agent with a session id (terminal A)

praisonai run "Research topic X" --attach my-session

Attach from another terminal (terminal B)

praisonai attach my-session

What --attach <id> really tags. --attach <id> is an event-stream label, not a session identity. Two things happen independently:

Persistence / continuity is driven by --session <id> or --continue (a --no-save run has no session identity, so no history is loaded or saved).
Live event fan-out to praisonai attach <id> clients is driven by --attach <id> (falls back to the session id when --attach is omitted).

So praisonai run "..." --no-save --attach obs-1 streams events to observers under obs-1 but persists nothing; praisonai run "..." --session s1 (no --attach) is observable under s1 and its history is retained across turns; praisonai run "..." --session s1 --attach obs-1 runs the stateful s1 conversation but publishes its events under obs-1.

Usage

praisonai attach <session-id> [--json]

Argument / Option	Type	Default	Description
`session_id`	positional	required	Session id to attach to
`--json`	flag	`false`	Emit raw NDJSON events instead of human-readable output

How It Works

Attaching never starts execution — it only observes. Detaching (Ctrl-C) does not stop the run on terminal A.

Events arrive over Server-Sent Events at GET /sessions/{session_id}/events with Bearer auth from the runtime lockfile. Session ids are percent-encoded on the wire. A : keep-alive comment is sent every ~15s and ignored.

Event Reference

Type	Fields	Human render
`run.start`	`session_id`, `prompt`	`▶ run.start: <prompt>`
`run.result`	`session_id`, `ok`, `result`	`✓ run.result` then result text
`run.error`	`session_id`, `error`	`✗ run.error: <error>`

Human output
--json (NDJSON)

Attached to session 'my-session'. Ctrl-C to detach.
▶ run.start: Research topic X
✓ run.result
Here is the summary...

praisonai attach my-session --json | jq 'select(.type=="run.result")'

{"type": "run.start", "session_id": "my-session", "prompt": "Research topic X"}
{"type": "run.result", "session_id": "my-session", "ok": true, "result": "..."}

Exit Codes

Code	Meaning
`0`	Clean detach (Ctrl-C)
`1`	No compatible warm runtime, or stream lost mid-attach
`4`	Runtime module not importable

Common Patterns

Watch a long-running agent from a second terminal — start with --attach, observe progress without blocking terminal A. Pipe JSON into jq — praisonai attach my-session --json | jq 'select(.type=="run.result")'. Multiple observers — several terminals can attach to the same session concurrently; all receive the same events. Observe without persisting — praisonai run "..." --no-save --attach obs-1 streams events under obs-1 for observers while keeping the run on the anonymous, non-persisted path.

Best Practices

Start the daemon first

Run praisonai daemon start before run --attach. Without a warm runtime, attach exits with code 1.

Use direct prompt runs only

--attach on praisonai run works for direct prompts only — not YAML files, --agent, or --command.

Detaching is safe

Ctrl-C in an attach terminal never cancels the underlying agent run.

Version mismatch after upgrade

If CLI and daemon major versions differ, attach refuses to connect. Run praisonai daemon stop && praisonai daemon start after upgrading.

Run

--attach flag for tagging warm-runtime sessions

Daemon

Warm runtime lifecycle and version handshake

​Quick Start

​Usage

​How It Works

​Event Reference

​Exit Codes

​Common Patterns

​Best Practices

​Related

Run

Daemon

Quick Start

Usage

How It Works

Event Reference

Exit Codes

Common Patterns

Best Practices

Related