Skip to main content
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

1

Start the warm runtime

praisonai daemon start --background
2

Run an agent with a session id (terminal A)

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

Attach from another terminal (terminal B)

praisonai attach my-session

​
Usage

praisonai attach <session-id> [--json]
Argument / OptionTypeDefaultDescription
session_idpositionalrequiredSession id to attach to
--jsonflagfalseEmit 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

TypeFieldsHuman render
run.startsession_id, prompt▶ run.start: <prompt>
run.resultsession_id, ok, result✓ run.result then result text
run.errorsession_id, error✗ run.error: <error>
Attached to session 'my-session'. Ctrl-C to detach.
▶ run.start: Research topic X
✓ run.result
Here is the summary...

​
Exit Codes

CodeMeaning
0Clean detach (Ctrl-C)
1No compatible warm runtime, or stream lost mid-attach
4Runtime 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.

​
Best Practices

Run praisonai daemon start before run --attach. Without a warm runtime, attach exits with code 1.
--attach on praisonai run works for direct prompts only — not YAML files, --agent, or --command.
Ctrl-C in an attach terminal never cancels the underlying agent run.
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