Environment variables with the CLI and API

Experimental Feature

This experimental feature is available to try out before it’s fully released or ready for production. We recommend using it in non-critical sites and non-production environments only. Learn more in our Netlify Labs doc.

The Netlify CLI and API can be used to add, edit, or delete environment variables for sites using the new secrets store in the beta experience.

This includes support for reading and setting scopes and contextual values. An environment variable’s contextual values are the different values set for use in each deploy context.

Any updates made using the CLI or API will be reflected in the Netlify UI.

# CLI

Netlify CLI 11.5.0 adds full beta support for accessing and setting environment variables in the new experience using netlify dev and netlify env.

The Netlify CLI is the local development context

By default, the Netlify CLI deploy context is the local development context (dev). Unless a different deploy context is specified, CLI commands will get and use variables that have values set specifically for use with the dev deploy context and variables that have a single value for use across all deploy contexts.

There are two new flags available for use with the CLI’s netlify dev, netlify env:set, netlify env:get, and netlify env:list commands:

  • --context: to set or get contextual values for an environment variable. Accepted values are production, deploy-preview, branch-deploy, branch:YOUR_BRANCH_NAME, and dev for the local development environment. You can also use all to set the same value for use across all deploy contexts.

  • --scope: to set an environment variable’s scope or get variables that include that scope, available for teams on Pro plans and above. Accepted values are builds, functions, runtime, and post_processing. You can also use all when you set a value or any when you get a value.

You can use both flags in the same command, for example:

netlify env:set API_KEY someValue --scope functions --context production branch-deploy
netlify env:list --scope builds --context deploy-preview

The updated CLI commands now operate as follows:

  • env:get retrieves the value set for local development with the Netlify CLI (deploy contexts dev or all). You can use the --context flag to retrieve a value from another context or the --scope flag to retrieve a value only if the variable is available to a specific scope.

  • env:list: lists all site environment variables that have values set for local development with the Netlify CLI (deploy contexts dev or all). You can request other contextual values using the --context flag and filter the list using the --scope flag. The list will only include shared environment variables if the command is run by a team Owner.

  • env:set: creates or updates a site environment variable with the provided value, scopes, and deploy contexts. Only one value can be set at a time, but you can set it to multiple deploy contexts and scopes in a space-separated list (no commas). If you omit the --scope or --context flags when running the env:set command, the variable is set to all scopes and with the same value for all deploy contexts.

    For example, to set one value for production and deploy-preview and another value for a branch named staging, run the command twice:

    netlify env:set API_KEY someValue --context production deploy-preview
    netlify env:set API_KEY someOtherValue --context branch:staging
    
  • env:import: imports variables from a given file and sets them to all scopes and with the same value for all deploy contexts.

  • env:migrate is now aliased to env:clone: copies environment variables from one site to another. If you clone variables from a site in the beta to a site that is not, the cloned variable will be available to all scopes and will use the value set for use with the Netlify CLI (deploy contexts dev or all).

  • env:unset: deletes the specified variable and its values from all deploy contexts. You can use the --context flag to delete one value from a specific deploy context instead.

  • netlify dev: runs your project using environment variables that have values set for local development with the Netlify CLI (deploy contexts dev or all). You can use the --context flag to run your project with a different deploy context’s settings and variables. Note that environment variables apply to all scopes when running netlify dev.

  • netlify build: updated to build your project using environment variables from not only netlify.toml, but also any set using the Netlify UI, API, or CLI. Note that environment variables apply to all scopes when running netlify build locally. The default build context is production but you can use the --context flag to specify a build for a different deploy context. For example:

    netlify build --context branch:staging
    

Access the full command reference to learn more about the updated CLI commands and the values they support.

# API

You can use the new beta environment variables API endpoints to access and set both site and shared environment variables for migrated sites.

The new endpoints include:

  • getEnvVars: returns all environment variables for a team or site. The list will only include shared environment variables if the request is made by a team Owner.
  • createEnvVars: creates site or shared environment variables with the specified scopes and contextual values.
  • getEnvVar: returns an individual environment variable for a team or site.
  • updateEnvVar: updates an existing environment variable by replacing all of its values with the values provided with this request.
  • setEnvVarValue: updates or creates a new value for an existing environment variable.
  • deleteEnvVar: deletes an environment variable and all of its values.
  • deleteEnvVarValue: deletes a specific environment variable value.

Note that migrated site environment variables can no longer be accessed or updated using the sites endpoints. The env property in the build-settings object will be an empty array. All updates for migrated environment variables should use the new environment variables endpoints instead.

Access the full endpoint reference to learn more about the new endpoints and their specifications.