> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getkato.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Push environment variables

> Merge or replace variables in an existing project environment.

Merge or replace variables in an existing project environment.

Use a developer access key. This endpoint is part of the [CLI API](/api-reference/cli/overview), with its own response format and rate limit.

Required scopes: `env:write`.

The key owner must still be a workspace owner or administrator. Missing scope or admin access returns `403`; an unavailable or differently pinned project returns `404`. The environment must already exist. A push writes a version snapshot and activity. Review `replace` carefully: an empty vars map replaces the environment with no variables.

## Parameters

<ParamField body="recordId" type="string" required>
  Nonempty project record ID, respecting any project pin.
</ParamField>

<ParamField body="env" type="string" required>
  1–40 characters; letters, numbers, hyphens, or underscores, starting with a letter or number. Names are trimmed.
</ParamField>

<ParamField body="vars" type="object" required>
  String map. Keys are 1–128 characters matching /^\[A-Za-z\_]\[A-Za-z0-9\_]\*\$/. Values are strings up to 65,536 characters.
</ParamField>

<ParamField body="mode" type="string">
  merge (default) preserves unspecified keys; replace removes keys not supplied.
</ParamField>

## Response

**200** — Top-level snapshot `version`, `summary` with added/changed/removed key arrays, and human-readable `change`. Change wording is illustrative.

<ResponseExample>
  ```json 200 theme={null}
  {
    "version": 2,
    "summary": {
      "added": [
        "PUBLIC_LABEL"
      ],
      "changed": [],
      "removed": []
    },
    "change": "Added 1 variable"
  }
  ```
</ResponseExample>

<RequestExample>
  ```bash Request theme={null}
  curl --fail-with-body --silent --show-error \
    "https://api.getkato.io/cli/v1/env/push" \
    -H "Authorization: Bearer $KATO_API_KEY" \
    -H "Content-Type: application/json" \
    --data '{
    "recordId": "project_example",
    "env": "development",
    "vars": {
      "PUBLIC_LABEL": "Northlane"
    },
    "mode": "merge"
  }'
  ```
</RequestExample>

This request changes workspace data. A timeout does not prove that the write failed; inspect the result before retrying.


## Related topics

- [CLI API](/api-reference/cli/overview.md)
- [All endpoints](/api-reference/endpoints.md)
- [Kato CLI](/documentation/cli.md)
- [Pull environment variables](/api-reference/cli/pull.md)
- [CLI configuration and CI](/documentation/cli-configuration.md)