# Pause and resume

> Stop a resource, an environment, a project or a workspace and keep everything — and what happens when the platform pauses you

URL: https://pier.run/docs/pause-and-resume

Pausing stops the running parts of something and keeps its data, configuration,
hostnames and history. Resuming brings it back as it was. The verbs are the same at every
scope.

```bash
pier pause api
```

```text title="output"
OK  Paused app "api"
→  [22:36:07] active

```

```bash
pier ls apps
```

```text title="output"
                                                                                       
 NAME STATUS REPLICAS AUTOSCALE IMAGE                                    PORT UPDATED  
                                                                                       
 api  paused 1/1      -         zot.pier-registry.svc.cluster.local:5... 8080 just now 
                                                                                       

```

```bash
pier resume api
```

```text title="output"
OK  Resumed app "api"
→  [22:36:07] resumed

```

## Scopes

| Command                                                                        | Pauses                            |
| ------------------------------------------------------------------------------ | --------------------------------- |
| `pier pause api`, `pier pause api/canary`, `pier pause main`, `pier pause www` | one resource or one target        |
| `pier environments pause staging`                                              | every resource in the environment |
| `pier projects pause acme`                                                     | every environment of the project  |
| `pier workspaces pause`                                                        | everything in the workspace       |

A paused app keeps its hostname, which answers with an error page; a paused Postgres keeps
its data and stops accepting connections; a paused site is not served. Buckets and volumes
pause with their environment. A deploy into a paused target offers to resume it first
(`--no-resume` fails instead, for CI).

A pause requested with `pier pause` does not expire: it is recorded with the reason
`user_paused`, and only `pier resume` clears it. A paused app is not billed for compute;
its storage is billed.

## When the platform pauses you

The platform pauses a whole workspace for three reasons. The reason is shown in the
console, in `pier billing overview`, and in an email:

| Reason           | Trigger                                                                 | Recovery window                      | Resumes when                               |
| ---------------- | ----------------------------------------------------------------------- | ------------------------------------ | ------------------------------------------ |
| `cap_hit`        | overage spend reached the workspace [cap](/docs/workspaces-and-billing) | never purged; held storage is billed | the cap is raised or the period rolls over |
| `payment_failed` | an invoice is seven days past due                                       | 30 days, then purged                 | the invoice is paid                        |
| `trial_expired`  | the trial's grant or its 14 days ran out                                | 7 days, then purged                  | a plan is chosen                           |

A system pause cannot be lifted with `pier resume`; it is resolved through billing.
`pier events --all-projects --severity warn` shows the enforcement events.

## Removed resources

`pier rm` is a pause with a 30-day clock: the resource leaves the environment, its data is
kept, `pier trash` lists it, `pier trash restore <type> <name>` brings it back
(config-external until re-declared in `pier.yaml`), `pier trash purge` ends the window.
[Concepts: trash](/docs/concepts#trash).

## See also

[`pier pause`](/docs/cli/reference/pause) · [`pier resume`](/docs/cli/reference/resume) ·
[`pier trash`](/docs/cli/reference/trash) · [Workspaces and billing](/docs/workspaces-and-billing)