The pier CLI
One rule shapes every command — the environment is the unit of work
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> |
| 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).
The five groups
pier --help lists commands in five groups, ordered by how often each is reached for.
The 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,rmwithapp,site,pg,bucket,volume,domainortarget. They edit the declaration, as editingpier.yamldoes; with--stagethey edit onlypier.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;useis 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.