env

coolship env pull [flags]
coolship env diff [flags]
coolship env push [flags]

Coolify keeps two scopes per application: the variables regular deployments see, and a separate copy used by preview deployments. The env commands act on the regular scope unless --preview is given. Values are masked in output unless --show-values is given. Shared references such as {{team.NAME}} are synced as references, never as the values they resolve to. Environment variables explains the rules; the workflow guide shows them in sequence.

Shared flags

env pull

Write the remote variables into the local file, creating it with private permissions. Keys that exist only locally are kept, comments and ordering are preserved, and values Coolify withholds are noted as comments rather than invented.

$ coolship env pull
Wrote 4 regular variable(s) to /home/you/my-app/.env

{
  "target": { "…": "the resolved target" },
  "scope": "regular",
  "file": "/home/you/my-app/.env",
  "written": ["DATABASE_URL", "PORT"],
  "kept": ["LOCAL_ONLY"],
  "withheld": ["API_SECRET"]
}

written, kept, withheld, and warnings are omitted when empty.

env diff

Compare the local file with the remote variables, from the local file's point of view: what push would create, update, or (with --prune) delete.

$ coolship env diff
Comparing /home/you/my-app/.env with regular variables of fenix-bot
+ NEW_KEY=********  (local only; push creates it)
~ PORT: local ********, remote ********
- OLD_KEY=********  (remote only; push --prune deletes it)
? API_SECRET  (remote value withheld; cannot compare)
3 unchanged

When nothing differs, the second line is No differences (3 unchanged) instead.

{
  "target": { "…": "the resolved target" },
  "scope": "regular",
  "file": "/home/you/my-app/.env",
  "added": [{ "key": "NEW_KEY" }],
  "changed": [{ "key": "PORT" }],
  "removed": [{ "key": "OLD_KEY" }],
  "withheld": ["API_SECRET"],
  "unchanged": 3
}

added keys exist only locally, changed keys differ, removed keys exist only remotely, and withheld keys have a remote value Coolify hides; unchanged counts the rest. Values are masked unless --show-values is given: the text output shows ******** (or (empty)) in their place, and the JSON entries carry only key until --show-values adds local and remote. --exit-code makes a clean comparison exit 0 and any difference exit 1, which is useful in CI.

env push

Create and update remote variables from the local file, in one bulk request. Keys that exist only remotely are left in place unless --prune is given. A key whose remote value is withheld is overwritten only with --force. The plan is shown and confirmed first, or requires --yes when noninteractive. Changes take effect on the next deployment.

{
  "plan": {
    "target": { "…": "the resolved target" },
    "scope": "regular",
    "file": "/home/you/my-app/.env",
    "create": [{ "key": "NEW_KEY", "local": "value" }],
    "update": [{ "key": "PORT", "local": "3000", "remote": "8080" }],
    "delete": [{ "key": "OLD_KEY", "remote": "value" }],
    "skipped": ["API_SECRET"]
  }
}

skipped lists withheld keys that were not forced. push has no --show-values; its JSON carries the values it pushed and deleted as they are, so treat that output as you would the file itself. push preserves each variable's literal, multiline, and shown-once flags, which the server would otherwise reset. Coolify creates a preview-scope twin of every regular variable push creates.

Examples

coolship env pull                 # remote → .env, keeping local-only keys and comments
coolship env diff                 # what push would change, values masked
coolship env diff --show-values
coolship env diff --exit-code     # CI check: 1 when .env drifted from Coolify
coolship env push                 # create and update; asks first
coolship env push --prune --yes   # also delete remote-only keys, without asking
coolship env pull --preview --file .env.preview

Exit codes

0 on success (for diff --exit-code, when there are no differences); 1 when the request fails, or for diff --exit-code when there are differences; 2 when the directory is not linked, the file cannot be parsed, or push needs --yes noninteractively; 130 when the confirmation is cancelled.