# All commands > The complete pier reference on one page, for search and for agents URL: https://pier.run/docs/cli/reference/all Every command with its arguments and flags. Per-command pages: [CLI reference](/docs/cli/reference). ## Global flags | Flag | Value | Default | Description | | ------------------- | -------- | ------- | -------------------------------------------------------------------------------------- | | `-v`, `--version` | | | Print version | | `-j`, `--json` | | | Output as JSON | | `--no-color` | | | Disable colored output (env `NO_COLOR`) | | `-w`, `--workspace` | `STRING` | | Override default workspace (name or ID) | | `-p`, `--project` | `STRING` | | Override default project (name, slug, or ID) (env `PIER_PROJECT`) | | `-e`, `--env` | `STRING` | | Target this environment for this command only (slug); use 'pier use' to switch | | `--profile` | `STRING` | | Use a named session profile for this invocation (e.g. local, dev) (env `PIER_PROFILE`) | | `--no-state` | | | Ignore saved selections, always prompt | ## Inspect the environment ### pier status ```bash pier status ``` Project state, resource counts, config drift. ### pier logs ```bash pier logs [] [flags] ``` Read or follow logs for an app, a Postgres, or the whole environment. | Argument | Required | Description | | -------- | -------- | ---------------------------------------------------------------------------------- | | `` | no | App or Postgres to read (name, name/target, or name/target/instance); omit to pick | | Flag | Value | Default | Description | | ---------------- | ----------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- | | `--type` | `STRING` | | Disambiguate a name shared by several kinds: app or pg | | `--all` | | | Every app in the environment (skips the picker) | | `--tail` | `100` | `100` | Max lines | | `--since` | | `1h` | Lookback: a duration (30m, 6h, 7d) or an RFC3339 time | | `--query` | `STRING` | | Search filter (Quickwit syntax; a bare word matches the message; substring-only with --follow) | | `--level` | `LEVEL,...` | | Only these levels (repeatable). Apps: INFO WARN ERROR FATAL DEBUG TRACE; Postgres: LOG INFO NOTICE WARNING ERROR FATAL DEBUG | | `--instance` | `STRING` | | Apps: one instance (name or pod suffix) — the same as a third ref segment | | `-f`, `--follow` | | | Keep streaming new lines until Ctrl-C (apps and environments) | | `--utc` | | | Timestamps in UTC instead of local time | ### pier events ```bash pier events [] [flags] ``` Show or watch events for a resource, the environment, the project or the workspace. | Argument | Required | Description | | -------- | -------- | ------------------------------------------------------------ | | `` | no | Resource (name, or name/target for one target); omit to pick | | Flag | Value | Default | Description | | ----------------- | -------------- | ------- | ---------------------------------------------------------------------------- | | `--type` | `STRING` | | Disambiguate a name shared by several kinds: app, site, pg, bucket or volume | | `--all-envs` | | | Every environment of the project (skips the picker) | | `--all-projects` | | | The whole workspace (skips the picker) | | `--kind` | `KIND,...` | | intent \| milestone \| activity (repeatable) | | `--action` | `ACTION,...` | | Exact action match e.g. app.created (repeatable) | | `--action-prefix` | `STRING` | | Action prefix e.g. app. matches every app.\* event | | `--severity` | `SEVERITY,...` | | info \| warn \| error \| critical (repeatable) | | `--actor` | `STRING` | | Filter by actor user ID | | `--intent` | `STRING` | | All events for one intent ID | | `--operation` | `STRING` | | All events for one operation (op\_...) | | `--since` | `STRING` | | Lower bound: a duration (30m, 6h, 7d) or an RFC3339 time | | `--until` | `STRING` | | Upper bound: a duration ago or an RFC3339 time | | `--limit` | `50` | `50` | Max events (server caps at 200) | | `--after` | `STRING` | | Continue from a previous page's next\_cursor (--json) | | `--payload` | | | Include each event's payload (--json) | | `--watch` | | | Keep printing new events until Ctrl-C | | `--utc` | | | Absolute UTC timestamps instead of relative | ### pier monitor ```bash pier monitor [] [flags] ``` Monitor a resource or the whole environment: live snapshot, --range summary, --metric drill-down. | Argument | Required | Description | | -------- | -------- | ----------------------------------------------------- | | `` | no | Resource to show (name, or name/target); omit to pick | | Flag | Value | Default | Description | | --------------- | -------- | ------- | -------------------------------------------------------------------------------------------- | | `--type` | `STRING` | | Disambiguate a name shared by several kinds: app, site, pg, bucket or volume | | `--all` | | | Show every resource in the environment (the overview) without the picker | | `--range` | `24h` | | Summarise a window instead of the live snapshot (1h, 6h, 24h, 7d, 30d) | | `--metric` | `STRING` | | Show one measure's series over the window (e.g. cpu\_pct, latency\_p95\_ms); implies --range | | `--by-instance` | | | With --metric on an app: one column per instance for cpu\_pct/memory\_pct | ### pier deploys ```bash pier deploys ``` Deploy history (apps + sites), incl. build logs. #### pier deploys ls ```bash pier deploys ls [] [flags] ``` List deploys (apps + sites). | Argument | Required | Description | | -------- | -------- | ------------------------------------------------ | | `` | no | Narrow to one app or site (slug, or slug/target) | | Flag | Value | Default | Description | | ------------ | -------- | ------- | ---------------------------------------------------------------------- | | `--type` | `STRING` | | Filter by resource type: app or site | | `--limit` | `INT` | | Max rows (server default 50, max 200) | | `--system` | | | Include platform-initiated rollouts (drift repair, resume, relocation) | | `--all-envs` | | | Every environment (default: the current one only) | #### pier deploys info ```bash pier deploys info [] ``` Show deploy details. | Argument | Required | Description | | -------- | -------- | ------------------------------------------------------------- | | `` | no | Deploy ID (build\_…); picked from recent deploys when omitted | #### pier deploys logs ```bash pier deploys logs [] [flags] ``` Show build logs for a deploy. | Argument | Required | Description | | -------- | -------- | ------------------------------------------------------------- | | `` | no | Deploy ID (build\_…); picked from recent deploys when omitted | | Flag | Value | Default | Description | | ---------------- | -------- | ------- | ---------------------------------------------------- | | `--tail` | `2000` | `2000` | Max log lines | | `--query` | `STRING` | | Full-text search filter | | `-f`, `--follow` | | | Follow the live log stream until the build completes | ### pier ls ```bash pier ls [] ``` What's in the environment; a kind (apps, sites, pg, buckets, volumes, domains) narrows it. | Argument | Required | Description | | -------- | -------- | -------------------------------------------------------------- | | `` | no | Narrow to one kind: apps, sites, pg, buckets, volumes, domains | ### pier info ```bash pier info [] [flags] ``` One resource in full: an app or site with its targets, one target, a Postgres, bucket, volume or domain. | Argument | Required | Description | | -------- | -------- | ---------------------------------------------------------------------- | | `` | no | Resource to show (name, name/target, or a custom domain); omit to pick | | Flag | Value | Default | Description | | -------- | -------- | ------- | ------------------------------------------------------------------------------------ | | `--type` | `STRING` | | Disambiguate a name shared by several kinds: app, site, pg, bucket, volume or domain | ## Change the environment ### pier apply ```bash pier apply [] [flags] ``` Converge pier.yaml: add, set and remove resources — never rolls a workload. | Argument | Required | Description | | -------- | -------- | ---------------------------------------- | | `` | no | Path to pier.yaml (default: auto-detect) | | Flag | Value | Default | Description | | ------------- | ------------------ | ------- | --------------------------------------------------------------------------------------------------- | | `--dry-run` | | | Preview changes without applying | | `-y`, `--yes` | | | Skip confirmation prompt | | `--prune` | | | Delete resources not in pier.yaml | | `--all-envs` | | | Apply all environments (default: current env only) | | `--purge` | | | Deletes in this apply skip the 30-day recovery window (torn down immediately) | | `--rename` | `KIND.OLD=NEW,...` | | Apply a rename in place instead of delete+create (KIND.OLD=NEW, e.g. apps.api=gateway). Repeatable. | ### pier deploy ```bash pier deploy [] [flags] ``` Build and roll changed apps and sites (implies apply). | Argument | Required | Description | | -------- | -------- | ------------------------------------------------------------------------------ | | `` | no | Deploy one app or site only (name or name/target); default: everything changed | | Flag | Value | Default | Description | | ------------------ | ------------------ | -------- | ------------------------------------------------------------------------------------------------------------------- | | `-y`, `--yes` | | | Skip confirmation prompt | | `-f`, `--force` | | | Force rebuild all apps | | `--tag` | | `latest` | Image tag | | `--no-resume` | | | Refuse to resume suspended targets — fail fast (CI escape hatch) | | `--prune-external` | | | Also delete resources on the server that aren't in pier.yaml and were never applied from it (added via console/API) | | `--purge` | | | Deletes in this deploy skip the 30-day recovery window (torn down immediately) | | `--rename` | `KIND.OLD=NEW,...` | | Apply a rename in place instead of delete+create (KIND.OLD=NEW, e.g. apps.api=gateway). Repeatable. | | `--path` | `STRING` | | Site only: directory to build and upload (default: the site's build context) | | `--build-cmd` | `STRING` | | Site only: override the build command (build-time only) | | `--output-dir` | `STRING` | | Site only: override the output directory (build-time only) | | `--skip-build` | | | Site only: skip install and build, upload the directory as is | ### pier add ```bash pier add ``` Add a resource. #### pier add app ```bash pier add app [flags] ``` Add an app. | Flag | Value | Default | Description | | -------------- | ------------- | ------- | ------------------------------------------------------------------------------------------------------------- | | `--name` | `STRING` | | App name | | `--plan` | `STRING` | | App plan (e.g. app-s, app-m) | | `--replicas` | `0` | `0` | Number of replicas | | `--autoscale` | `STRING` | | Autoscale range min-max (e.g. 1-4); XOR with --replicas | | `--trigger` | `TRIGGER,...` | | Autoscale trigger type:value (cpu:70, memory:80, rps:50, latency:250ms); repeatable | | `--idle-after` | `STRING` | | Zero-traffic window before scale-to-zero (with --autoscale 0-N) | | `--image` | `STRING` | | Container image (static-image flow, skips build) | | `--port` | `INT` | | Container port (required with --image) | | `--template` | `STRING` | | Scaffold from a starter template (e.g. node\_hono, python\_fastapi, go\_fiber, rust\_axum, dockerfile\_caddy) | | `-y`, `--yes` | | | Skip confirmation prompt | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier add site ```bash pier add site [flags] ``` Add a static site. | Flag | Value | Default | Description | | ------------- | -------- | ------- | ----------------------------------------------------------------------------------------------------- | | `--name` | `STRING` | | Site name | | `--template` | `STRING` | | Scaffold from a starter template (e.g. site\_nextjs, site\_astro, site\_vite, site\_hugo, site\_html) | | `-y`, `--yes` | | | Skip confirmation prompt | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier add pg ```bash pier add pg [flags] ``` Add a Postgres instance. | Flag | Value | Default | Description | | -------------- | -------- | ------- | ------------------------------------------------------------------- | | `--name` | `STRING` | | Postgres cluster name (CNPG cluster / Pier resource name) | | `--default-db` | `STRING` | | Default Postgres database name created with the cluster (required) | | `--plan` | `STRING` | | Sizing plan (e.g. pg-s, pg-m, pg-l) | | `--replicas` | `0` | `0` | Number of replicas | | `--pg-version` | `STRING` | | Postgres major version | | `-y`, `--yes` | | | Skip confirmation prompt | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier add bucket ```bash pier add bucket [flags] ``` Add a bucket. | Flag | Value | Default | Description | | ------------- | -------- | ------- | ------------------------------------------------------------------- | | `--name` | `STRING` | | Bucket name | | `--access` | `""` | | Access level: public or private | | `-y`, `--yes` | | | Skip confirmation prompt | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier add volume ```bash pier add volume [flags] ``` Add a persistent volume. | Flag | Value | Default | Description | | -------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------- | | `--name` | `STRING` | | Volume name | | `--size` | `""` | | Size (e.g. 1GB, 5GB) | | `--durability` | `""` | | Durability tier: standard (node-local, default) or ha (replicated, survives node failure). Immutable after creation. | | `-a`, `--app` | `STRING` | | Attach to an app (slug or slug/target) | | `--mount` | `STRING` | | Mount path inside the app (required with --app non-interactively) | | `-y`, `--yes` | | | Skip confirmation | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier add domain ```bash pier add domain [] [flags] ``` Add a custom domain. | Argument | Required | Description | | ---------- | -------- | ------------------------------------ | | `` | no | Domain to add (e.g. app.example.com) | | Flag | Value | Default | Description | | -------------- | -------- | ------- | ------------------------------------------------------------------- | | `-a`, `--app` | `STRING` | | App ref (slug or slug/target) | | `-s`, `--site` | `STRING` | | Site ref (slug or slug/target) | | `-y`, `--yes` | | | Skip confirmation | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier add target ```bash pier add target [flags] ``` Add a deployment target to an app or site. | Argument | Required | Description | | -------- | -------- | ------------------------------------------ | | `` | yes | App or site (name) | | `` | yes | New target name (slug-shaped, e.g. canary) | | Flag | Value | Default | Description | | -------------- | -------- | ------- | ---------------------------------------------------- | | `--branch` | `STRING` | | Git branch that deploys this target | | `--plan` | `STRING` | | Sizing plan (e.g. app-s, app-m) | | `--dockerfile` | `STRING` | | Dockerfile path override (relative to build context) | | `-y`, `--yes` | | | Skip confirmation prompt | ### pier set ```bash pier set ``` Change a resource's config. #### pier set app ```bash pier set app [] [flags] ``` Change an app's config. | Argument | Required | Description | | -------- | -------- | ----------------------------- | | `` | no | App ref (slug or slug/target) | | Flag | Value | Default | Description | | ----------------- | ------------- | ------- | ----------------------------------------------------------------------------------- | | `--plan` | `STRING` | | New plan | | `--replicas` | `INT` | | New replica count (fixed scaling; XOR with --autoscale) | | `--autoscale` | `STRING` | | Autoscale range min-max (e.g. 1-4), or 'off' to return to fixed | | `--trigger` | `TRIGGER,...` | | Autoscale trigger type:value (cpu:70, memory:80, rps:50, latency:250ms); repeatable | | `--idle-after` | `STRING` | | Zero-traffic window before scale-to-zero (with --autoscale 0-N) | | `--image` | `STRING` | | Deploy from a static image (switches off build\_context) | | `--port` | `INT` | | Container port (image-sourced apps only) | | `--build-context` | `STRING` | | Deploy by building a code path, relative to pier.yaml (switches off image) | | `-y`, `--yes` | | | Skip confirmation prompt | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier set site ```bash pier set site [] [flags] ``` Change a site's config. | Argument | Required | Description | | -------- | -------- | ------------------------------ | | `` | no | Site ref (slug or slug/target) | | Flag | Value | Default | Description | | ----------------- | -------- | ------- | ------------------------------------------------------------------- | | `--framework` | `STRING` | | New framework (e.g. static, nextjs-static, astro, vite, hugo) | | `--build-command` | `STRING` | | New build command | | `--output-dir` | `STRING` | | New output directory | | `-y`, `--yes` | | | Skip confirmation prompt | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier set pg ```bash pier set pg [] [flags] ``` Change a Postgres instance's config. | Argument | Required | Description | | ------------ | -------- | --------------------- | | `` | no | Postgres name or slug | | Flag | Value | Default | Description | | -------------- | -------- | ------- | ------------------------------------------------------------------- | | `--plan` | `STRING` | | New plan | | `--replicas` | `INT` | | New replica count | | `--pg-version` | `STRING` | | New Postgres major version (e.g. 17) | | `-y`, `--yes` | | | Skip confirmation prompt | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier set bucket ```bash pier set bucket [] [flags] ``` Change a bucket's config. | Argument | Required | Description | | ---------- | -------- | ------------------- | | `` | no | Bucket name or slug | | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------------------------------------------------- | | `--access` | `""` | | Access level: public or private | | `-y`, `--yes` | | | Skip confirmation prompt | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier set volume ```bash pier set volume [] [flags] ``` Change a volume's config. | Argument | Required | Description | | ---------- | -------- | ------------------------ | | `` | no | Volume name, slug, or ID | | Flag | Value | Default | Description | | ------------- | -------- | ------- | ------------------------------------------------------------------- | | `--size` | `""` | | New size (e.g. 5GB, 10GB) | | `-a`, `--app` | `STRING` | | Bind to an app (slug or slug/target), moving any existing binding | | `--mount` | `STRING` | | Mount path inside the app (required with --app non-interactively) | | `--detach` | | | Remove the volume's app binding | | `-y`, `--yes` | | | Skip confirmation | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | ### pier rm ```bash pier rm ``` Remove a resource. #### pier rm app ```bash pier rm app [] [flags] ``` Remove an app. | Argument | Required | Description | | -------- | -------- | --------------------- | | `` | no | App name, slug, or ID | | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------------------------------------------------- | | `-y`, `--yes` | | | Skip confirmation prompt | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier rm site ```bash pier rm site [] [flags] ``` Remove a site. | Argument | Required | Description | | -------- | -------- | ----------------- | | `` | no | Site name or slug | | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------------------------------------------------- | | `-y`, `--yes` | | | Skip confirmation prompt | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier rm pg ```bash pier rm pg [] [flags] ``` Remove a Postgres instance. | Argument | Required | Description | | ------------ | -------- | --------------------- | | `` | no | Postgres name or slug | | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------------------------------------------------- | | `-y`, `--yes` | | | Skip confirmation prompt | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier rm bucket ```bash pier rm bucket [] [flags] ``` Remove a bucket. | Argument | Required | Description | | ---------- | -------- | ------------------- | | `` | no | Bucket name or slug | | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------------------------------------------------- | | `-y`, `--yes` | | | Skip confirmation prompt | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier rm volume ```bash pier rm volume [] [flags] ``` Remove a volume. | Argument | Required | Description | | ---------- | -------- | ------------------------ | | `` | no | Volume name, slug, or ID | | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------------------------------------------------- | | `-y`, `--yes` | | | Skip confirmation | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier rm domain ```bash pier rm domain [] [flags] ``` Remove a custom domain. | Argument | Required | Description | | ---------- | -------- | ----------------------------------------- | | `` | no | Domain to delete (interactive if omitted) | | Flag | Value | Default | Description | | -------------- | -------- | ------- | ------------------------------------------------------------------- | | `-a`, `--app` | `STRING` | | App ref narrowing the --stage selection (slug or slug/target) | | `-s`, `--site` | `STRING` | | Site ref narrowing the --stage selection (slug or slug/target) | | `-y`, `--yes` | | | Skip confirmation | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier rm target ```bash pier rm target [flags] ``` Remove a deployment target from an app or site. | Argument | Required | Description | | -------- | -------- | ----------------------------------------------------------------- | | `` | yes | Target to remove (name/target of an app or site, e.g. web/feat-x) | | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------ | | `-y`, `--yes` | | | Skip confirmation prompt | ### pier trash ```bash pier trash ``` Removed resources in their recovery window: list, restore, purge. #### pier trash ls ```bash pier trash ls ``` List removed resources still in their recovery window. #### pier trash restore ```bash pier trash restore ``` Restore a removed resource (its data comes back). | Argument | Required | Description | | -------- | -------- | ---------------------------------------------------- | | `` | yes | Resource type: app \| pg \| site \| bucket \| volume | | `` | yes | Resource name (slug) | #### pier trash purge ```bash pier trash purge [flags] ``` Purge a removed resource now (forfeits recovery). | Argument | Required | Description | | -------- | -------- | ---------------------------------------------------- | | `` | yes | Resource type: app \| pg \| site \| bucket \| volume | | `` | yes | Resource name (slug) | | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------ | | `-y`, `--yes` | | | Skip confirmation prompt | ### pier copy ```bash pier copy ``` Copy a resource to another environment. #### pier copy app ```bash pier copy app [] [flags] ``` Copy an app to another environment. | Argument | Required | Description | | -------- | -------- | ------------------------ | | `` | no | App name or slug to copy | | Flag | Value | Default | Description | | ------ | -------- | ------- | ----------------------- | | `--to` | `STRING` | | Target environment slug | #### pier copy site ```bash pier copy site [] [flags] ``` Copy a site to another environment. | Argument | Required | Description | | -------- | -------- | ------------------------- | | `` | no | Site name or slug to copy | | Flag | Value | Default | Description | | ------ | -------- | ------- | ----------------------- | | `--to` | `STRING` | | Target environment slug | ### pier rename ```bash pier rename [flags] ``` Rename a resource in place (non-destructive). | Argument | Required | Description | | -------- | -------- | ------------------------------------------------------------------------- | | `` | yes | Resource kind: app \| postgres \| site \| bucket \| volume \| environment | | `` | yes | Current name | | `` | yes | New name | | Flag | Value | Default | Description | | ------------- | ----- | ------- | ----------------- | | `-y`, `--yes` | | | Skip confirmation | ### pier promote ```bash pier promote [flags] ``` Make a target the primary of its app or site. | Argument | Required | Description | | -------- | -------- | ------------------------------------------------------ | | `` | yes | Target to make primary (name/target of an app or site) | | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------ | | `-y`, `--yes` | | | Skip confirmation prompt | ### pier restart ```bash pier restart [] [flags] ``` Restart an app or a Postgres instance. | Argument | Required | Description | | -------- | -------- | -------------------------------------------------------------- | | `` | no | App (name or name/target) or Postgres to restart; omit to pick | | Flag | Value | Default | Description | | ------------- | -------- | ------- | ------------------------------------------------------ | | `--type` | `STRING` | | Disambiguate a name shared by several kinds: app or pg | | `-y`, `--yes` | | | Skip the resume confirmation prompt | | `--no-resume` | | | Fail instead of resuming a paused resource/ancestor | ### pier rollback ```bash pier rollback [] [flags] ``` Roll an app or site back to a previous deploy. | Argument | Required | Description | | -------- | -------- | ------------------------------------------------------------ | | `` | no | App or site to roll back (name or name/target); omit to pick | | Flag | Value | Default | Description | | ------------- | -------- | ------- | -------------------------------------------------------------------------------- | | `--type` | `STRING` | | Disambiguate a name shared by several kinds: app or site | | `--to` | `STRING` | | Deploy to roll back to (an id from 'pier deploys ls'); default: the previous one | | `-y`, `--yes` | | | Skip confirmation prompt | | `--no-resume` | | | Fail instead of resuming a paused app/ancestor | ### pier pause ```bash pier pause [] [flags] ``` Pause a resource, environment, project or workspace (recoverable). | Argument | Required | Description | | -------- | -------- | ---------------------------------------- | | `` | no | Resource to pause (name, or name/target) | | Flag | Value | Default | Description | | ------------- | -------- | ------- | ---------------------------------------------------------------------------- | | `--type` | `STRING` | | Disambiguate a name shared by several kinds: app, site, pg, bucket or volume | | `-y`, `--yes` | | | Skip confirmation | | `--no-wait` | | | Return immediately after submitting; don't wait for terminal status | ### pier resume ```bash pier resume [] [flags] ``` Resume a paused resource, environment, project or workspace. | Argument | Required | Description | | -------- | -------- | ----------------------------------------- | | `` | no | Resource to resume (name, or name/target) | | Flag | Value | Default | Description | | ------------- | -------- | ------- | ---------------------------------------------------------------------------- | | `--type` | `STRING` | | Disambiguate a name shared by several kinds: app, site, pg, bucket or volume | | `--no-wait` | | | Return immediately after submitting; don't wait for terminal status | | `-y`, `--yes` | | | Accepted for symmetry with pause (resume never prompts) | ## Connect & data ### pier ssh ```bash pier ssh [] [] [flags] ``` Open a shell in a running app. | Argument | Required | Description | | ----------- | -------- | --------------------------------------------------------------------------------- | | `` | no | App ref (slug, slug/target, or slug/target/instance; uses current app if omitted) | | `` | no | Command to run (default: /bin/sh) | | Flag | Value | Default | Description | | ------- | ----- | ------------------- | ----------------------- | | `--key` | | `~/.ssh/id_ed25519` | Path to SSH private key | ### pier psql ```bash pier psql [] [] [flags] ``` Open a psql shell to a Postgres instance. | Argument | Required | Description | | ------------ | -------- | ---------------------------------- | | `` | no | Postgres name, slug, or ID | | `` | no | Extra args passed to psql after -- | | Flag | Value | Default | Description | | ------ | -------- | ------- | ------------------------------------------------- | | `--db` | `STRING` | | Override the Postgres database inside the cluster | ### pier vars ```bash pier vars ``` Environment variables. #### pier vars ls ```bash pier vars ls ``` List environment variables. #### pier vars set ```bash pier vars set [] [] [flags] ``` Set a variable (plain, secret or linked); KEY=VALUE or KEY VALUE. | Argument | Required | Description | | --------- | -------- | ---------------------------- | | `` | no | Variable name (or KEY=VALUE) | | `` | no | Variable value | | Flag | Value | Default | Description | | ---------------- | -------- | ------- | ------------------------------------------------------------------- | | `-s`, `--secret` | | | Store as secret | | `--secret-value` | `STRING` | | Secret value (use '-' for stdin) | | `--from` | `STRING` | | Link to resource reference (e.g. postgres.main.url) | | `--app` | `STRING` | | Scope to an app (slug or slug/target) | | `--site` | `STRING` | | Scope to a site (slug or slug/target) | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier vars rm ```bash pier vars rm [] [flags] ``` Remove a variable. | Argument | Required | Description | | -------- | -------- | ----------------------- | | `` | no | Variable name to remove | | Flag | Value | Default | Description | | ------------- | -------- | ------- | ------------------------------------------------------------------- | | `--app` | `STRING` | | Scope to an app (slug or slug/target) | | `--site` | `STRING` | | Scope to a site (slug or slug/target) | | `-y`, `--yes` | | | Skip confirmation prompt | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | #### pier vars import ```bash pier vars import [flags] ``` Import variables from a .env file. | Flag | Value | Default | Description | | ------------- | -------- | ------- | ------------------------------------- | | `--file` | `STRING` | | Path to .env file (use '-' for stdin) | | `--secret` | | | Treat all imported vars as secrets | | `-y`, `--yes` | | | Skip confirmation prompt | #### pier vars reveal ```bash pier vars reveal [] ``` Reveal the value of a secret variable. | Argument | Required | Description | | -------- | -------- | ----------------------- | | `` | no | Variable name to reveal | ### pier routes ```bash pier routes ``` Site routing rules. #### pier routes ls ```bash pier routes ls [] ``` List a site's routing rules. | Argument | Required | Description | | -------- | -------- | ------------------------------ | | `` | no | Site ref (name or name/target) | #### pier routes add ```bash pier routes add [] [] [flags] ``` Add a routing rule (redirect, rewrite, header). | Argument | Required | Description | | -------------- | -------- | ---------------------------------------- | | `` | no | Site (name or name/target); omit to pick | | `` | no | Route type (redirect, rewrite, header) | | Flag | Value | Default | Description | | --------------- | ------------- | ------- | ------------------------------------------------------------------- | | `-y`, `--yes` | | | Skip confirmation prompt | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | | `--source` | `STRING` | | Source path pattern | | `--destination` | `STRING` | | Destination path or URL | | `--status` | `308` | `308` | Redirect status code (301/302/307/308) | | `--path` | `STRING` | | Header rule path pattern | | `--headers` | `HEADERS,...` | | Header key=value pairs | #### pier routes rm ```bash pier routes rm [] [] [flags] ``` Remove a routing rule. | Argument | Required | Description | | -------------- | -------- | ---------------------------------------- | | `` | no | Site (name or name/target); omit to pick | | `` | no | Route type (redirect, rewrite, header) | | Flag | Value | Default | Description | | ------------- | -------- | ------- | ------------------------------------------------------------------- | | `-y`, `--yes` | | | Skip confirmation prompt | | `--stage` | | | Write the change to pier.yaml only — apply later with 'pier deploy' | | `--source` | `STRING` | | Source/path pattern to remove | | `--path` | `STRING` | | Header rule path to remove | #### pier routes fallback ```bash pier routes fallback [] [flags] ``` Configure the SPA fallback. | Argument | Required | Description | | -------- | -------- | ---------------------------------------- | | `` | no | Site (name or name/target); omit to pick | | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------ | | `-y`, `--yes` | | | Skip confirmation prompt | ### pier pg ```bash pier pg ``` Postgres tools. #### pier pg credentials ```bash pier pg credentials [] [flags] ``` Show connection credentials. | Argument | Required | Description | | ------------ | -------- | -------------------------- | | `` | no | Postgres name, slug, or ID | | Flag | Value | Default | Description | | ------- | ----- | ------- | ------------------------------------ | | `--uri` | | | Print connection URI only (pipeable) | #### pier pg plans ```bash pier pg plans ``` List available Postgres plans. #### pier pg databases ```bash pier pg databases [] ``` List logical databases inside an instance. | Argument | Required | Description | | ------------ | -------- | --------------------------------------- | | `` | no | Postgres instance (name or name/target) | #### pier pg tables ```bash pier pg tables [] [] [flags] ``` List tables in a logical database. | Argument | Required | Description | | ------------ | -------- | --------------------------------------------------------------------- | | `` | no | Postgres instance (name or name/target) | | `` | no | Logical database inside the cluster (default: the instance's default) | | Flag | Value | Default | Description | | ---------- | -------- | ------- | -------------------------------------------------- | | `--schema` | `STRING` | | Filter by schema (default: all non-system schemas) | | `--limit` | `100` | `100` | Limit number of rows returned | | `--csv` | | | Output as CSV (no formatting) | #### pier pg query ```bash pier pg query [] [] [] [flags] ``` Run a one-off SQL query. | Argument | Required | Description | | ------------ | -------- | --------------------------------------------------------------------- | | `` | no | Postgres instance (name or name/target) | | `` | no | Logical database inside the cluster (default: the instance's default) | | `` | no | SQL to execute (use --file to read from a file or stdin) | | Flag | Value | Default | Description | | --------- | -------- | ------- | -------------------------------------- | | `--file` | `STRING` | | Read SQL from a file (use - for stdin) | | `--limit` | `INT` | | Max rows returned before truncation | | `--csv` | | | Output as CSV | ### pier objects ```bash pier objects ``` Bucket objects (data plane). #### pier objects put ```bash pier objects put [flags] ``` Upload a file to a bucket. | Flag | Value | Default | Description | | ---------------- | -------- | ------- | ---------------------------------------- | | `-b`, `--bucket` | `STRING` | | Bucket name, slug, or ID | | `-f`, `--file` | `STRING` | | Local file path to upload | | `--key` | `STRING` | | Remote object key (defaults to filename) | #### pier objects get ```bash pier objects get [] [flags] ``` Download an object from a bucket. | Argument | Required | Description | | -------- | -------- | ----------- | | `` | no | Object key | | Flag | Value | Default | Description | | ---------------- | -------- | ------- | ------------------------------------------- | | `-b`, `--bucket` | `STRING` | | Bucket name, slug, or ID | | `-o`, `--output` | `STRING` | | Local file path (defaults to key basename) | | `--prefix` | `STRING` | | Filter the interactive picker by key prefix | #### pier objects ls ```bash pier objects ls [flags] ``` List objects in a bucket. | Flag | Value | Default | Description | | ---------------- | -------- | ------- | ---------------------------- | | `-b`, `--bucket` | `STRING` | | Bucket name, slug, or ID | | `--prefix` | `STRING` | | Filter objects by key prefix | | `--max-keys` | `100` | `100` | Max objects to return | #### pier objects rm ```bash pier objects rm [] [flags] ``` Remove an object from a bucket. | Argument | Required | Description | | -------- | -------- | ----------- | | `` | no | Object key | | Flag | Value | Default | Description | | ---------------- | -------- | ------- | ------------------------------------------- | | `-b`, `--bucket` | `STRING` | | Bucket name, slug, or ID | | `-y`, `--yes` | | | Skip confirmation prompt | | `--prefix` | `STRING` | | Filter the interactive picker by key prefix | #### pier objects presign ```bash pier objects presign [] [flags] ``` Generate a presigned URL for an object. | Argument | Required | Description | | -------- | -------- | ----------- | | `` | no | Object key | | Flag | Value | Default | Description | | ---------------- | -------- | ------- | ----------------------------------------------------------------- | | `-b`, `--bucket` | `STRING` | | Bucket name, slug, or ID | | `--method` | `STRING` | | HTTP method: GET or PUT (defaults to GET in non-interactive mode) | | `--prefix` | `STRING` | | Filter the interactive picker by key prefix (GET only) | ### pier snapshots ```bash pier snapshots ``` Volume snapshots. #### pier snapshots ls ```bash pier snapshots ls [] ``` List snapshots. | Argument | Required | Description | | ---------- | -------- | ------------------------ | | `` | no | Volume name, slug, or ID | #### pier snapshots create ```bash pier snapshots create [] ``` Create an on-demand snapshot. | Argument | Required | Description | | ---------- | -------- | ------------------------ | | `` | no | Volume name, slug, or ID | ### pier backups ```bash pier backups ``` Postgres backups. #### pier backups ls ```bash pier backups ls [] ``` List backups. | Argument | Required | Description | | ------------ | -------- | -------------------------- | | `` | no | Postgres name, slug, or ID | #### pier backups create ```bash pier backups create [] ``` Trigger an on-demand backup. | Argument | Required | Description | | ------------ | -------- | -------------------------- | | `` | no | Postgres name, slug, or ID | ### pier github ```bash pier github ``` GitHub push-to-deploy. #### pier github connect ```bash pier github connect [flags] ``` Connect this project to a GitHub repository. | Flag | Value | Default | Description | | ------------- | -------- | ------- | ------------------------------ | | `--repo` | `STRING` | | GitHub repository (owner/repo) | | `-y`, `--yes` | | | Skip confirmation prompt | #### pier github set ```bash pier github set [flags] ``` Configure deploy triggers for push-to-deploy. | Flag | Value | Default | Description | | ---------- | -------- | ------- | -------------------------------------------------------------------------- | | `--app` | `STRING` | | App slug to set the trigger on (flag mode — skips the interactive prompt) | | `--site` | `STRING` | | Site slug to set the trigger on (flag mode — skips the interactive prompt) | | `--target` | `STRING` | | Target name (default: the resource's only target) | | `--branch` | `STRING` | | Branch or pattern to deploy on push (e.g. main, release-\*) | | `--remove` | | | Remove the trigger instead of setting one | #### pier github disconnect ```bash pier github disconnect [flags] ``` Disconnect GitHub from this project. | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------ | | `-y`, `--yes` | | | Skip confirmation prompt | #### pier github status ```bash pier github status ``` Show GitHub connection status. ### pier dev ```bash pier dev ``` Run the current environment locally (docker). #### pier dev up ```bash pier dev up [flags] ``` Run the current environment locally (default). | Flag | Value | Default | Description | | ------------------- | --------- | ------- | ----------------------------------------------------------------------------- | | `--dry-run` | | | Print the materialization plan and generated compose file; run nothing | | `--watch` | | | Watch build contexts and rebuild/restart apps on change | | `--only` | `APP,...` | | Run only these apps | | `--pull-secrets` | | | Reveal secret values from the server (required for protected environments) | | `--no-pull-secrets` | | | Never reveal secrets; missing ones error unless --allow-missing | | `--allow-missing` | | | Run even when required secrets have no value (vars are absent) | | `--build` | | | Rebuild app images even when the build context is unchanged | | `--no-build` | | | Never build; fail if an app image is missing | | `--keep-others` | | | Leave other environments' running dev stacks alone (default: their apps stop) | #### pier dev status ```bash pier dev status ``` Show this project's local dev stacks across environments. #### pier dev stop ```bash pier dev stop ``` Stop the current environment's local stack (data kept). #### pier dev reset ```bash pier dev reset [flags] ``` Destroy local dev stack(s): containers, volumes, generated files. | Flag | Value | Default | Description | | ------------- | ----- | ------- | ---------------------------------------------------- | | `--all` | | | Reset every environment's dev stack for this project | | `-y`, `--yes` | | | Skip confirmation prompt | #### pier dev logs ```bash pier dev logs [] ``` Follow the local stack's logs. | Argument | Required | Description | | -------- | -------- | ---------------- | | `` | no | Limit to one app | ## Project & scope ### pier config ```bash pier config ``` pier.yaml lifecycle: init, sync, diff, validate. #### pier config init ```bash pier config init [flags] ``` Create a new project and write its pier.yaml. | Flag | Value | Default | Description | | ---------------- | -------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `-o`, `--output` | | `pier.yaml` | Output file path | | `--name` | `STRING` | | Project name for the new project (default: directory name). Required non-interactively — creating a server project should never be a silent side effect in CI. | #### pier config validate ```bash pier config validate [] ``` Validate pier.yaml syntax and references. | Argument | Required | Description | | -------- | -------- | ---------------------------------------- | | `` | no | Path to pier.yaml (default: auto-detect) | #### pier config diff ```bash pier config diff [] ``` Show differences between pier.yaml and platform state. | Argument | Required | Description | | -------- | -------- | ---------------------------------------- | | `` | no | Path to pier.yaml (default: auto-detect) | #### pier config sync ```bash pier config sync [] [flags] ``` Pull server state into pier.yaml (adopt an existing project, or update an existing file). | Argument | Required | Description | | -------- | -------- | ---------------------------------------- | | `` | no | Path to pier.yaml (default: auto-detect) | | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------ | | `-y`, `--yes` | | | Skip confirmation prompt | ### pier use ```bash pier use [] ``` Switch the active environment. | Argument | Required | Description | | --------------- | -------- | ------------------------------------------- | | `` | no | Environment slug to switch to; omit to pick | ### pier projects ```bash pier projects ``` Projects: list, add, inspect, remove, pause, switch. #### pier projects ls ```bash pier projects ls ``` List projects. #### pier projects add ```bash pier projects add [flags] ``` Add a project. | Argument | Required | Description | | -------- | -------- | ------------ | | `` | yes | Project name | | Flag | Value | Default | Description | | -------- | -------- | ------- | ----------------------------------------------- | | `--slug` | `STRING` | | URL-safe identifier (auto-generated if omitted) | #### pier projects info ```bash pier projects info ``` Show project details. | Argument | Required | Description | | ----------- | -------- | ------------------------- | | `` | yes | Project name, slug, or ID | #### pier projects use ```bash pier projects use [] ``` Switch the active project (picker when no name is given). | Argument | Required | Description | | -------- | -------- | --------------------------------------- | | `` | no | Project name, slug, or ID; omit to pick | #### pier projects rm ```bash pier projects rm [] [flags] ``` Remove a project. | Argument | Required | Description | | ----------- | -------- | ------------------------- | | `` | no | Project name, slug, or ID | | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------ | | `-y`, `--yes` | | | Skip confirmation prompt | #### pier projects pause ```bash pier projects pause [flags] ``` Pause an entire project (recoverable). | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------------------------------------------------- | | `-y`, `--yes` | | | Skip confirmation | | `--no-wait` | | | Return immediately after submitting; don't wait for terminal status | #### pier projects resume ```bash pier projects resume [flags] ``` Resume a paused project. | Flag | Value | Default | Description | | ----------- | ----- | ------- | ------------------------------------------------------------------- | | `--no-wait` | | | Return immediately after submitting; don't wait for terminal status | ### pier environments ```bash pier environments ``` Environments: list, add, pause (switch with 'pier use'). #### pier environments ls ```bash pier environments ls ``` List environments. #### pier environments add ```bash pier environments add [flags] ``` Add an environment. | Argument | Required | Description | | -------- | -------- | ------------------------------- | | `` | yes | Environment name (e.g. Staging) | | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------ | | `-y`, `--yes` | | | Skip confirmation prompt | #### pier environments pause ```bash pier environments pause [flags] ``` Pause an environment (recoverable). | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------------------------------------------------- | | `-y`, `--yes` | | | Skip confirmation | | `--no-wait` | | | Return immediately after submitting; don't wait for terminal status | #### pier environments resume ```bash pier environments resume [flags] ``` Resume a paused environment. | Flag | Value | Default | Description | | ----------- | ----- | ------- | ------------------------------------------------------------------- | | `--no-wait` | | | Return immediately after submitting; don't wait for terminal status | ### pier workspaces ```bash pier workspaces ``` Workspaces: switch, pause, resume. #### pier workspaces ls ```bash pier workspaces ls ``` List your workspaces. #### pier workspaces use ```bash pier workspaces use [] ``` Switch the active workspace. | Argument | Required | Description | | ------------- | -------- | ---------------------------------- | | `` | no | Workspace name or ID; omit to pick | #### pier workspaces pause ```bash pier workspaces pause [flags] ``` Pause an entire workspace (closes the active plan). | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------------------------------------------------- | | `-y`, `--yes` | | | Skip confirmation | | `--no-wait` | | | Return immediately after submitting; don't wait for terminal status | #### pier workspaces resume ```bash pier workspaces resume [flags] ``` Resume a paused workspace. | Flag | Value | Default | Description | | ----------- | ----- | ------- | ------------------------------------------------------------------- | | `--no-wait` | | | Return immediately after submitting; don't wait for terminal status | ## CLI & account ### pier login ```bash pier login [] [flags] ``` Authenticate with the controller. | Argument | Required | Description | | -------- | -------- | ------------------------------------------------- | | `` | no | Controller URL (default: built-in or from config) | | Flag | Value | Default | Description | | -------------- | ----- | ------- | -------------------------------------------------- | | `--no-browser` | | | Use email/password prompt instead of browser login | ### pier logout ```bash pier logout ``` Log out and clear session. ### pier whoami ```bash pier whoami ``` Show current user. ### pier profiles ```bash pier profiles ``` Session profiles (one login per controller). #### pier profiles ls ```bash pier profiles ls ``` List stored profiles. #### pier profiles use ```bash pier profiles use [] ``` Switch the default profile. | Argument | Required | Description | | -------- | -------- | -------------------------- | | `` | no | Profile name; omit to pick | #### pier profiles rm ```bash pier profiles rm ``` Remove a stored profile. | Argument | Required | Description | | -------- | -------- | ------------ | | `` | yes | Profile name | ### pier billing ```bash pier billing ``` Billing state and overage cap. #### pier billing overview ```bash pier billing overview ``` Show billing overview (plan, status, credits). #### pier billing charges ```bash pier billing charges ``` Show recent charges. #### pier billing cap ```bash pier billing cap ``` Manage the workspace overage cap. ##### pier billing cap show ```bash pier billing cap show ``` Show the current cap. ##### pier billing cap set ```bash pier billing cap set [] [flags] ``` Set or update the cap. | Argument | Required | Description | | ---------- | -------- | ------------------------------------------------------------ | | `` | no | Cap amount in USD (e.g. 50.00). Prompts when omitted on TTY. | | Flag | Value | Default | Description | | ---------- | ----- | -------------- | -------------------- | | `--action` | | `hard_suspend` | What happens at 100% | ##### pier billing cap remove ```bash pier billing cap remove [flags] ``` Remove the cap (= unlimited). | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------ | | `-y`, `--yes` | | | Skip confirmation prompt | ### pier ssh-key ```bash pier ssh-key [flags] ``` Generate SSH certificate for shell access. | Flag | Value | Default | Description | | ------- | ----- | ----------------------- | ---------------------- | | `--key` | | `~/.ssh/id_ed25519.pub` | Path to SSH public key | ### pier upgrade ```bash pier upgrade ``` Upgrade the CLI to the latest version. ### pier uninstall ```bash pier uninstall [flags] ``` Uninstall the Pier CLI and remove all data. | Flag | Value | Default | Description | | ------------- | ----- | ------- | ------------------------ | | `-y`, `--yes` | | | Skip confirmation prompt |