The checkly env command manages global environment variables in your Checkly account. Create, update, list, export, and remove variables that are available across all checks in your account.
Before using , ensure you have:
  • An initialized Checkly CLI project
  • At least one check or resource defined in your project
  • Valid Checkly account authentication (run npx checkly login if needed)
  • A checkly.config.ts or checkly.config.js configuration file
For additional setup information, see CLI overview.

​
Usage

The basic command structure uses subcommands to manage environment variables.
Terminal
npx checkly env <subcommand> [arguments] [options]

​
Subcommands

SubcommandDescription
addCreate and add a new environment variable.
updateUpdate an existing environment variable.
lsList all global environment variables.
pullExport variables to a local file.
rmRemove an environment variable.

​
checkly env add

Create a new global environment variable. Usage:
Terminal
npx checkly env add <key> <value> [options]
Options:
OptionDescription
--locked, -lLock variable.
--secret, -sStore as secret.
Examples:
Terminal
# Add regular variable
npx checkly env add ENVIRONMENT "production"

# Add locked variable
npx checkly env add INTERNAL_API_URL "https://internal.api.com" --locked

# Add secret variable
npx checkly env add API_SECRET "super-secret-key" --secret

​
checkly env update

Update an existing global environment variable. Usage:
Terminal
npx checkly env update <key> <value> [options]
Options:
OptionDescription
--locked, -lLock variable.
--secret, -sStore as secret.
Examples:
Terminal
# Update regular variable
npx checkly env update ENVIRONMENT "staging"

# Update and convert to locked
npx checkly env update API_KEY "new-secret-key" --locked

# Update existing secret
npx checkly env update DATABASE_PASSWORD "new-password" --secret

​
checkly env ls

List all global environment variables in your account. Usage:
Terminal
npx checkly env ls
Examples:
Terminal
# List all variables
npx checkly env ls
Shows variable keys and their values. Secret values are hidden for security.

​
checkly env pull

Export global variables from your Checkly account to a local file. Usage:
Terminal
npx checkly env pull [filename] [options]
Options:
OptionDescription
--force, -fOverwrite existing file without confirmation
Examples:
Terminal
# Pull to default .env file
npx checkly env pull

# Pull to specific file
npx checkly env pull .env.production

# Force overwrite existing file
npx checkly env pull .env.production --force

​
checkly env rm

Remove a global environment variable. Usage:
Terminal
npx checkly env rm <key> [options]
Options:
OptionDescription
--force, -fSkip confirmation dialog
Examples:
Terminal
# Remove with confirmation
npx checkly env rm ENVIRONMENT

# Remove without confirmation
npx checkly env rm OLD_VARIABLE --force

​
Variable Types

​
Regular Variables

Standard key-value pairs visible to all team members:
Terminal
npx checkly env add ENVIRONMENT "production"

​
Locked Variables

Locked environment variables can only be accessed by team members with “Read & Write” access or above.
Terminal
npx checkly env add INTERNAL_API_URL "https://internal.api.com" --locked

​
Secrets

Once saved, secrets are never shown in the UI or in logs. The secret value cannot be accessed via the CLI or API.
Terminal
npx checkly env add API_SECRET "super-secret-key" --secret

​
Variable Scope

Environment variables managed by checkly env are global and available to:
  • All checks in your account
  • All check groups
  • All team members (unless locked)
For check-specific or group-specific variables, use the web UI or configure them directly in your monitoring-as-code setup.

​
Best Practices

  1. Use secrets for sensitive data like API keys, passwords, and tokens
  2. Lock internal variables that shouldn’t be visible to read-only users
  3. Use descriptive names following standard conventions (UPPER_SNAKE_CASE)
  4. Document variables and their purposes for team collaboration
  5. Regular cleanup of unused variables to maintain security