CLI reference

pier                      the TUI: sessions live-updating
                          enter attach · n new · d delete · p pin · m resize · l logs · s settings · r refresh · q quit
pier <branch> [base]      new session off base (default HEAD), then attach
    -d, --detach          create without attaching
    --idle <dur|never>    idle self-park timeout (default 30m)
    --cap <dur|never>     unattended runaway cap (default 8h)
    --no-park             shorthand for --idle never
pier ls                   plain list (pipeable)
pier attach <session>     attach (parked sessions auto-resume, ~20-60s)
pier logs <session>       show the setup script log (-f follows)
pier rm <session> [-f]    destroy the session and its disk
pier keep <session>       pin: disable idle self-park
pier resize <session> <type>   grow/shrink the VM (~1-2 min, same CPU arch)
pier bake                 prebake this repo's session image (~1-2 min creates)
pier mcp login <session>  one-time browser approvals for OAuth MCP servers
pier proxy                every running session as <session>.pier (macOS)
pier port <session> <p>   manual port forward (8080:3000 = local:session)
pier doctor               environment + account checks
pier teardown             remove all pier groundwork from the account
pier setup                the one-time account wizard

The TUI

Run pier with no arguments. Sessions live-update in place:

The TUI uses the terminal’s full-screen alternate buffer, so quitting restores your shell untouched. Attachments open inside the TUI; detaching from tmux with C-b d returns to the session list. The setup-log viewer also stays in the TUI, live-follows a running setup, and returns to the list with esc.

Key	Action
enter	attach (parked sessions resume first)
n	new session
d	delete
p	pin (disable idle self-park)
m	resize
l	show the setup log
s	settings
r	refresh
q	quit

pier ls stays plain and pipeable on purpose. The TUI is the pretty view.

If an aws login session expires, the TUI offers enter to reauthenticate and refresh the list in place.