# Apply and deploy

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

URL: https://pier.run/docs/apply-and-deploy

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.

```text title="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](/docs/concepts#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:

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

## Removals

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

## See also

[Concepts: apply, deploy, staged](/docs/concepts#apply-deploy-staged) · [`pier apply`](/docs/cli/reference/apply) ·
[`pier deploy`](/docs/cli/reference/deploy) · [`pier status`](/docs/cli/reference/status)