# Refs, kinds and environments

> The grammar every runtime command accepts, and how a command finds its environment

URL: https://pier.run/docs/cli/refs

## Ref

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

| Form             | Means                                                                       |
| ---------------- | --------------------------------------------------------------------------- |
| `api`            | the container; for a single-target app or site, its only target             |
| `api/stage`      | one target of a multi-target app or site                                    |
| `api/stage/2`    | one instance (`logs`, `ssh`)                                                |
| `--type pg main` | breaks a name shared across kinds (`app`, `site`, `pg`, `bucket`, `volume`) |
| `-e staging api` | scopes strictly to one environment                                          |

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>`:

```bash
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](/docs/cli/configuration)).