How to use .env files in Thunder Client

On this page

Managing API keys, URLs, and credentials across your development environments shouldn’t mean maintaining the same variables in multiple places.

Most projects already have a .env file containing these values. Now, Thunder Client can read that file directly. Simply link it to an environment, and your API requests will use the values automatically — no importing, duplicating, or manually syncing variables.

In this guide, we’ll walk through how to connect .env files to Thunder Client, switch between Development, Staging, and Production environments, and run your collections using the same configuration from the CLI.

To make things practical, we’ll walk through the setup using a real-world example: an Event Booking API built with Express. The steps are identical in VS Code and JetBrains IDEs, and this feature is available on all plans, including Free.

Step 1: Your .env file

Here’s the .env file from the Event Booking API’s root folder, with placeholders in place of real secrets:

.env
# Auth service
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
# API settings
PORT=3001
# reference another variable in the same file
API_URL=http://localhost:${PORT}/api
# Test user
TEST_EMAIL=organiser@example.com
TEST_PASSWORD=your-test-password

Each line holds one KEY=value pair, and lines that start with # are comments.

Before going further, add these lines to your .gitignore so your .env files never reach Git:

.gitignore
.env
.env.*
!.env.example

The .env.* pattern also covers the .env.staging and .env.production files you’ll add in Step 4. The !.env.example exception lets you commit a template with placeholder values, so teammates know which variables they need to set.

  1. In the Env tab, click the ☰ menu, choose New Environment and name it Development.
  2. Select the Link to .env file checkbox, then click the file field and choose your project’s .env file. The environment saves automatically.
  3. Set Development as the active environment.

Every variable in the file is now available as {{VARIABLE_NAME}}. You can still add variables directly to the environment, such as apiVersion and timeout in the screenshot below, and they work alongside the ones from the file.

Select Link to .env file and choose your file

Thunder Client loads the file’s variables only while this environment is active, and it rereads the file on every request. If you change a value in .env, your next request picks it up, with no need to reopen the environment.

Step 3: Use the variables in a request

The Event Booking API uses Supabase for sign-in. To sign in as the test user, create a POST request to this URL:

Text
{{SUPABASE_URL}}/auth/v1/token?grant_type=password

In the Headers tab, add an apikey header with the value {{SUPABASE_ANON_KEY}}. Then, in the Body tab, choose JSON and enter:

JSON
{
"email": "{{TEST_EMAIL}}",
"password": "{{TEST_PASSWORD}}"
}

Click Send, and you should get a 200 OK response. Thunder Client fills in all four values from your .env file when it sends the request, so none of them are saved in the request itself.

The URL, API key and login credentials all come from your .env file

Step 4: Add Staging and Production files

Give each environment its own file, using the same variable names with different values:

Environment Linked file
Development .env
Staging .env.staging
Production .env.production
  1. Create .env.staging and .env.production alongside your .env file, and fill them with your staging and production values:

    .env.production
    SUPABASE_URL=https://your-prod-project.supabase.co
    SUPABASE_ANON_KEY=your-prod-anon-key
  2. Create Staging and Production environments, and link each one to its matching file as you did in Step 2.

  3. Switch the active environment, and Thunder Client loads that environment’s linked file. The same requests now hit staging or production without any edits.

Each environment links to its own file

You don’t need to update .gitignore: the .env.* line from Step 1 already keeps these files out of Git.

Step 5: Run it from the CLI

The Thunder Client CLI loads the linked .env file as well. Save your requests to a collection, then open a terminal in your project’s root folder and run the collection with an environment:

Terminal
tc --col 'Event Booking API' --env 'Development'
Every request passes, using the values from your .env file

Each request returns 200, which confirms that the CLI read the values from your .env file.

To override a value for a single run, pass it with --var-data, which takes priority over the .env file.

Use it with your AI agent

Thunder Client also works with AI agents such as Claude Code and Codex. When an agent lists your environments, it sees only their names and never the values from your .env file.

To set this up, see Introducing Thunder Client MCP Server v2.

Good to know

  • Unlink any time. Open the environment and clear the Link to .env file checkbox. The environment saves automatically, and the file’s variables stop loading.
  • Environment values win. If the same variable is defined in both the environment and the .env file, the environment’s value is used. Use different names unless you want the environment to override the file.
  • Link, don’t import. Importing a .env file from the Env tab copies its values into the environment, while linking keeps them in the file.
  • File paths. With Git Sync or a custom save location, Thunder Client saves the path relative to your project. Otherwise, it saves the full path, so the .env file must exist at the same location on every machine that runs your requests, such as a CI server.

Next steps

Questions or ideas? Contact us or open an issue on GitHub.

Try it on your own API

Thunder Client is a lightweight API client that lives inside VS Code and JetBrains IDEs.

Written by
Varun Kumar ManchikantiSoftware Engineer at Thunder Client