Zeabur Variables Management

Always use npx zeabur@latest to invoke Zeabur CLI. Never use zeabur directly or any other installation method. If npx is not available, install Node.js first.

Do not guess CLI syntax. Only create, update, delete, env, and list are valid subcommands. Subcommands like set or add do not exist and will silently fail with no error output.

Known Issues

Use --id not --name — name lookup is unreliable
${VAR} gets empty — shell expands before CLI receives; use single quotes
variable env replaces ALL variables — it overwrites the entire variable set with the .env file contents; existing variables not in the file will be removed

Create Variables

Creates new variables. Errors if a key already exists — use update to change existing keys.

# Always use service ID — use the `zeabur-service-list` skill to get it
npx zeabur@latest variable create --id <service-id> \
  -k "KEY1=value1" \
  -k "KEY2=value2" \
  -y -i=false

Update Variables

Updates only the specified keys. Does NOT clear other variables.

npx zeabur@latest variable update --id <service-id> \
  -k "KEY1=new_value1" \
  -k "KEY2=new_value2" \
  -y -i=false

Delete Variables

Deletes only the specified keys.

npx zeabur@latest variable delete --id <service-id> \
  --delete-keys "KEY1" \
  --delete-keys "KEY2" \
  -y -i=false

List Variables

npx zeabur@latest variable list --id <service-id> -i=false

Load from .env File

Warning: This replaces ALL variables on the service with the contents of the .env file. Existing variables not in the file will be removed.

npx zeabur@latest variable env --id <service-id> -f .env

After running env, you must restart the service manually to apply changes.

Variable References

Warning: The CLI -k flag uses Cobra's StringToStringVar parser which cannot reliably handle values containing ${}, even with single quotes. The value may be truncated or emptied. See zeabur/cli#201.

# WRONG — shell expands ${VAR} to empty
npx zeabur@latest variable create --id <service-id> -k "REDIS_URL=${REDIS_URI_INTERNAL}" -y -i=false

# STILL UNRELIABLE — single quotes prevent shell expansion but Cobra's CSV parser may still mangle the value
npx zeabur@latest variable create --id <service-id> -k 'REDIS_URL=${REDIS_URI_INTERNAL}' -y -i=false

# RECOMMENDED — set variable references in Zeabur Dashboard
# Or use GraphQL API with updateEnvironmentVariable(data: Map!) mutation

For cross-service variable references like ${POSTGRESQL.POSTGRES_CONNECTION_STRING}, always use the Zeabur Dashboard or the GraphQL API directly until the CLI bug is fixed.

Quick Reference

Need	Command	Behavior
Add new vars	`npx zeabur@latest variable create --id <service-id> -k "K=V" -y -i=false`	Errors if key exists
Change existing vars	`npx zeabur@latest variable update --id <service-id> -k "K=V" -y -i=false`	Only updates specified keys
Remove specific vars	`npx zeabur@latest variable delete --id <service-id> --delete-keys "K" -y -i=false`	Only removes specified keys
Overwrite all vars from file	`npx zeabur@latest variable env --id <service-id> -f .env`	Replaces entire variable set
View vars	`npx zeabur@latest variable list --id <service-id> -i=false`	Read-only

zeabur-variables