Skip to main content
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us