# The pier CLI

> One rule shapes every command — the environment is the unit of work

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

`pier` acts on the **current environment**. A command is top-level when it reads or
changes what is in that environment; it sits under a noun only when the noun has
vocabulary of its own.

| You want to              | Say                                       | Grammar                                  |
| ------------------------ | ----------------------------------------- | ---------------------------------------- |
| act on something running | `pier logs api`, `pier restart api/stage` | runtime verb + [`<ref>`](/docs/cli/refs) |
| change what is declared  | `pier add app`, `pier rm site www`        | config verb + `<kind>`                   |
| see what is here         | `pier ls`, `pier status`, `pier deploys`  | a read verb; bare nouns list             |
| switch scope             | `pier use staging`, `pier projects use`   | `use`, and only `use`                    |

There are no aliases: one spelling per command. A retired spelling answers with the
current one (`pier apps list` → `try: pier ls apps`). `--json` and `-y` make any command
scriptable ([Scripting](/docs/cli/scripting)).

## The five groups

`pier --help` lists commands in five groups, ordered by how often each is reached for.
The [reference](/docs/cli/reference) uses the same groups.

| Group                   | Commands                                                                                                              |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
| Inspect the environment | `status`, `ls`, `info`, `logs`, `events`, `monitor`, `deploys`                                                        |
| Change the environment  | `apply`, `deploy`, `add`, `set`, `rm`, `trash`, `copy`, `rename`, `promote`, `restart`, `rollback`, `pause`, `resume` |
| Connect & data          | `ssh`, `psql`, `vars`, `routes`, `pg`, `objects`, `snapshots`, `backups`, `github`, `dev`                             |
| Project & scope         | `config`, `use`, `projects`, `environments`, `workspaces`                                                             |
| CLI & account           | `login`, `logout`, `whoami`, `profiles`, `billing`, `ssh-key`, `upgrade`, `uninstall`                                 |

## Verbs and nouns

* **Runtime verbs take a `<ref>`**: `logs`, `info`, `monitor`, `restart`, `rollback`,
  `promote`, `ssh`, `deploy`. The ref names something running.
* **Config verbs take a `<kind>`**: `add`, `set`, `rm` with `app`, `site`, `pg`, `bucket`,
  `volume`, `domain` or `target`. They edit the declaration, as editing `pier.yaml` does;
  with `--stage` they edit only `pier.yaml`.
* **Reads are verbs**: `status`, `ls`, `info`, `logs`, `events`, `monitor`, `deploys`.
  With no argument they show the environment or open a picker.
* **Child data and keyed lists are nouns**: `objects`, `snapshots`, `backups`, `vars`,
  `routes`. Each has its own verbs (`put`, `create`, `set`, `reveal`, …).
* **A bare noun lists** (`pier deploys`, `pier vars`, `pier projects`). It never opens a
  selector; `use` is the one switch verb.

## Spelling

`ls`, `add`, `set` and `rm` are abbreviated because they are the most frequent commands.
`copy`, `rename`, `promote`, `restore` and `purge` are infrequent and are full words.
`create` is used only for artifacts that are taken rather than declared (`snapshots
create`, `backups create`). Kinds are singular on verbs (`add app`) and plural on `ls`
(`ls apps`). Postgres is spelled `pg` in every command.