> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Attach

> Stream live events from a session running on the warm runtime

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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    A[Terminal A<br/>run --attach id] --> R[Warm Runtime]
    R -->|SSE events| B[Terminal B<br/>attach id]
    R -->|SSE events| C[Terminal C<br/>attach id --json]

    classDef input fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class A input
    class R process
    class B,C output
```

## Quick Start

<Steps>
  <Step title="Start the warm runtime">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai daemon start --background
    ```
  </Step>

  <Step title="Run an agent with a session id (terminal A)">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai run "Research topic X" --attach my-session
    ```
  </Step>

  <Step title="Attach from another terminal (terminal B)">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai attach my-session
    ```
  </Step>
</Steps>

***

## Usage

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant A as Terminal A
    participant R as Warm Runtime
    participant H as Event Hub
    participant B as Terminal B
    participant C as Terminal C

    A->>R: run --attach my-session
    B->>R: attach my-session
    C->>R: attach my-session --json
    R->>H: fan-out session events
    H-->>B: run.start / run.result / run.error
    H-->>C: NDJSON lines
```

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

<Tip>
  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.
</Tip>

***

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

<Tabs>
  <Tab title="Human output">
    ```
    Attached to session 'my-session'. Ctrl-C to detach.
    ▶ run.start: Research topic X
    ✓ run.result
    Here is the summary...
    ```
  </Tab>

  <Tab title="--json (NDJSON)">
    ```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    praisonai attach my-session --json | jq 'select(.type=="run.result")'
    ```

    ```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    {"type": "run.start", "session_id": "my-session", "prompt": "Research topic X"}
    {"type": "run.result", "session_id": "my-session", "ok": true, "result": "..."}
    ```
  </Tab>
</Tabs>

***

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

***

## Best Practices

<AccordionGroup>
  <Accordion title="Start the daemon first">
    Run `praisonai daemon start` before `run --attach`. Without a warm runtime, attach exits with code 1.
  </Accordion>

  <Accordion title="Use direct prompt runs only">
    `--attach` on `praisonai run` works for direct prompts only — not YAML files, `--agent`, or `--command`.
  </Accordion>

  <Accordion title="Detaching is safe">
    Ctrl-C in an attach terminal never cancels the underlying agent run.
  </Accordion>

  <Accordion title="Version mismatch after upgrade">
    If CLI and daemon major versions differ, attach refuses to connect. Run `praisonai daemon stop && praisonai daemon start` after upgrading.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Run" icon="play" href="/docs/cli/run">
    `--attach` flag for tagging warm-runtime sessions
  </Card>

  <Card title="Daemon" icon="bolt" href="/docs/cli/daemon">
    Warm runtime lifecycle and version handshake
  </Card>
</CardGroup>