env0

Load environment variables directly from 1Password and never store secrets in .env files again.

Features

• Load environment variables directly from 1Password vaults
• Simple configuration using a .env0 file to declare required envs
• Easy integration with any command or script

Prerequisites

• 1Password CLI installed and configured

Installation

npm install env0

Usage

1. Create a .env0 file

In your project root, add a .env0 file (this can be commited in version control) with the environment variable names that should be loaded from 1Password:

# Shorthand assignment - loads TEST_ENV_VAR from 1Password
TEST_ENV_VAR

# Literal string assignment
LITERAL_VAR="my static value"

# Reference assignment - loads SOURCE_VAR from 1Password
RENAMED_VAR=SOURCE_VAR

# Section syntax - load multiple fields from a single 1Password item
[item:supabase]
SUPABASE_SECRET_KEY
SUPABASE_URL
SUPABASE_KEY=SUPABASE_ANON_KEY

You can also create a .env0.local file for local development overrides. This file should not be committed to version control:

# Override with a local value
DB_URL="postgres://localhost:5432/my_local_db"

2. Create secrets in 1Password

Create a 1Password vault and add the environment variables to it:

3. Run commands with env0

Use env0 to load environment variables into a sub process that runs the specified command.

# Basic usage
env0 --source op:your-vault-name -- your-command

# Use a custom env0 file
env0 --source op:your-vault-name --file "./env0.custom" -- your-command

# Use multiple env0 files (later files override earlier ones)
env0 --source op:your-vault-name -f .env0.base -f .env0.staging -- your-command

# Alternatively, print environment variables for shell export
env0 --source op:your-vault-name --print

CLI Options

• -s, --source <platform:vault>: Specify the source in format platform:vault (e.g. op:secrets-staging)
• -f, --file <path>: Path to an env0 file (can be specified multiple times; defaults to .env0 unless -e is used)
• -e, --entry <entries...>: Specify environment variable entries inline
• -p, --print: Print environment variables for shell export
• Any additional arguments are passed to the command being executed

How It Works

1. The CLI loads environment variables using either:
   • The env0 file(s) specified by -f, --file, or
   • Inline entries specified via -e, --entry, or
   • Both sources when both -f and -e are both explicitly specified
2. When multiple -f files are specified, they are processed in order.
3. If a .env0.local file exists in the same directory as the env0 file, it will be loaded and its values will override or extend the base configuration.
4. Where there are multiple files declared, each file's .local override is applied immediately after (e.g., -f a -f b loads: a → a.local → b → b.local).
5. For each entry, it processes the environment variable based on its type:
   • Shorthand (e.g., VAR): Fetches the corresponding item from the specified 1Password vault
   • Literal (e.g., VAR="value"): Uses the literal string value provided
   • Reference (e.g., VAR=SOURCE_VAR): Fetches the value from another 1Password item
   • Section (e.g., [item:name]): Sets the context for subsequent entries to fetch fields from a specific 1Password item by title
6. Environment variables are loaded into the process
7. The specified command is executed with the loaded environment variables

Programmatic API

Reading Secrets

Use the read function to load secrets from 1Password programmatically:

import { read } from "env0";

// Basic usage - reads from .env0 file by default
const env = await read({
  source: "op:my-vault",
});

// With custom files and inline entries
const env = await read({
  source: "op:my-vault",
  files: [".env0", ".env0.staging"],
  entries: ["API_KEY", "DB_URL=database_url"],
});

// Use with any process spawning library
import { spawn } from "child_process";
spawn("npm", ["run", "dev"], {
  env: { ...process.env, ...env },
});

Parsing

An API is also provided for parsing .env0 files without resolving secrets.

import { parse, parseFile, parseFiles } from "env0";

// Parse a string
const result = parse(`
  API_KEY
  DB_URL="localhost"
  [item:stripe]
  STRIPE_KEY
`);

result.getKeys();        // ["API_KEY", "DB_URL", "STRIPE_KEY"]
result.getExpressions(); // { API_KEY: { key, type, ... }, ... }
result.has("API_KEY");   // true

// Parse a file
const result = parseFile(".env0");

// Parse multiple files (later files override earlier ones)
const result = parseFiles([".env0", ".env0.staging"], {
  resolveLocalOverrides: true, // also reads .env0.local, .env0.staging.local
});

Types

type ReadOptions = {
  source: string;      // Required: "op:vault-name"
  files?: string[];    // Default: [".env0"]
  entries?: string[];  // Additional inline entries
};

type ExpressionType = "shorthand" | "literal" | "reference";

type ExpressionNode = {
  key: string;
  type: ExpressionType;
  value?: string;       // The literal value or reference key
  itemContext?: string; // The 1Password item name when inside a [item:X] section
};

Examples

# Run a command with environment variables from 1Password dev vault
env0 --source op:dev -- node app.js

# Run a command inside a shell (single quotes for shell interpolation)
env0 -s op:dev -e DB_URL -sh 'echo $DB_URL'

# Use specific environment variables without a env0 file
env0 --source op:dev --entry DB_URL --entry API_KEY -- node app.js

# Use literal and reference assignments inline
STAGE="dev" env0 -s op:dev -e DB_PASS=PROD_DB_PASS -- node app.js

# Combine env0 file with additional entries
env0 -s op:dev -f .env0 -e EXTRA_VAR1 -e EXTRA_VAR2 -- node app.js

# Load from multiple env0 files (base config + environment-specific overrides)
env0 -s op:dev -f .env0 -f .env0.staging -- node app.js

# Export variables to your shell and run a command
eval $(env0 -s op:dev -p) && node app.js

License

MIT License

Contributors

• Daniel Grant