Apply and deploy

pier.yaml is the source of truth; apply converges declarations, deploy builds and rolls what changed

Two verbs move the platform toward pier.yaml.

Verb	Does	Never does
`pier apply`	creates, changes and removes resources so the environment matches the file; applies scaling and variables	builds; rolls a target for a source change
`pier deploy`	everything `apply` does, then builds and rolls the targets whose source, image or port changed	—

Both print a plan and ask for confirmation (-y to skip); --dry-run on apply prints the plan only.

output

→  Comparing prod environment against platform state...

  Changes:
    + create environment "prod" (new environment)
    + create app "api" in prod (plan: app-s, replicas: 1)
    + create postgres "main" in prod (plan: pg-s, version: 17, replicas: 1)
    + create bucket "uploads" in prod (access: private)
    + create site "www" in prod

  Deploy:
    app "api"    build (first deploy)
    site "www"    build required (new resource — initial build required)
    postgres "main"    deploy (deployed inline)
    bucket "uploads"    deploy (deployed inline)

OK  Applied 5 config change(s) to prod
→  Building api from ./api
→  Building pier-build/api:latest...

→  Pushing registry.pier.run/01a05313-e4fa-7707-a014-05f1ae901cec/api:9eed0df...
9eed0df: digest: sha256:13e134f00256cce6b3bc076b2671fb63dca2eee0bfb14509576612703a39c662 size: 855
OK  Pushed registry.pier.run/01a05313-e4fa-7707-a014-05f1ae901cec/api:9eed0df
→  Deploying api...
→  Found 1 site files to deploy
→  Uploading 1 files...
OK  All files uploaded
→  Waiting for infrastructure provisioning...
OK  Infrastructure ready

OK  Summary: 1 built, 4 deployed

What is a change

Kind of change	Applied by	Effect
a resource added or removed	`apply`	created; removed to trash
`plan`, `replicas`, `autoscale`	`apply`	immediate; a plan change rolls the target
a variable	`apply`	new environment version; the targets that read it roll
`build_context` contents, `dockerfile`, `image`, `port`	`deploy`	a new deploy: build (if needed) and roll
`name`	`apply`	display only

A change apply will not release is staged: pier status lists it, and the next pier deploy releases it.

Staged edits

pier add, pier set and pier rm apply immediately. With --stage they only edit pier.yaml, so several edits can be reviewed in one diff and applied together:

pier add pg --name main --plan pg-s --default-db app --stage
pier set app api --plan app-m --stage
git diff pier.yaml
pier apply

pier apply removes what the file no longer declares only with --prune; without it a missing resource is reported and kept. --prune-external on deploy also removes resources that were never in the file (created from the console or the API). --purge skips the 30-day recovery window.

Renames

A renamed resource is treated as a delete and a create unless the rename is declared: pier apply --rename apps.api=gateway (or pier rename) keeps the hostname, history and data.

Apply and deploy

What is a change

Staged edits

Removals

Renames

See also

On this page