envsitter

Safely inspect and match .env secrets without ever printing values.

envsitter is designed for LLM/agent workflows where you want to:

• List keys present in an env source (.env file or external provider)
• Compare a key’s value to a candidate value you provide at runtime ("outside-in")
• Do bulk matching (one candidate against many keys, or candidates-by-key)
• Produce deterministic fingerprints for comparisons/auditing
• Ask boolean questions about values (empty/prefix/suffix/regex/type-ish checks) without ever returning the value

Related: https://github.com/boxpositron/envsitter-guard — an OpenCode plugin that blocks agents/tools from reading or editing sensitive .env* files (preventing accidental secret leaks), while still allowing safe inspection via EnvSitter-style tools (keys + deterministic fingerprints; never values).

Security model (what this tool does and does not do)

• Values are read in-process for comparisons, but never returned by the library API and never printed by the CLI.
• Deterministic matching uses HMAC-SHA-256 with a local pepper.
  • This avoids publishing raw SHA-256 hashes that are easy to dictionary-guess.
• Candidate secrets should be passed via stdin (--candidate-stdin) to avoid shell history.

Non-goals:

• This tool is not a secret manager.
• This tool does not encrypt or relocate .env values; it operates on sources in-place.

Install

npm install envsitter

Or run the CLI without installing globally:

npx envsitter keys --file .env

Pepper (required for deterministic fingerprints)

envsitter uses a local "pepper" as the HMAC key.

Resolution order:

1. process.env.ENVSITTER_PEPPER (or ENV_SITTER_PEPPER)
2. Pepper file at .envsitter/pepper (auto-created if missing)

The pepper file is created with mode 0600 when possible, and .envsitter/ is gitignored.

CLI usage

Quick reference

Command	Description
keys	List all keys in an env file
fingerprint	Get deterministic fingerprint for a key
match	Match candidate value(s) against key(s)
match-by-key	Bulk match candidates by key
scan	Detect value shapes (JWT, URL, base64)
validate	Check dotenv syntax
copy	Copy keys between env files
format / reorder	Sort and organize env files
annotate	Add comments to keys
add	Add new key (fails if exists)
set	Create or update key
unset	Set key to empty value
delete	Remove key(s) from file

Commands

• keys --file <path> [--filter-regex <re>]
• fingerprint --file <path> --key <KEY>
• match --file <path> (--key <KEY> | --keys <K1,K2> | --all-keys) [--op <op>] [--candidate <value> | --candidate-stdin]
• match-by-key --file <path> (--candidates-json <json> | --candidates-stdin)
• scan --file <path> [--keys-regex <re>] [--detect jwt,url,base64]
• validate --file <path>
• copy --from <path> --to <path> [--keys <K1,K2>] [--include-regex <re>] [--exclude-regex <re>] [--rename <A=B,C=D>] [--on-conflict error|skip|overwrite] [--write]
• format --file <path> [--mode sections|global] [--sort alpha|none] [--write]
• reorder --file <path> [--mode sections|global] [--sort alpha|none] [--write]
• annotate --file <path> --key <KEY> --comment <text> [--line <n>] [--write]
• add --file <path> --key <KEY> [--value <v> | --value-stdin] [--write]
• set --file <path> --key <KEY> [--value <v> | --value-stdin] [--write]
• unset --file <path> --key <KEY> [--write]
• delete --file <path> (--key <KEY> | --keys <K1,K2>) [--write]

Notes for file operations:

