Watching in a terminal

porthole join connects to a session and renders it in the terminal you are already sitting in.

porthole join p3rx-9kma

It accepts a bare code, a full link, or an invite link — in which case the secret is read from the link and never printed.

Press Ctrl+] to disconnect.

Why not just use the browser

This is the same peer-to-peer WebRTC DataChannel the browser viewer uses. The difference is who draws the screen.

The browser viewer renders through xterm.js. porthole join writes the raw stream to your own terminal emulator, so the thing interpreting the escape sequences is the same program that interprets them for every other command you run. Interactive full-screen programs — vim, htop, less, tmux — behave exactly as they do over SSH, because architecturally this is the same arrangement.

You also get your terminal's own scrollback, font, colours, and selection behaviour, and you never leave the keyboard.

Read-only by default

Sessions are read-only unless the host says otherwise.

porthole join p3rx-9kma --write

--write asks the host for input access. It does not grant it — the host approves with Ctrl+] w, or has started the session with --auto-approve. Until then you are watching.

--readonly states the default explicitly, which is useful in a script or an alias where the intent should be obvious to whoever reads it later.

Identifying yourself

porthole join p3rx-9kma --name "Ali"

The name is printed on the host's terminal when you connect and disconnect. It is self-reported and not verified — it is a label so the host knows who turned up, not an identity claim.

Terminal size

By default the size reported to the host tracks your window, and resizing renegotiates. Pin it when you do not want that:

porthole join p3rx-9kma --cols 220 --rows 50

Pinning is useful when several people are watching and you would rather the host's shell not reflow every time one of you resizes.

Recording what you are shown

porthole join p3rx-9kma --record session.cast

Writes an asciicast file of the stream as you received it, replayable with porthole replay.

Full flag list

See the CLI reference.