Oko
Oko/Docs

Command reference

oko sessions attach

Joins this terminal to a session: locally at the attach socket the broker lists for it, or as a viewer of a session published through a WebSocket relay.

Invocation#

Command
oko sessions attach ID [--socket PATH] | oko sessions attach ID --relay URL

Inputs and options#

  • ID is the session; --socket names the broker that holds it (the installed one when left out), and this terminal's size is forwarded through it.
  • --relay is the relay's WebSocket URL (wss:// or https://, ws:// or http:// on loopback only); the relay credential is read only from Skarbiec.

Output and state effect#

  • Places stdin in raw mode while attached, forwards bytes and resize events, and restores terminal settings on exit. A resize the broker refuses is named on stderr.
  • The `sessions-lifecycle` qualification includes a real OS pseudo-terminal attached through the CLI to an isolated broker session. It sends unique input through the terminal, observes the broker's echo and actual raw-mode flags, ends that session, and compares restored terminal flags, control characters and speeds with their original values. The candidate-bound report retains the command, output, exit status and measured settings.
  • If the qualification fails while attached, its report records that failure before attempting cleanup. A subsequent forced-cleanup failure retains both causes instead of replacing the original attachment failure.

Refusals and safe exits#

  • A missing ID refuses with “oko sessions attach requires <id>”, and --relay together with --socket with “… --socket names a local broker, not both” (exit 2); “the broker at <socket> holds no session <id>; it holds: <ids>”, “connect failed for <socket>: <error>”, --token, an invalid relay URL or an unavailable oko-pty-relay credential exit unsuccessfully.
  • Reading terminal settings, enabling raw mode and restoring the original settings report the actual operating-system cause. An attachment failure followed by a restoration failure retains both causes; restoration failure after an otherwise successful attachment still exits unsuccessfully. This applies to local and relay attachment. Non-terminal input does not require terminal mode changes.
  • Only the operating system's not-a-terminal result selects non-terminal input. Other terminal inspection failures retain their actual cause and refuse attachment. Non-terminal attachment does not change the signal mask or start a terminal resize watcher.

CLI reference#