Refs, kinds and environments

Ref

A <ref> names something running. Every runtime verb accepts the same forms:

Resolution:

• An explicit ref must match exactly one thing; a name that matches several kinds needs --type.
• With no ref on a terminal, the command opens a picker listing what it accepts. A lone candidate is selected without a prompt.
• A bare name of a multi-target app opens a picker for actions (restart, logs), because an action never guesses a target. For info it shows the container view, since the container is a valid answer there.
• Without -e, every environment of the project is searched and the active one breaks a tie. -e is for one invocation only; it never changes what a later bare command targets.

Kind

Config verbs name a declaration, not a running thing, so they take a <kind>:

pier add app        # app · site · pg · bucket · volume · domain · target
pier set app api --plan app-m
pier rm site www
pier ls apps        # plural on ls: apps · sites · pg · buckets · volumes · domains

Environment

The environment a command acts in comes from, in order:

1. -e <slug>: this invocation only, never saved.
2. The sticky selection: pier use <slug>, or a picker the user accepted.
3. Auto-select, when the project has exactly one environment.

pier status prints the active environment; pier use with no argument opens the picker.

Project

The project comes from the nearest pier.yaml above the current directory (its project: key), then -p <name>, then the selection saved by pier projects use. Commands run inside the repository need no project flag (Configuration).