Sessions

A session is one shared terminal. The host runs a real shell (or any program); everyone else mirrors it live over the encrypted relay.

Host a session

$ ptln start

(Bare ptln opens your session manager; hosting a shared shell is always ptln start.)

Useful flags:

  • --open — guests can type immediately (default: view-only until granted)
  • --invite-only=false — allow anonymous view-only joins from the bare link. By default (--invite-only, on) joining requires a partyline account
  • --team <slug> — host the session for a team (its members can see it)
  • --invite a@x.com,b@y.com — invite by email when the session opens
  • -- <command> — run a specific program instead of your $SHELL, e.g. ptln start -- vim notes.md

Join a session

$ ptln join 'https://partyline.sh/j/<code>#k=<key>'

Joining requires a partyline account, so the host always sees exactly who's on the line. You start view-only.

Who can drive — personal vs team

Watching is free; driving is paid. Who can take the keyboard depends on where the session lives:

  • Personal session (ptln start): you drive, everyone else watches. It's your terminal to share. To collaborate with more than one driver, host for a team.
  • Team session (ptln start --team <slug>): members with Full access can be granted the keyboard; Viewers watch only. Viewers are free and unlimited — see Team & members.

Requesting control: press ctrl-\ then r — the host gets a notice and can grant you with ctrl-\ g (opens typing to all full-access guests) or /pgrant <name> (just you). This works inside full-screen apps too.

A viewer can't be granted typing, no matter how often they ask — full access is a driver seat. The host promotes them first with ptln team access <handle> full (or the team page); the member then rejoins to pick it up, and then the grant works.

Roles & control

  • Host — owns the session; grants/revokes typing; ends it; can kick or lock.
  • Full access — can host, and can be granted the keyboard. Paid seat.
  • Viewer — watch-only, always free. Cannot type, even if granted.
  • Everyone on the line is a verified partyline user (shown with ✓).

Screen size

The shared terminal is sized to the smallest connected screen — the same rule tmux and screen use. That way everyone sees an identical layout with no line-wrapping or redraw artifacts, even across very different window sizes. If a joiner has a small window, the whole session shrinks to fit them; resize any window and the session re-clamps live to the largest size that still fits everyone. For the roomiest session, have everyone maximize their terminal.

Reconnecting

If the connection drops — a wifi blip, the relay restarting — partyline reconnects on its own. The host re-establishes the relay (same session, same key) and joiners re-attach within seconds; the screen repaints and you carry on. After ~3 minutes of failed retries it gives up and tells you to start a fresh session. A clean host exit (/pexit) ends it for everyone immediately — no reconnect attempts.

Quitting

Ctrl-C is passed through to the shell (raw mode), so it won't quit partyline. End or leave with:

  • Host: /pexit or ctrl-\ q (ends the session for everyone)
  • Guest: /pexit or ctrl-\ d (you leave)