Variables, Secrets, and dotenv imports

Every environment command requires a selected workspace and site, plus membership in that workspace.

Choose the right value type

TypeUse it forCan the CLI reveal it?
VariableNon-secret runtime configuration and every literal PUBLIC_* name.Yes, with variable get.
SecretPrivate credentials and server-only sensitive configuration.No. secret get confirms existence and last update time.

Vite inlines literal PUBLIC_* names into the client bundle. Ploy therefore stores them as Variables, never Secrets.

Set and read Variables

Manage a Variable
ploy variable set PUBLIC_API_ORIGIN --env production --body https://api.example.com
ploy variable get PUBLIC_API_ORIGIN --env production

Use --env preview or --env production. Without --body, a set command reads piped stdin or opens an interactive prompt.

Set and inspect Secrets

Manage a Secret
printf '%s' "$API_TOKEN" | ploy secret set API_TOKEN --env production
ploy secret get API_TOKEN --env production

The Secret prompt is masked. Prefer stdin or the prompt so values do not remain in shell history.

Import a dotenv file

Import mixed configuration
ploy env set --env preview --env-file .env.preview

A dotenv import accepts 1–100 unique entries. Names beginning with PUBLIC_ become Variables; all other names become Secrets. The operation updates or inserts parsed names without deleting names that are absent from the file.

The save is atomic: either the accepted dotenv entries are applied together or none are applied.

Preview a change

Preview mutations
ploy --dry-run variable set PUBLIC_API_ORIGIN --env production --body https://api.example.com
ploy --dry-run env set --env preview --env-file .env.preview

--dry-run is supported by set and import mutations. It is not supported by get commands.

Name and value rules

  • Names must match [A-Z][A-Z0-9_]*.
  • Names are at most 128 characters and cannot use platform-reserved names.
  • Values must be non-empty and at most 64 KiB.
  • A dotenv import contains 1–100 unique entries.

Changes take effect on the next publish. Saving configuration does not publish the site or inject values into the current sandbox.

Keep going