CLI reference
Commands for managing sessions, sharing repository knowledge and coordinating agents. Start with Quickstart for a working example; use this page to look up a command.
The binary is partyline; ptln is a symlink to it. ptln <command> --help prints one command's
usage and ptln man prints the manual. Source: github.com/partyline-sh/cli, MIT licence.
Sessions
Details: Sessions.
| Command | Does what |
|---|---|
ptln | open the session manager (the first-run screen when there are no sessions) |
ptln new <engine> [dir] [flags] | start a session. Engines: claude, codex, gemini, opencode, goose, antigravity. Arguments after [dir] are not passed to the engine. |
ptln --resume | reopen the sessions open when you last quit, with the same models and permission modes |
ptln llms ls [--all] | list sessions, newest first. --all includes sessions started by other agents. |
ptln llms <id>... | open those sessions in one terminal |
ptln llms resume <id> | resume one session in this terminal, without the multiplexer |
ptln llms prune [--apply] | list sessions whose worktree is gone, skipping running ones. --apply moves them to the trash. |
ptln llms --roots · --look-in <dir> | print where sessions are read from · also read them under another home directory |
ptln tmux --resume · --quit · --print-conf | reopen the saved set · save the set, then stop every session and the tmux server · print the generated tmux configuration |
ptln wt ls · rm <branch|path> [--yes] · prune [--yes] | list every git worktree of this repository · remove one, after asking · list clean worktrees on crank-* branches left by older versions; --yes removes them |
ptln keepgoing [status|off] | list Claude sessions with keep-going armed · disarm it on all of them |
ptln new flags:
| Flag | Does what |
|---|---|
--worktree <name> | create a git worktree on a new branch <name> and start the session in it |
--with-state | with --worktree: copy uncommitted changes and untracked files into the new worktree |
--keep-going N | Claude only: request continuation when a turn ends, up to N times |
--goal <text> | the instruction given with each keep-going continuation |
Repo memory
Details: Repo memory.
| Command | Does what |
|---|---|
ptln memory build [--apply] [--refresh] [--remove-stale] | set up or refresh: a project overview (generated when there is none), build/test/CI facts, open questions on first setup. Prints only, until --apply. --refresh rewrites the overview from the last commit; --remove-stale deletes derived facts whose evidence is gone. |
ptln memory add <kind> "..." | record a fact. Kinds: overview, decision, constraint, contract, gotcha, question. Flags: --tags a,b, --supersedes <id>. |
ptln memory ls [--all] | current facts; --all includes superseded ones |
ptln memory brief | what a session is told at start |
ptln memory edit <id> "..." · append <id> "..." · rm <id> | rewrite, extend or delete a fact |
ptln memory verify <id>... | mark facts as checked against the code at HEAD |
ptln memory where | where the facts are, and how many |
ptln memory map | rewrite the generated block in existing AGENTS.md, CLAUDE.md and GEMINI.md; create AGENTS.md if none exists |
ptln memory hooks [--install] | which engines refresh facts during a session, and which need a trust grant |
ptln memory harvest [-n] [--since <rev>] | legacy side-repo projects only: record facts declared in Ptln-<Kind>: commit trailers; -n prints only |
ptln memory propose --from <src> <kind> "..." | legacy side-repo projects only: record a fact from another system, with at least one citation |
Chat
Details: Chat.
| Command | Does what |
|---|---|
ptln chat | open the room. In it: /add <tab>..., /remove <tab>, /who, /stop [tab], /go [tab], /clear, /help; @<tab> or @<engine> addresses one session; Shift-⏎ adds a line break; ctrl-c leaves. Chat lists the editing keys. |
ptln chat add <tab>... · remove <tab>... | change members from outside the room |
ptln chat who | members, and whether each one is listening |
ptln chat send "..." · read · listen | what sessions run: post a reply · print waiting messages · wait for one message and exit |
Loops
Details: Loops. ptln loop is experimental and not listed in ptln help.
| Command | Does what |
|---|---|
ptln loop guide | the loop workflow, brief template and report template for the calling session |
ptln loop start --brief <file> --checks "<cmd>" · ptln loop batch start --brief <file> --brief <file> ... --checks "<cmd>" | start a single run · a batch (run by a session) |
ptln loop status [<id>] · ptln loop tab | every loop, or one · the Loops board full-screen (ctrl-\ l as a popup) |
ptln loop delete <id> | stop a loop, or its whole batch, and remove it for good |
ptln loop --help lists every loop subcommand.
Mobile remote
| Command | Does what |
|---|---|
ptln relay setup | review hosting and service setup, or join a private gateway after comparing a code |
ptln relay discover · ptln relay approve | find nearby gateways · compare and approve a computer on the owner host |
ptln relay service start|stop|restart|status | manage the private gateway user service |
ptln relay serve · ptln relay deploy | run the Go relay · deploy the Cloudflare Worker |
ptln remote pair · ptln remote phones · ptln remote revoke <id> | approve a phone · list phones · revoke one |
The native iOS/Android app and browser client pair separately with each computer.
Native Attach adds a computer-side path to a draft after a confirmed transfer;
it never sends the draft. Limits are 20 MiB per file and 200 MiB cached per phone.
Phone layout is opt-in and also narrows the computer's single-pane window.
Connection errors are in ~/.partyline/remote/session.log (latest 200 lines).
See Mobile remote for availability, paths, limits and recovery.
ptln remote --help and ptln relay --help contain the command reference.
This machine
| Command | Does what |
|---|---|
ptln state | JSON: live sessions, how many are waiting for input, the provider rate limit if one applies |
ptln tray [on|off] | macOS menu-bar icon (below) |
ptln theme [Partyline|Blue|Mono|Paperwhite] [--background auto|dark|light] [--motion on|off] [--glyphs auto|ascii] | palette, background, motion and status glyph preferences |
ptln upgrade | update the way partyline was installed: brew upgrade for Homebrew, otherwise the install script. ptln update is an alias. |
ptln version | the version, and whether a newer release exists |
ptln welcome · ptln man · ptln help | the first-run screen · the manual · the command list |
Updates
At most once a day, in the background, partyline reads the latest release tag from GitHub's API for
partyline-sh/cli; when a newer version exists, the session manager says so. The request includes no install identifier, account, repository path or content. GitHub sees the
request IP address. It is skipped in CI, for dev builds, and with PARTYLINE_NO_UPDATE_CHECK=1
or NO_UPDATE_NOTIFIER=1. ptln version checks immediately.
The macOS tray
ptln tray on adds a menu-bar icon and a login item; ptln tray off removes both. With no argument
it prints whether the tray is on.
The menu lists live sessions and which are waiting for input; that count is the badge. It shows the provider rate limit when one applies, and opens the session manager. A notification fires when the number of sessions waiting for input goes up; it names the engine and directory and never includes transcript text.
The tray reads ptln state. It makes no network requests and opens no ports.
tmux 3.3 or newer is required to host sessions.
Environment
| Variable | Effect |
|---|---|
PARTYLINE_MEMORY_REFRESH=off | disable per-turn memory refresh; instruction-file memory still applies |
PARTYLINE_MEMORY_CAPTURE=off | disable automatic capture; explicit memory commands still work |
PARTYLINE_ENGINE | the engine N starts: claude, codex, gemini or antigravity |
PARTYLINE_TMUX_SOCKET | the tmux socket name (default partyline) |
PARTYLINE_NO_UPDATE_CHECK=1 | no update check |
docs/reference/environment.md lists every variable the code reads.
Status motion
Working indicators use bracketed activity meters in Sessions, Chat and the Loops board. They show observed work, not a percentage estimate. Paused, idle and needs-you states are static; review completion counts come from recorded reviewer results.
ptln theme --motion off (or --still) saves reduced motion; --motion on restores it.
ptln theme --glyphs ascii saves ASCII status signals; --glyphs auto restores automatic
glyph selection. PARTYLINE_STILL=1 disables animation for a process; NO_COLOR and the C/POSIX
locale select ASCII signal glyphs. These preferences affect status indicators, not agent output.
Frame ticks update presentation only. Idle views schedule no animation/visibility watch. Sessions refresh their existing data source every five seconds while visible; hidden views only retry visibility at that slower interval. Chat and Loops keep their existing data-refresh rates. Visibility is checked once a second while motion is active; motion stops when the tmux pane/window is inactive or the session is detached. Focus reports are honored where the terminal forwards them. Partyline does not enable global tmux focus reporting or change agent-pane dimensions for this feature.