• Commands that modify files (copy, format/reorder, annotate, add, set, unset, delete) are dry-run unless --write is provided.
• These commands never print secret values; output includes keys, booleans, and line numbers only.
• When targeting example files (.env.example, .env.sample, .env.template, .env.dist, .env.default), a warning is emitted. Use --no-example-warning to suppress.
• Non-standard env file names are fully supported (e.g., api.env, database.env, config.env.local).
• Values with special characters (spaces, #, quotes, newlines) are automatically double-quoted with proper escaping.

List keys

envsitter keys --file .env

Filter by key name (regex):

envsitter keys --file .env --filter-regex "/(KEY|TOKEN|SECRET)/i"

Fingerprint a single key

envsitter fingerprint --file .env --key OPENAI_API_KEY

Outputs JSON containing the key’s fingerprint and metadata (never the value).

Match a candidate against a single key (recommended via stdin)

node -e "process.stdout.write('candidate-secret')" \
  | envsitter match --file .env --key OPENAI_API_KEY --candidate-stdin --json

Exit codes:

• 0 match found
• 1 no match
• 2 error/usage

Match operators (for humans)

envsitter match supports an --op flag.

• Default: --op is_equal
• When --op is_equal is used, EnvSitter hashes both the candidate and stored value with the local pepper (HMAC-SHA-256) and compares digests using constant-time equality.
• Other operators evaluate against the raw value in-process, but still only return booleans/match results (no values are returned or printed).

Operators:

• exists: key is present in the source (no candidate required)
• is_empty: value is exactly empty string (no candidate required)
• is_equal: deterministic match against a candidate value (candidate required)
• partial_match_prefix: value.startsWith(candidate) (candidate required)
• partial_match_suffix: value.endsWith(candidate) (candidate required)
• partial_match_regex: regex test against value (candidate required; candidate is a regex like "/^sk-/" or a raw regex body)
• is_number: value parses as a finite number (no candidate required)
• is_boolean: value is true/false (case-insensitive, whitespace-trimmed) (no candidate required)
• is_string: value is neither is_number nor is_boolean (no candidate required)

Examples:

# Prefix match
node -e "process.stdout.write('sk-')" \
  | envsitter match --file .env --key OPENAI_API_KEY --op partial_match_prefix --candidate-stdin

# Regex match (regex literal syntax)
node -e "process.stdout.write('/^sk-[a-z]+-/i')" \
  | envsitter match --file .env --key OPENAI_API_KEY --op partial_match_regex --candidate-stdin

# Exists (no candidate)
envsitter match --file .env --key OPENAI_API_KEY --op exists --json

Match one candidate against multiple keys

node -e "process.stdout.write('candidate-secret')" \
  | envsitter match --file .env --keys OPENAI_API_KEY,ANTHROPIC_API_KEY --candidate-stdin --json

Match one candidate against all keys

node -e "process.stdout.write('candidate-secret')" \
  | envsitter match --file .env --all-keys --candidate-stdin --json

Match candidates-by-key (bulk assignment)

Provide a JSON object mapping key -> candidate value.

envsitter match-by-key --file .env \
  --candidates-json '{"OPENAI_API_KEY":"sk-...","ANTHROPIC_API_KEY":"sk-..."}'

For safer input, pass the JSON via stdin:

cat candidates.json | envsitter match-by-key --file .env --candidates-stdin

Scan for value shapes (no values returned)

envsitter scan --file .env --detect jwt,url,base64

Optionally restrict which keys to scan:

envsitter scan --file .env --keys-regex "/(JWT|URL)/" --detect jwt,url

Validate dotenv syntax

envsitter validate --file .env
envsitter validate --file .env --json

Copy keys between env files (production → staging)

Dry-run (no file is modified):

envsitter copy --from .env.production --to .env.staging --keys API_URL,REDIS_URL --json

Apply changes:

envsitter copy --from .env.production --to .env.staging --keys API_URL,REDIS_URL --on-conflict overwrite --write --json

Rename while copying:

envsitter copy --from .env.production --to .env.staging --keys DATABASE_URL --rename DATABASE_URL=STAGING_DATABASE_URL --write

Annotate keys with comments

envsitter annotate --file .env --key DATABASE_URL --comment "prod only" --write

Reorder/format env files

envsitter format --file .env --mode sections --sort alpha --write
# alias:
envsitter reorder --file .env --mode sections --sort alpha --write

Add a new key (fails if key exists)

envsitter add --file .env --key NEW_API_KEY --value "sk-xxx" --write
# or via stdin (recommended to avoid shell history):
node -e "process.stdout.write('sk-xxx')" | envsitter add --file .env --key NEW_API_KEY --value-stdin --write

Set a key (creates or updates)

envsitter set --file .env --key API_KEY --value "new-value" --write
# or via stdin:
node -e "process.stdout.write('new-value')" | envsitter set --file .env --key API_KEY --value-stdin --write

Unset a key (set to empty value)

envsitter unset --file .env --key OLD_KEY --write

Delete keys

# Single key:
envsitter delete --file .env --key DEPRECATED_KEY --write

# Multiple keys:
envsitter delete --file .env --keys OLD_KEY,UNUSED_KEY,LEGACY_KEY --write

Output contract (for LLMs)

General rules:

• Never output secret values; treat all values as sensitive.
• Prefer --candidate-stdin over --candidate to avoid shell history.
• Exit codes: 0 match found, 1 no match, 2 error/usage.

JSON outputs:

• keys --json -> { "keys": string[] }
• fingerprint -> { "key": string, "algorithm": "hmac-sha256", "fingerprint": string, "length": number, "pepperSource": "env"|"file", "pepperFilePath"?: string }
• match --json (single key) ->
  • default op (not provided): { "key": string, "match": boolean }
  • with --op: { "key": string, "op": string, "match": boolean }
• match --json (bulk keys / all keys) ->
  • default op (not provided): { "matches": Array<{ "key": string, "match": boolean }> }
  • with --op: { "op": string, "matches": Array<{ "key": string, "match": boolean }> }
• match-by-key --json -> { "matches": Array<{ "key": string, "match": boolean }> }
• scan --json -> { "findings": Array<{ "key": string, "detections": Array<"jwt"|"url"|"base64"> }> }
• validate --json -> { "ok": boolean, "issues": Array<{ "line": number, "column": number, "message": string }> }
• copy --json -> { "from": string, "to": string, "onConflict": string, "willWrite": boolean, "wrote": boolean, "hasChanges": boolean, "issues": Array<...>, "plan": Array<...> }
• format --json / reorder --json -> { "file": string, "mode": string, "sort": string, "willWrite": boolean, "wrote": boolean, "hasChanges": boolean, "issues": Array<...> }
• annotate --json -> { "file": string, "willWrite": boolean, "wrote": boolean, "hasChanges": boolean, "issues": Array<...>, "plan": { ... } }
• add --json / set --json / unset --json -> { "file": string, "key": string, "willWrite": boolean, "wrote": boolean, "hasChanges": boolean, "issues": Array<...>, "plan": { "key": string, "action": "added"|"updated"|"unset"|"key_exists"|"not_found"|"no_change", "line"?: number } }
• delete --json -> { "file": string, "keys": string[], "willWrite": boolean, "wrote": boolean, "hasChanges": boolean, "issues": Array<...>, "plan": Array<{ "key": string, "action": "deleted"|"not_found", "line"?: number }> }

Library API

Basic usage

import { EnvSitter } from 'envsitter';

const es = EnvSitter.fromDotenvFile('.env');

const keys = await es.listKeys();
const fp = await es.fingerprintKey('OPENAI_API_KEY');
const match = await es.matchCandidate('OPENAI_API_KEY', 'candidate-secret');

File operations via the library

import {
  addEnvFileKey,
  annotateEnvFile,
  copyEnvFileKeys,
  deleteEnvFileKeys,
  formatEnvFile,
  setEnvFileKey,
  unsetEnvFileKey,
  validateEnvFile
} from 'envsitter';

await validateEnvFile('.env');

await copyEnvFileKeys({
  from: '.env.production',
  to: '.env.staging',
  keys: ['API_URL', 'REDIS_URL'],
  onConflict: 'overwrite',
  write: true
});

await annotateEnvFile({ file: '.env', key: 'DATABASE_URL', comment: 'prod only', write: true });
await formatEnvFile({ file: '.env', mode: 'sections', sort: 'alpha', write: true });

// Add a new key (fails if exists)
await addEnvFileKey({ file: '.env', key: 'NEW_KEY', value: 'new_value', write: true });

// Set a key (creates or updates)
await setEnvFileKey({ file: '.env', key: 'API_KEY', value: 'updated_value', write: true });

// Unset a key (set to empty)
await unsetEnvFileKey({ file: '.env', key: 'OLD_KEY', write: true });

// Delete keys
await deleteEnvFileKeys({ file: '.env', keys: ['DEPRECATED', 'UNUSED'], write: true });

Utility functions

import { isExampleEnvFile } from 'envsitter';

// Detect example/template env files
isExampleEnvFile('.env.example');      // true
isExampleEnvFile('api.env.sample');    // true
isExampleEnvFile('.env');              // false
isExampleEnvFile('api.env');           // false

Match operators via the library

import { EnvSitter } from 'envsitter';
import type { EnvSitterMatcher } from 'envsitter';

const es = EnvSitter.fromDotenvFile('.env');

const matcher: EnvSitterMatcher = { op: 'partial_match_prefix', prefix: 'sk-' };
const ok = await es.matchKey('OPENAI_API_KEY', matcher);

Bulk matching

import { EnvSitter } from 'envsitter';

const es = EnvSitter.fromDotenvFile('.env');

// One candidate tested against a set of keys
const matches = await es.matchCandidateBulk(['OPENAI_API_KEY', 'ANTHROPIC_API_KEY'], 'candidate-secret');

// One matcher tested against a set of keys
const prefixMatches = await es.matchKeyBulk(['OPENAI_API_KEY', 'ANTHROPIC_API_KEY'], { op: 'partial_match_prefix', prefix: 'sk-' });

// Candidates-by-key
const byKey = await es.matchCandidatesByKey({
  OPENAI_API_KEY: 'sk-...',
  ANTHROPIC_API_KEY: 'sk-...'
});

External sources (hooks)

You can load dotenv-formatted output from another tool/secret provider:

import { EnvSitter } from 'envsitter';

const es = EnvSitter.fromExternalCommand('my-secret-provider', ['export', '--format=dotenv']);
const keys = await es.listKeys();

Development

npm install
npm run typecheck
npm test

Run a single test file:

npm run build
node --test dist/test/envsitter.test.js

Run a single test by name:

npm run build
node --test --test-name-pattern "outside-in" dist/test/envsitter.test.js

License

MIT. See LICENSE.