← All Posts

How to Do Env Variable Management on Claude Code

Claude Code reads environment variables directly from your shell session and from .env files in your project root. Set variables with export VAR=value before launching Claude Code, or place them in a .env file that your project loads automatically. Claude Code does not inject variables into your shell, but it can read, reference, and help manage them throughout your session.

  • Claude Code inherits all environment variables active in the terminal session where it is launched.
  • Variables in .env files are read by your app's runtime (Node, Python, etc.) but Claude Code can inspect and edit those files directly.
  • Sensitive credentials like API keys should never be hardcoded in source files. Claude Code enforces this by working within your existing secret management setup.

What is environment variable management in Claude Code?

Environment variable management in Claude Code means controlling which runtime secrets, API keys, and config values are available during your coding session. Because Claude Code runs as an agentic process in your terminal, it naturally picks up your shell's environment. This makes it straightforward to wire up credentials for tools it calls (databases, APIs, cloud SDKs) without duplicating config files.

Claude Code can read your current environment, help you scaffold .env files, validate variable names against expected patterns, and even warn you when a variable looks like it might be missing. The workflow fits directly into standard 12-factor app config practices.

How to pass environment variables to Claude Code

Method 1: shell export before launching

The simplest approach is to export variables in your current shell before starting a Claude Code session:

export DATABASE_URL="postgres://user:pass@localhost/mydb"
export OPENAI_API_KEY="sk-..."
claude

Claude Code inherits the full environment of the parent shell. Any tool it invokes (bash commands, test runners, build scripts) will also have access to those variables.

Method 2: inline variable assignment

For one-off sessions, prefix the claude command:

DATABASE_URL="postgres://..." claude

This scopes the variable to that Claude Code process only, which is useful when you want to test against a staging database without changing your persistent shell environment.

Method 3: .env file in the project root

Most Node, Python, and Ruby projects auto-load a .env file at startup via libraries like dotenv or python-dotenv. Claude Code can read, edit, and create these files directly. Ask Claude Code to scaffold one:

Add a .env.example file that documents all required environment variables for this project

Claude Code will scan your codebase for process.env references (or Python's os.environ) and produce a documented template.

Method 4: direnv for per-project automation

direnv hooks into your shell and loads a .envrc file automatically when you cd into a directory. Since Claude Code launches from your shell, variables loaded by direnv are already present. This is the cleanest setup for multi-project workflows where each project needs a different set of credentials.

How Claude Code handles secrets and sensitive variables

Claude Code does not store or transmit your environment variables to Anthropic beyond what is needed to execute the current task. However, you should still follow secure practices:

  • Add .env to your .gitignore immediately. Claude Code will flag this if it is missing when you ask it to set up a project.
  • Use .env.example (committed) alongside .env (ignored) to document required variables without leaking values.
  • For macOS-native credential storage, use the macOS Keychain via the security CLI. Usagebar, for instance, stores your Claude credentials securely in Keychain rather than in plaintext config files.
  • Rotate any key you accidentally commit immediately. Claude Code can help you audit a repo's git history for leaked secrets if you ask it to.

Using the /env command and slash commands in Claude Code

Claude Code supports slash commands that give you quick access to session context. While there is no dedicated /env slash command, you can use natural language prompts mid-session to inspect or update variable usage:

  • "What environment variables does this project require?" : Claude Code scans imports and process.env/os.environ calls across the codebase.
  • "Check if my .env file is missing any required variables." : Claude Code diffs your .env against the .env.example template.
  • "Update DATABASE_URL in my .env to point to the staging server." : Claude Code edits the file directly.
  • "Is STRIPE_SECRET_KEY committed anywhere in this repo?" : Claude Code searches git history and working files.

You can also check your session context and usage at any point with the /usage command, which shows how much of your plan's token budget you have consumed in the current session.

Common patterns for different stacks

Node.js / Next.js

Next.js has built-in env loading: .env.local for secrets, .env for defaults. Ask Claude Code: "Set up my Next.js environment files with proper naming conventions and add them to .gitignore."

Python / Django / FastAPI

Use python-dotenv or pydantic-settings. Ask Claude Code: "Add pydantic-settings to this FastAPI project and load DATABASE_URL and SECRET_KEY from environment."

Docker Compose

Pass an env_file directive in docker-compose.yml. Claude Code can scaffold the compose file and the matching .env together: "Set up docker-compose with a Postgres service that reads credentials from .env."

GitHub Actions / CI/CD

Secrets in CI should live in the platform's secret manager (GitHub Secrets, AWS SSM, etc.), not in .env files. Ask Claude Code: "Show me how to reference GitHub Actions secrets in my workflow file for DEPLOY_KEY and DATABASE_URL."

Key takeaways

  1. Export variables in your shell before running claude, or use direnv for automatic per-project loading.
  2. Keep .env in .gitignore and maintain a .env.example for documentation.
  3. Claude Code can audit your codebase for missing or leaked variables on request.
  4. For sensitive tokens on macOS, prefer Keychain storage over plaintext files.
  5. Use the /usage command to monitor your session token consumption, especially during long refactoring tasks that touch many files.

Stay in flow while managing secrets and usage

Long environment setup sessions eat into your Claude Code usage window. The worst outcome: you hit the 5-hour rate limit right before running the final integration test. Usagebar puts your remaining Claude Code usage directly in the macOS menu bar, with smart alerts at 50%, 75%, and 90% so you know exactly when to wrap up a session. Credentials are stored in macOS Keychain, never in plaintext. It's free for students, and pay-what-you-want for everyone else.

Get Usagebar : instant download, no subscription required.

Related guides

Track Your Claude Code Usage

Never hit your usage limits unexpectedly. Usagebar lives in your menu bar and shows your 5-hour and weekly limits at a glance.

Get Usagebar