convex env

Set and view environment variables on your deployment

The convex env command allows you to manage environment variables on your Convex deployment. Environment variables are accessible in your Convex functions via process.env.

Subcommands

• convex env set - Set environment variables
• convex env get - Print a variable’s value
• convex env list - List all environment variables
• convex env remove - Unset an environment variable

Set command

Set environment variables on your deployment.

Usage

npx convex env set <name> [value] [options]
npx convex env set --from-file <file> [options]

Arguments

name · string

Name of the environment variable to set.

Optional when using --from-file.

value · string

Value to set. If omitted, you’ll be prompted to enter it interactively.

Options

--from-file · string

Read environment variables from a .env file.

Without --force, fails if any existing variable has a different value.

--force · boolean

When setting multiple variables, overwrite existing environment variable values instead of failing on mismatch.

Examples

Set a single variable

Set a variable with a value:

npx convex env set API_KEY "sk_live_abc123"

Set interactively

Set a variable and be prompted for the value:

npx convex env set API_SECRET
# You'll be prompted to enter the value

Set from file

Set multiple variables from a .env file:

npx convex env set --from-file .env.production

Force overwrite

Overwrite existing values when importing from file:

npx convex env set --from-file .env.production --force

Set from stdin

Read value from stdin:

echo "secret_value" | npx convex env set API_KEY

Set on production

Set a variable on your production deployment:

npx convex env set API_KEY "sk_live_abc123" --prod

Get command

Print an environment variable’s value.

Usage

npx convex env get <name>

Arguments

name · string · required

Name of the environment variable to retrieve.

Examples

npx convex env get API_KEY

List command

List all environment variables on your deployment.

Usage

npx convex env list

Examples

List all environment variables:

npx convex env list

List variables on production:

npx convex env list --prod

Remove command

Unset an environment variable from your deployment.

Usage

npx convex env remove <name>

Aliases

• convex env rm
• convex env unset

Arguments

name · string · required

Name of the environment variable to remove.

Examples

Remove a variable:

npx convex env remove API_KEY

Remove from production:

npx convex env remove OLD_CONFIG --prod

Deployment selection

All convex env subcommands support deployment selection:

• --prod - Target production deployment
• --preview-name <name> - Target a preview deployment
• --url <url> - Target a specific deployment URL
• --admin-key <key> - Admin key for authentication

By default, commands target your dev deployment.

Environment variable format

When using --from-file, the file should follow the .env format:

# Comments are allowed
API_KEY=sk_live_abc123
DATABASE_URL=postgresql://localhost/mydb
FEATURE_FLAG=true

# Multi-line values use quotes
PRIVATE_KEY="-----BEGIN PRIVATE KEY-----
MIIEvgIBADANBgkqhkiG9w0BAQEFAASCBKgwggSkAgEAAoIBAQ...
-----END PRIVATE KEY-----"

Best practices

1. Never commit secrets - Don’t commit .env files with secrets to version control
2. Use different values per environment - Production and dev should have separate API keys
3. Set in CI/CD - Use convex env set in deployment pipelines to configure production
4. Validate on startup - Check for required environment variables in your backend initialization code

Security

Environment variables are:

• Encrypted at rest
• Only accessible to your Convex functions
• Not exposed in client-side code
• Transmitted securely over HTTPS

Values are shown in the Convex dashboard but can be marked as sensitive to hide them from unauthorized team members.