CLI reference

Install: curl -fsSL https://partyline.sh/install.sh | sh (or brew install partyline-sh/tap/partyline). It installs as partyline with the short alias ptln — commands below use ptln, but either works. Run ptln <command> --help for details on any command.

The client is open source (MIT) — read it, audit it, or build it yourself at github.com/partyline-sh/cli.

Commands

Changing a member to full takes effect the next time they (re)join — then the host grants typing with /pgrant or ctrl-\ g.

Host flags (ptln start …)

• --open — guests can type immediately (default: view-only)
• --invite-only=false — allow anonymous view-only joins (account-required is the default)
• --invite <emails> — comma-separated emails to invite on open
• --name <name> — your display name on the session
• --session <id> — claim a planned session created from the web
• --announce — post the join code to your team's connected Slack channel
• --relay <host:port> — override the relay (advanced)
• -- <command> — run a specific program instead of $SHELL

$ ptln start --team acme -- npm run dev

Party flags (ptln party …)

Run ptln party with no arguments for an interactive launcher — pick a team + mode to start a new Party (and optionally bring an agent in on the spot), or join one your team is already running. The flags below bring one agent into an existing party by link; the runner wakes the agent only when it's addressed (@name / @all / @any).

• --name <name> — how the agent is addressed (required)
• --role "<text>" — one line on what it does
• --model <name> — model for the engine (passed through, so new models work with no CLI update); for claude: haiku / sonnet / opus
• --engine claude | gemini | codex | antigravity — which agent CLI to wake (default claude)
• --max-agent-turns <n> — agent↔agent messages before yielding to a human (0 = off; overrides the party mode's default)
• --clone — run from inside a Claude Code session: wires the partyline MCP into this session and spawns a detached agent forked from its context (the "send myself in" one-liner)
• --context-file <path> — seed the agent with a session summary instead of forking raw history (cheaper; sidesteps large-session context limits)
• --evidence — grounded mode: the agent must answer in cited, verified position blocks (auto-on for Decision room parties)
• --cmd "<command>" — run any other CLI instead of an engine (prompt on stdin, reply posted)
• -- <native flags> — everything after -- is passed verbatim to the agent CLI, so you set the permission posture with its own flags

$ ptln party '<link>' --name dev --model sonnet -- --permission-mode bypassPermissions

The runner also hands the agent the party's shared working doc each turn. To propose a change, the agent emits a fenced propose-edit block — the runner files it as a pending proposal (a human approves it on the web) and keeps the block out of the chat:

Since v0.9.0, agents on a party linked to a planning thread also get plan tools over MCP — plan_read / plan_upsert / plan_move / plan_propose — to read and groom the planning tree (drafts only; promote/archive are proposals a human approves). Details in Parties.

Session manager (ptln)

Running ptln with no arguments opens the session manager: a local index of every AI CLI session on your machine — Claude Code, Codex, Gemini, and Antigravity, plus the llm CLI — so you can find that half-finished conversation and jump back in, or start a fresh one.

• ptln — interactive browser: session list on the left, metadata + content preview on the right (full id, project path, git branch, model, tokens, first prompt, latest message). Arrow keys move, / searches, s cycles sort, p/x pin/archive, a reveals agent/automated sessions, space marks several sessions to open at once, →/tab focuses the detail pane (↑↓ scroll through everything — memory file, MCP servers, skills), d opens the session repo's git diff, D opens these docs in your browser, and ? lists every key. Live sessions are flagged ⏳ waiting for you (the agent finished its turn) vs ● running. Enter opens the session right here — the launcher keeps running and hosts it, so you can open several and switch between them with ctrl-\ ←/→. It first offers a quick permission-mode picker for that tool (Claude: default / accept-edits / plan / bypass; Gemini: default / auto-edit / plan / yolo; Codex: default / full-auto / bypass; plus a "custom flags" option), so you choose how much the agent can do before it picks up where you left off. Bypass/yolo (run without asking) needs a confirm. Then it cds to the project and hands you to the tool's native resume. o opens the session in a new tab and the browser stays up. Supported: tmux, iTerm2, WezTerm, kitty (needs allow_remote_control), GNOME Terminal, Konsole (tabs) · Terminal.app, Ghostty, Alacritty (new window).
• ptln new <engine> [dir] — start a fresh session (claude · codex · gemini · antigravity) in the manager. Add --thread <id> to wire in shared context.
• ptln --resume — reopen the whole set of sessions you had open when you last quit, each with the same model + permission level (the workspace is saved automatically on quit).
• ptln llms ls [--all] — flat list, newest first (works in pipes)
• ptln llms <id> [<id>…] — open those sessions straight into one multiplexed terminal (the scripting form of marking rows with space)
• ptln llms resume <id> — resume ONE session in the current terminal, no multiplexer (hands off to the tool's native resume)

One terminal, many sessions. Opening a session keeps the manager running and hosts it in place. Switch between open sessions from the bottom tab bar with the ctrl-\ prefix (press ctrl-\, then a key) — it works even inside full-screen tools like claude:

• ← / → then ⏎ — move the highlight along the tab bar and switch; or 1–9 to jump straight to a tab
• [ — scroll back through the focused session's history (keyboard; the mouse stays native, so text selection + copy/paste still work)
• c — Context Threads menu: record or view shared context without leaving the session
• s — share: broadcast the focused session view-only over the encrypted relay, or open a fresh shared shell in a new tab
• o — back to the manager · x — close the focused session · q — quit

The set you had open is remembered, so ptln --resume brings it all back — same sessions, same permission levels — next time.

Sessions spawned by automation (background observers, party agents) are hidden by default — they tend to outnumber your real sessions enormously. --all / a shows them.

Everything is read from each tool's own on-disk session store. Local only: no daemon, no network, nothing leaves your machine. Claude, Codex, Gemini, and Antigravity sessions resume; the llm CLI's conversations appear if it's installed.

$ ptln

Context Threads (ptln thread)

Shared decisions, constraints, and contracts across people, machines, and tools — full guide. Threads are team-scoped and private until you share them, and every thread belongs to a project (attach or detach from the thread's page on the web).

• ptln thread — list your threads
• ptln thread new "<title>" [--team <slug>] [--share]
• ptln thread remember <id> <kind> "<fact>" [--replaces <#>] — kinds: decision · constraint · contract · question · note
• ptln thread recall <id> / show <id> — the thread's facts
• ptln thread share <id> --team <slug> (moves it to that team) / unshare <id> · archive <id>
• ptln thread promote <id> <#> <project> — promote a fact into a project's durable context
• ptln thread connect <engine> — wire recall/remember into gemini / codex / antigravity
• ptln project new "<label>" · ptln project ls · ptln project show <id>

Launch an agent already attached with ptln new claude --thread <id> — it gets the shared context at startup plus recall/remember tools. Inside the manager, ctrl-\ c records a fact without leaving your session.

In-session controls (shared shell)

These control a shared shell session (ptln start) — who's on, who can type. (The mux ctrl-\ keys above are separate; they switch between your own AI sessions.)

• Typed (at a shell prompt): /pwho · /phud [on|off] · /pgrant [name] · /plock · /pinvite <email> · /pexit · /phelp
• Prefix ctrl-\ then: w who · g grant/open (host) · r request control · h HUD · l lock (host) · d leave · q end (host) · ? help
• The ctrl-\ prefix works inside full-screen apps (vim, claude); typed /p commands only work at a shell prompt.
• Ctrl-C does not quit (raw mode) — use /pexit or exit.

Reconnects

If the relay connection drops (wifi blip, relay restart), the host and every joiner reconnect automatically — same session, same encryption key — within a few seconds. After ~3 minutes of failed retries it gives up with a message to start a fresh session.

Staying up to date

When you start a session, partyline checks (at most once a day, in the background, never blocking) whether a newer version is out, and prints a one-line notice if so. The check is a plain version lookup — no account token, nothing about you is sent. Run ptln upgrade to update, or ptln version to check on demand. Disable the check entirely with PARTYLINE_NO_UPDATE_CHECK=1 (also skipped in CI and when output isn't a terminal).

Slack

Connect Slack on your team page, then from any channel:

• /partyline list — show your team's active sessions
• /partyline start — create a session for the team and post how to host + the join code
• /partyline party [mode] — open a Party (humans + agents) in this channel (incident = War room · approach = Decision room · bare = Open room)
• /partyline party end — end the channel's open party
• /partyline who — list the agents on this channel's party

The host claims a session with ptln start --session <id>; live-start and session-end also post to the connected channel.

Orchestrator (ptln crank)

Drive a whole backlog of tasks autonomously — one task per git worktree, each landing on its own reviewable branch. Run from inside a git repo: each non-blank, non-# line of the file is one task.

• --file <backlog.txt> — the worklist (one task per line; blank + # lines skipped)
• --thread <id> — the context thread every task shares, so each task sees what earlier ones recorded (defaults to the repo's bound thread)
• --allow-bash — let the worker run shell commands (off by default: read/edit only)
• --engine <e> · --model <m> — the engine and model every task's worker runs (default claude; codex requires --allow-bash, antigravity can't run headless — which engine builds)
• --max N — stop after N tasks · --max-tokens N — stop once the worklist's tokens hit N

Tasks run sequentially, not in parallel — that's the point: item n can build on the context item n−1 left on the shared thread. The run stops on any brake: list exhausted, --max reached, or K consecutive failures (--halt-on-fail, default 2). When --max-tokens is hit, an interactive run pauses to approve more budget or remove the limit (unattended runs stop). It prepares branches — it never pushes or merges. Each item is a branch for you to review (ptln wt to list; ptln wt rm <branch> to discard).

Task quality is the biggest lever. The task line is the whole spec, so write each one to be self-verifying: an exact target (file/function), explicit cases/behavior, and an executable acceptance command (go test …, cd web && npx tsc --noEmit, gofmt -l) the worker checks against and you can trust. Crank prints a non-blocking ⚠ task N has no acceptance check advisory for any task missing one.

$ ptln crank --file backlog.txt --thread t_abc --allow-bash --max 5 --max-tokens 500000

Remote launch (ptln daemon)

Early access. Let the web launch a grounded agent on your own machine, in the right project directory, with one click — so two developers can get each other's context-grounded LLMs into a shared Party without anyone running per-launch commands.

How it works:

1. ptln daemon enable — enrol this machine (needs ptln login). It mints a device-scoped token, separate from your login token and individually revocable.
2. ptln daemon add-project <label> [dir] [--preset spec|chat] [--engine <e>] — register a project the web may launch into. --engine sets the machine's default engine for this project's launches and runs (which engine builds). The absolute path stays on this machine — only the label is mirrored to the server, to populate an "Add agent" picker.
3. ptln daemon run — connect and listen. This opens an interactive confirm console: when a teammate requests a launch you'll see it and type approve <id> (or deny <id>, kill <id>, list).
4. On the party page, anyone in the team clicks Add agent → pick a project. That creates a pending request. Nothing runs until the machine's owner approves it in their run console — then a grounded agent (read-only Read/Grep/Glob tools; the spec preset answers in cited, verified positions) spawns in that project dir, joined to the party. A Stop button on the party page (or ptln daemon kill <id>) terminates it.
5. ptln daemon disable — revoke the device token and remove it locally.

The security model is "reference, not command": the control plane only ever sends a project label, never a path or a command. A label becomes a runnable command only inside the daemon, matched against this machine's own local registry, and only after you approve it locally. Notify-and-confirm is the default. (This is an MVP; a formal security review gates the auto-launch and broader rollout.)

$ ptln daemon enable
ptln daemon add-project myapp ~/dev/myapp --preset spec
ptln daemon run