env

pfy env manages deployment environments in two places: the Environment records on the Manager (create, update, delete, list) and the short aliases in your project.yaml that deploy commands resolve with --env <alias> (add, remove, link).

Synopsis

pfy env <subcommand> [flags]

Description

There are two things called "environment", and pfy env manages both:

• The server-side Environment entity (dev | qas | run), created per project on the Manager: create, update, delete, list.
• The local alias in project.yaml's environments: map, which binds a friendly name (e.g. prod) to server IDs (tenant_id, application_id, environment_id, cached deployment_id): add, remove, link.

The local alias is what every deploy/render command's --env <name> flag resolves through. pfy sync seeds one alias per tenant automatically.

The verbs split: add/remove edit only the local project.yaml; create/update/delete hit the server. env remove does not delete the server environment and vice versa.

env list

List a project's environments, plus the local aliases.

pfy env list [--project <slug> | --project-id <id>]

Environments:
  - Production (prod) type=run
  - Staging (staging) type=qas
2 environments

Local aliases (project.yaml):
  - prod -> tenant=… application=… environment=…

Project selection: --project-id > --project <slug> > project.yaml's project_id.

env add

Record a local alias, resolving friendly --tenant (and optional --application) slugs to their IDs via the API, so you never paste raw UUIDs into deploy commands.

pfy env add <alias> --tenant <slug> [--application <slug>] [--name <label>] [--project <slug> | --project-id <id>]

Flag	Aliases	Required	Description
--tenant		Yes	Tenant slug (resolved to an ID)
--application	--app	No	Application slug (resolved to an ID, project-level)
--name		No	Human label for the alias
--project		No*	Project slug the slugs are resolved in
--project-id		No*	Project ID (overrides --project)

* One project selector is needed unless project.yaml has a project_id. A tenant or application slug that does not exist fails with nothing was resolved, so the alias was left unchanged.

Fields already recorded for the alias (e.g. environment_id) are preserved; only what was just resolved is overwritten.

Example

pfy env add staging --tenant staging --application web-app --project my-saas

Added alias "staging" -> tenant <id> application <id> (project.yaml)

env remove

Remove a local project.yaml alias. Does not delete the server-side environment (use env delete for that).

pfy env remove <alias>

env create

Create a server-side environment (and optionally record a local alias in the same step).

pfy env create --name <name> --slug <slug> [--type dev|qas|run] [--link <alias> [--app <application-id>]] [--project <slug> | --project-id <id>]

Flag	Required	Description
--name	Yes	Display name
--slug	Yes	Environment slug
--type	No	One of dev, qas, run (default: dev)
--link	No	Also record a project.yaml alias with this name → the new environment
--app	No	Application ID to bind into the local alias (with --link)

Example

pfy env create --project my-saas --name "Production" --slug prod --type run --link prod

Created environment Production (prod) type=run [<id>]
Linked local alias "prod" -> environment <id> in project.yaml

env update

Update a server-side environment. Takes the raw environment ID.

pfy env update --id <environment-id> [--name <name>] [--slug <slug>] [--type dev|qas|run]

At least one of --name, --slug, --type is required. Output: Updated environment <name> (<slug>) type=<type>.

env delete

Delete a server-side environment. Takes the raw environment ID.

pfy env delete --id <environment-id> [--yes]

Flag	Aliases	Description
--id		Environment ID (required)
--yes	-y	Skip the confirmation prompt. Required under --ci or when stdin is not a terminal

On a terminal you type the ID back to confirm, like the other delete commands. Output: Deleted environment <id>.

env link

Record (or converge) a local alias pointing at a server environment, using raw IDs.

pfy env link <alias> --environment-id <id> [--app <application-id>] [--deployment-id <id>] [--name <label>]

Flag	Aliases	Required	Description
--environment-id	--env-id	Yes	Server Environment ID
--app		No	Application ID for this (application, environment)
--deployment-id		No	Cache the resolved Deployment ID for this alias
--name		No	Human label for the alias

The cached deployment_id is the shared deployment's; commands passed --tenant deliberately bypass the cache.

The alias schema

# project.yaml
environments:
  prod:
    tenant_id: "…"        # tenant the alias targets (optional)
    application_id: "…"   # application the deploy/render commands act on
    environment_id: "…"   # server Environment this alias resolves to
    deployment_id: "…"    # cached (application, environment) Deployment
    name: "Production"

See Project Configuration.

See Also

• sync - Seeds one alias per tenant automatically
• nomad - --env <alias> on every render/deploy command
• deployment - --env <alias> for spec access