CLI reference

pier                      the app: Sessions · Repos · Settings tabs (? for keys)
pier <branch> [base]      new session off base (default HEAD), then attach
    -d, --detach          create without attaching
    --idle <dur|never>    park after this much idle time (default from settings)
    --cap <dur|never>     unattended runaway cap (default 8h)
    --no-park             shorthand for --idle never
    --no-pool             launch fresh instead of claiming a pooled session
pier ls [--json]          plain list, or stable JSON for automation
pier attach <session>     attach (a parked session resumes, ~20-60s, tmux restored)
pier logs <session>       show the setup script log (-f follows)
pier rm <session> [-f]    destroy the session and its disk
pier keep <session>       pin: never park when idle
pier resize <session> <type>   grow/shrink the VM (~1-2 min, same CPU arch)
pier repos [--json]       every repo: session image, pool, idle cost, tips
pier bake                 build this repo's session image (repo prebuilt by default)
    --toolchain-only      keep repo state out of the image for this bake
    --with-repo           prebuild the repo into the image for this bake
pier pool                 this repo's pool (set <n> | fill [-d] | drain [repo])
pier proxy                every running session as <session>.pier (macOS)
pier port <session> <p>   manual port forward (8080:3000 = local:session)
pier setup [--skills]     first-time setup; --skills only refreshes the agent skill
    --print-admin         print the account setup for a cloud admin to run
pier doctor               environment + account checks
pier teardown             remove all pier groundwork from the account
pier version              print the pier version

JSON output

For automation, pier ls --json writes a JSON array with stable fields: id, name, repository, branch, owner, provider, state, setup_state, strained, created_at, machine_type, and cost_note. created_at is an RFC 3339 UTC timestamp, or null when unavailable; setup_state is empty when no running or failed setup is reported. The JSON mode writes no ANSI styling or explanatory prose to stdout.

pier ls shows the same steady states as the app (starting, running, parked, deleting, create failed). pier ls --json keeps the detailed ones.

The app

Run pier with no arguments. Three tabs, switched with tab, ← →, or 1 2 3:

• Sessions. Every session with a state dot and a detail pane: attach, logs, resize, keep, delete. Rows read starting, running, parked, deleting, or create failed. What the session is doing right now (agent working, quiet, you’re attached) lives in the detail pane.
• Repos. Each repo’s session image, pool, idle cost, and reminders.
• Settings. One page grouped into Cloud, New sessions, Idle & cost, Speed, and Appearance, showing only the active cloud’s fields with a line on what each changes. See Configuration.

The header keeps running and parked counts and the live hourly cost in view. Attaching stays in the app until the session answers, then hands over to it. Detaching from tmux with C-b d returns to the app.

Key	Action
enter	attach (a parked session resumes with tmux restored)
n	new session from this repo (runs in the background)
l	setup log, live
m	resize the VM
p	keep: never park when idle
d	destroy (or clear a failed create)
b	Repos: bake this repo’s session image
+ / -	Repos: pool size
f	Repos: fill the pool now
x	Repos: drain a repo’s pool
s	settings
r	refresh
?	every key
q	quit

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

If your cloud login expires, the app offers enter to sign in again and refreshes the list in place.