Environment variables

Every project has its own set of environment variables. They are encrypted at rest, injected into your app at build time and runtime, and synced with a local dotenv file via the CLI.

Pull and push

apco env pull                 # write the project's vars into .env
apco env push                 # replace the project's vars with .env's contents

Both accept --file <path> (default .env) and --project <slug|id>:

apco env pull --file .env.production
apco env push --file .env.production --project shop

Pulled 3 env var(s) into .env.
Pushed 3 env var(s) to my-app.

env push replaces everything

apco env push replaces the project's entire env var set with the file's contents. A variable missing from the file is deleted from the project. Do an apco env pull first if you're unsure what's currently set.

When changes take effect

Env vars are applied to a deployment when it is built and started:

• Build time — variables are passed to the Railpack build as build secrets, so build steps (e.g. NEXT_PUBLIC_*, API codegen) can read them.
• Runtime — variables are injected into the container's environment.

A running SSR app does not pick up changes live. Redeploy for new values to take effect:

apco env push
apco deploy

Values are never printed

The CLI is deliberately quiet about env var values:

• apco env pull writes values to the file only — stdout (and --json output) contains just the key names.
• apco env push echoes key names, never values.
• The MCP env_list tool returns names only.

Keep it that way on your side too: add .env* to .gitignore, and don't cat pulled files into logs or terminal shares.

{ "ok": true, "operation": "env.pull", "warnings": [],
  "message": "Pulled 3 env var(s) into .env.",
  "file": ".env", "keys": ["API_URL", "DATABASE_URL", "NODE_ENV"] }

Storage and limits

• Values are encrypted at rest on the platform.
• Your plan caps the number of env vars per project (maxEnvVars). Pushing more than the cap fails with QUOTA_EXCEEDED — see Plans & quotas.

DATABASE_URL and managed databases

If your project has a managed database, the platform injects the deployment channel's exact DATABASE_URL into the container automatically — and it wins over a user-defined DATABASE_URL env var. Production, Preview, and Dev never fall back to another channel's managed URL.

Related

• Deploying apps
• Managed databases
• Token scopes — env:read / env:write