FunctionsLast updated October 13, 2026

Add environment variables to functions

Learn to add environment variables to your functions.

Environment variables let you keep secrets, like tokens or API keys, hidden and out of version control. Sanity Functions lets you manage environment variables from the CLI so they're available to your deployed functions.

In this guide, you'll learn to add environment variables and access them from within your function code.

Prerequisites:

Complete the Functions quick start, or be comfortable creating and deploying a function.
Use the latest version of the sanity CLI (sanity@latest) to interact with Blueprints and Functions as shown in this guide. You can always run the latest CLI commands with npx sanity@latest.

Create a function

If you don't already have a blueprint and function set up, create them now.

Initialize a blueprint:

Add a function:

In this example, set the function to trigger on Document Create and Document Update, use TypeScript, and set the name to envExample.

✔ Enter function name: envExample
✔ Choose events to trigger your function: Document Create, Document Update
✔ Choose function language: TypeScript
✔ Add @sanity/functions helpers to the new Function? yes
✔ How to install the @sanity/functions helpers: npm

This creates a function in the functions/envExample directory.

Develop locally

Variables added with functions env add aren't available locally, but you can simulate them by prefixing your CLI command with the variable and value.

Start by updating the function to display the variable. This example uses a variable called SANITY_SECRET_SAUCE.

import { documentEventHandler } from '@sanity/functions'

export const handler = documentEventHandler(async ({ context, event }) => {
  console.log(`The secret: ${process.env.SANITY_SECRET_SAUCE}`)
})

export async function handler({context, event}) {
  console.log(`The secret: ${process.env.SANITY_SECRET_SAUCE}`)
}

All environment variables are accessible on process.env.

To test the function's access to a variable, prefix the CLI command with it.

If everything worked, you'll see this output:

Now that it works locally, make the same variable available to your deployed function.

Add an environment variable

Before you can add environment variables, you need to deploy the blueprint.

With the blueprint deployed, you can add environment variables to the function.

Add them with the sanity functions env add FUNCTION_NAME VARIABLE_NAME VARIABLE_VALUE command.

npx sanity@latest functions env add envExample SANITY_SECRET_SAUCE "content operating system"

pnpm dlx sanity@latest functions env add envExample SANITY_SECRET_SAUCE "content operating system"

yarn dlx sanity@latest functions env add envExample SANITY_SECRET_SAUCE "content operating system"

bunx sanity@latest functions env add envExample SANITY_SECRET_SAUCE "content operating system"

Create or update a document to trigger the function, then check the function's logs. The output matches the one from the local test.

You've now deployed and accessed an environment variable from a function.

When you're done with this function and blueprint, destroy the blueprint to prevent unexpected billing:

List and remove environment variables

Environment variables are linked to individual functions. In addition to add, you can use the following commands to interact with them:

sanity functions env list FUNCTION_NAME: List the environment variable keys set on the given function. Values are never displayed.
sanity functions env remove FUNCTION_NAME VARIABLE_NAME: Remove the variable from the deployed function.

A function's environment variables share a 4KB size limit, and deploying a blueprint never removes a variable, even one you delete from the blueprint. Learn more in Max environment variable size.

For additional usage information, add --help after each CLI command. You can read more about the CLI in the Functions CLI reference.

Troubleshooting

Adding a variable before deploying

sanity functions env add writes to the Sanity’s Functions service, not to your local blueprint. The function has to exist in a deployed stack first, so running it before sanity blueprints deploy fails. The command doesn't warn and continue; it stops. env list and env remove behave the same way.

Which message you get depends on how far the CLI gets:

Missing Stack: provide --stack, or set a Stack in your Blueprint config (`sanity blueprints config --edit`).: No stack is configured yet.
Missing Stack deployment: A stack ID is set, but no deployment exists to load.
Unable to find deployed function: "FUNCTION_NAME": The stack is deployed, and the function is declared locally but isn't in the deployment yet.
Unable to find function: "FUNCTION_NAME": The name doesn't match any function in the stack.

None of these messages tells you to deploy. They point you at sanity blueprints doctor, which reports the configuration problem but not the ordering mistake behind it. Run sanity blueprints deploy first, then add the variable. Adding a variable doesn't redeploy the stack, and the new value takes effect on the next function invocation.

Running the command outside a blueprint directory

Run the command from the blueprint directory or a subdirectory. The manifest is required even though the command only touches remote state. Without it you get Could not find a Blueprint manifest (sanity.blueprint.ts, .js, or .json). If the API rejects the change after the function resolves, the CLI reports Failed to update VARIABLE_NAME with the reason from the Functions API.

Was this page helpful?