### Install and Build Commands

Source: https://github.com/boxpositron/envsitter/blob/main/AGENTS.md

Standard commands for installing dependencies and building the project.

```bash
npm install
```

```bash
npm run build
```

--------------------------------

### Install envsitter

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Install the package via npm or execute the CLI directly using npx.

```bash
npm install envsitter
```

```bash
npx envsitter keys --file .env
```

--------------------------------

### TypeScript Import Examples

Source: https://github.com/boxpositron/envsitter/blob/main/AGENTS.md

Examples of correct ESM import syntax for local modules and Node.js built-ins.

```typescript
import { parseDotenv } from '../dotenv/parse.js'
```

```typescript
import { readFile } from 'node:fs/promises'
```

--------------------------------

### Development workflow commands

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Standard commands for installing dependencies, type checking, and running the test suite.

```bash
npm install
npm run typecheck
npm test
```

--------------------------------

### Detect Example Env Files with isExampleEnvFile

Source: https://context7.com/boxpositron/envsitter/llms.txt

Use `isExampleEnvFile` to identify example or template environment files, preventing accidental modification of sensitive configuration.

```typescript
import { isExampleEnvFile } from 'envsitter';

console.log(isExampleEnvFile('.env.example'));   // true
console.log(isExampleEnvFile('.env.sample'));    // true
console.log(isExampleEnvFile('.env.template'));  // true
console.log(isExampleEnvFile('.env.dist'));      // true
console.log(isExampleEnvFile('.env.defaults'));  // true
console.log(isExampleEnvFile('api.env.sample')); // true
console.log(isExampleEnvFile('.env'));           // false
console.log(isExampleEnvFile('api.env'));        // false
console.log(isExampleEnvFile('.env.production'));// false
```

--------------------------------

### EnvSitter Utility Function for Example Files

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Use the `isExampleEnvFile` function to detect if a file is an example or template environment file. It returns true for files ending with .example or .sample.

```typescript
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
```

--------------------------------

### Run CLI with Bun

Source: https://github.com/boxpositron/envsitter/blob/main/AGENTS.md

Execute the CLI using the Bun runtime.

```bash
bun src/cli.ts keys --file .env
```

--------------------------------

### Run test by pattern

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Builds the project and executes tests matching a specific name pattern.

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

--------------------------------

### Initialize EnvSitter from File

Source: https://context7.com/boxpositron/envsitter/llms.txt

Creates an EnvSitter instance from a local file to programmatically list keys.

```typescript
import { EnvSitter } from 'envsitter';

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

// List all keys
const keys = await es.listKeys();
console.log(keys); // ['API_KEY', 'DATABASE_URL', 'OPENAI_API_KEY']

// List keys with filter
const filteredKeys = await es.listKeys({ filter: /API/ });
console.log(filteredKeys); // ['API_KEY', 'OPENAI_API_KEY']
```

--------------------------------

### Format and Reorder Env Files

Source: https://context7.com/boxpositron/envsitter/llms.txt

Sorts and organizes environment files while preserving comments.

```bash
# Sort alphabetically within sections (default)
envsitter format --file .env --mode sections --sort alpha --write

# Sort globally (ignore section groupings)
envsitter format --file .env --mode global --sort alpha --write

# Alias command
envsitter reorder --file .env --mode sections --sort alpha --write

# Dry-run to preview
envsitter format --file .env --json
# Output: { "file": ".env", "mode": "sections", "sort": "alpha", "willWrite": false, "wrote": false, "hasChanges": true, "issues": [] }
```

--------------------------------

### Basic EnvSitter Library Usage

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Initialize EnvSitter from a .env file and perform basic operations like listing keys, fingerprinting a key, and matching a candidate secret.

```typescript
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');
```

--------------------------------

### Set a key

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Create or update an existing key with a new value.

```bash
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
```

--------------------------------

### Run specific test file

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Builds the project and executes a single test file using the Node.js test runner.

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

--------------------------------

### Testing Commands

Source: https://github.com/boxpositron/envsitter/blob/main/AGENTS.md

Commands for running the test suite, including specific file or pattern execution.

```bash
npm test
```

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

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

--------------------------------

### Reorder and format env files

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Sort and format the structure of an environment file.

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

--------------------------------

### List all keys in a dotenv file

Source: https://context7.com/boxpositron/envsitter/llms.txt

Use the `keys` command to list all environment variable keys present in a specified dotenv file. Supports filtering with regex and outputting as JSON.

```bash
# List all keys in .env file
envsitter keys --file .env
# Output:
# API_KEY
# DATABASE_URL
# OPENAI_API_KEY
# REDIS_URL
```

```bash
# List keys matching a pattern
envsitter keys --file .env --filter-regex "/(KEY|TOKEN|SECRET)/i"
# Output:
# API_KEY
# OPENAI_API_KEY
```

```bash
# Get keys as JSON
envsitter keys --file .env --json
# Output: { "keys": ["API_KEY", "DATABASE_URL", "OPENAI_API_KEY", "REDIS_URL"] }
```

--------------------------------

### Bulk match multiple candidate values against their respective keys

Source: https://context7.com/boxpositron/envsitter/llms.txt

The `match-by-key` command allows for efficient comparison of multiple candidate values against their corresponding keys. Candidates can be provided via a JSON argument or through stdin, with stdin being recommended for enhanced security.

```bash
# Via JSON argument
envsitter match-by-key --file .env \
  --candidates-json '{"OPENAI_API_KEY":"sk-abc...","ANTHROPIC_API_KEY":"sk-xyz..."}'
```

```bash
# Via stdin (recommended for security)
cat <<'EOF' | envsitter match-by-key --file .env --candidates-stdin
{"OPENAI_API_KEY":"sk-abc...","ANTHROPIC_API_KEY":"sk-xyz..."}
EOF
# Output:
# {
#   "matches": [
#     { "key": "OPENAI_API_KEY", "match": true },
#     { "key": "ANTHROPIC_API_KEY", "match": false }
#   ]
# }
```

--------------------------------

### List keys in an env file

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

List all keys or filter them using a regular expression.

```bash
envsitter keys --file .env
```

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

--------------------------------

### formatEnvFile

Source: https://context7.com/boxpositron/envsitter/llms.txt

Sorts and organizes environment files while preserving existing comments.

```APIDOC
## formatEnvFile

### Description
Formats the structure of a .env file.

### Parameters
#### Request Body
- **file** (string) - Required - Path to the file.
- **mode** ('sections' | 'global') - Optional - Formatting mode.
- **sort** ('alpha' | 'none') - Optional - Sorting strategy.
```

--------------------------------

### EnvSitter.matchKeyBulk

Source: https://context7.com/boxpositron/envsitter/llms.txt

Tests one matcher against multiple keys.

```APIDOC
## EnvSitter.matchKeyBulk

### Description
Tests one matcher against multiple keys.

### Parameters
#### Request Body
- **keys** (array) - Required - List of keys to test.
- **matcher** (object) - Required - The operation object defining the check.
```

--------------------------------

### Match a candidate value against all keys in a dotenv file

Source: https://context7.com/boxpositron/envsitter/llms.txt

Use the `--all-keys` flag with the `match` command to test a single candidate value against every key present in the specified dotenv file. This is useful for broad validation scenarios.

```bash
# Match against all keys
node -e "process.stdout.write('sk-secret123')" \
  | envsitter match --file .env --all-keys --candidate-stdin --json
```

--------------------------------

### EnvSitter.matchCandidateAll

Source: https://context7.com/boxpositron/envsitter/llms.txt

Tests one candidate against all keys in the source.

```APIDOC
## EnvSitter.matchCandidateAll

### Description
Tests one candidate against all keys in the source.

### Parameters
#### Request Body
- **candidate** (string) - Required - The value to search for across all keys.
```

--------------------------------

### Add New Keys

Source: https://context7.com/boxpositron/envsitter/llms.txt

Adds a new key-value pair to the file, failing if the key already exists.

```bash
# Via argument
envsitter add --file .env --key NEW_API_KEY --value "sk-newkey123" --write

# Via stdin (recommended)
node -e "process.stdout.write('sk-newkey123')" \
  | envsitter add --file .env --key NEW_API_KEY --value-stdin --write

# Output:
# { "file": ".env", "key": "NEW_API_KEY", "willWrite": true, "wrote": true, "hasChanges": true, "issues": [], "plan": { "key": "NEW_API_KEY", "action": "added", "line": 15 } }
```

--------------------------------

### Format and Organize .env Files

Source: https://context7.com/boxpositron/envsitter/llms.txt

Use `formatEnvFile` to sort and organize your .env file. It can sort alphabetically and organize variables into sections, while preserving comments. The `write: true` option applies changes directly to the file.

```typescript
import { formatEnvFile, type FormatEnvFileResult } from 'envsitter';

const result: FormatEnvFileResult = await formatEnvFile({
  file: '.env',
  mode: 'sections', // 'sections' | 'global'
  sort: 'alpha',    // 'alpha' | 'none'
  write: true
});

console.log(`Changed: ${result.hasChanges}, Wrote: ${result.wrote}`);
```

--------------------------------

### copyEnvFileKeys

Source: https://context7.com/boxpositron/envsitter/llms.txt

Copies keys between environment files with support for conflict resolution, filtering, and renaming.

```APIDOC
## copyEnvFileKeys

### Description
Copies keys from one file to another.

### Parameters
#### Request Body
- **from** (string) - Required - Source file path.
- **to** (string) - Required - Destination file path.
- **keys** (Array<string>) - Optional - Specific keys to copy.
- **onConflict** ('error' | 'skip' | 'overwrite') - Optional - Conflict resolution strategy.
- **write** (boolean) - Optional - Whether to write changes to disk.
```

--------------------------------

### Copy keys between env files

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Transfer keys between environment files with options for conflict resolution, renaming, and dry-runs.

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

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

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

--------------------------------

### addEnvFileKey

Source: https://context7.com/boxpositron/envsitter/llms.txt

Adds a new key-value pair to an environment file. Fails if the key already exists.

```APIDOC
## addEnvFileKey

### Description
Appends a new key to the file.

### Parameters
#### Request Body
- **file** (string) - Required - Path to the file.
- **key** (string) - Required - Key name.
- **value** (string) - Required - Key value.
```

--------------------------------

### Library Matching API

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Methods for matching candidates against environment keys using various operators.

```APIDOC
## Library Matching API

### Description
Provides functionality to match secret candidates against stored environment keys, supporting bulk operations and custom match operators.

### Methods
- `matchCandidate(key, candidate)`: Matches a single candidate against a key.
- `matchKey(key, matcher)`: Matches a key against a specific matcher object.
- `matchCandidateBulk(keys, candidate)`: Tests one candidate against multiple keys.
- `matchKeyBulk(keys, matcher)`: Tests one matcher against multiple keys.
- `matchCandidatesByKey(map)`: Matches multiple candidates against their respective keys.
```

--------------------------------

### Scan Environment Files

Source: https://context7.com/boxpositron/envsitter/llms.txt

Scans files for specific keys using regex patterns and detection rules.

```bash
envsitter scan --file .env --keys-regex "/(TOKEN|JWT)/" --detect jwt
```

--------------------------------

### Copy Keys Between Files

Source: https://context7.com/boxpositron/envsitter/llms.txt

Copies keys between environment files with support for conflict handling, regex filtering, and key renaming.

```bash
# Dry-run (preview changes)
envsitter copy --from .env.production --to .env.staging --keys API_URL,REDIS_URL --json
# Output shows plan without modifying files

# Apply changes with overwrite on conflict
envsitter copy --from .env.production --to .env.staging \
  --keys API_URL,REDIS_URL \
  --on-conflict overwrite \
  --write --json

# Copy with regex filter
envsitter copy --from .env.production --to .env.staging \
  --include-regex "/^DB_/" \
  --exclude-regex "/_PASSWORD$/" \
  --write

# Rename keys while copying
envsitter copy --from .env.production --to .env.staging \
  --keys DATABASE_URL \
  --rename DATABASE_URL=STAGING_DATABASE_URL \
  --write
```

--------------------------------

### Load environment variables from external command

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Initializes EnvSitter by executing an external command that outputs dotenv-formatted data.

```ts
import { EnvSitter } from 'envsitter';

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

--------------------------------

### EnvSitter.matchCandidatesByKey

Source: https://context7.com/boxpositron/envsitter/llms.txt

Tests multiple candidates against their respective keys in one call.

```APIDOC
## EnvSitter.matchCandidatesByKey

### Description
Tests multiple candidates against their respective keys in one call.

### Parameters
#### Request Body
- **candidates** (object) - Required - A map of keys to their candidate values.
```

--------------------------------

### EnvSitter.matchCandidateBulk

Source: https://context7.com/boxpositron/envsitter/llms.txt

Tests one candidate against multiple keys.

```APIDOC
## EnvSitter.matchCandidateBulk

### Description
Tests one candidate against multiple keys.

### Parameters
#### Request Body
- **keys** (array) - Required - List of keys to test.
- **candidate** (string) - Required - The value to compare against the stored secrets.
```

--------------------------------

### Set Key (Create or Update)

Source: https://context7.com/boxpositron/envsitter/llms.txt

Creates or updates a key-value pair idempotently in a dotenv file.

```APIDOC
## SET KEY (CREATE OR UPDATE)

Creates or updates a key-value pair idempotently.

### Method
POST

### Endpoint
`/set`

### Parameters
#### Query Parameters
- **file** (string) - Required - Path to the dotenv file.
- **key** (string) - Required - The key to set.
- **value** (string) - Optional - The value for the key (use `--value-stdin` for stdin).
- **value-stdin** (boolean) - Optional - Read value from stdin.
- **write** (boolean) - Optional - If true, apply changes to the file.

### Request Example (Via Argument)
```bash
envsitter set --file .env --key API_KEY --value "updated-value" --write
```

### Request Example (Via Stdin)
```bash
node -e "process.stdout.write('updated-value')" \
  | envsitter set --file .env --key API_KEY --value-stdin --write
```

### Request Example (Special Characters)
```bash
envsitter set --file .env --key MESSAGE --value "Hello World # with hash" --write
```

### Response
#### Success Response (200)
- **file** (string) - The processed file path.
- **key** (string) - The set key.
- **value** (string) - The set value.
- **willWrite** (boolean) - Indicates if changes were intended to be written.
- **wrote** (boolean) - Indicates if changes were actually written.
- **hasChanges** (boolean) - Indicates if there were any changes.
- **issues** (array) - List of issues found.

#### Response Example
```json
{
  "file": ".env",
  "key": "API_KEY",
  "value": "updated-value",
  "willWrite": true,
  "wrote": true,
  "hasChanges": true,
  "issues": []
}
```
```

--------------------------------

### Format/Reorder Env Files

Source: https://context7.com/boxpositron/envsitter/llms.txt

Sorts and organizes env files, preserving comments, with options for sorting mode and order.

```APIDOC
## FORMAT/REORDER ENV FILES

Sorts and organizes env files while preserving comments.

### Method
POST

### Endpoint
`/format` or `/reorder`

### Parameters
#### Query Parameters
- **file** (string) - Required - Path to the dotenv file.
- **mode** (string) - Optional - Sorting mode (`sections` or `global`). Defaults to `sections`.
- **sort** (string) - Optional - Sorting order (`alpha` for alphabetical). Defaults to `alpha`.
- **write** (boolean) - Optional - If true, apply changes to the file.
- **json** (boolean) - Optional - Output in JSON format.

### Request Example (Dry-run)
```bash
envsitter format --file .env --json
```

### Request Example (Apply Changes)
```bash
envsitter format --file .env --mode sections --sort alpha --write
```

### Response
#### Success Response (200)
- **file** (string) - The processed file path.
- **mode** (string) - The sorting mode used.
- **sort** (string) - The sorting order used.
- **willWrite** (boolean) - Indicates if changes were intended to be written.
- **wrote** (boolean) - Indicates if changes were actually written.
- **hasChanges** (boolean) - Indicates if there were any changes.
- **issues** (array) - List of issues found during formatting.

#### Response Example
```json
{
  "file": ".env",
  "mode": "sections",
  "sort": "alpha",
  "willWrite": true,
  "wrote": true,
  "hasChanges": true,
  "issues": []
}
```
```

--------------------------------

### Copy Keys Between Files

Source: https://context7.com/boxpositron/envsitter/llms.txt

Copies keys from one env file to another, with options for conflict handling, filtering, and renaming.

```APIDOC
## COPY KEYS BETWEEN FILES

Copies keys from one env file to another with conflict handling.

### Method
POST

### Endpoint
`/copy`

### Parameters
#### Query Parameters
- **from** (string) - Required - Source dotenv file path.
- **to** (string) - Required - Destination dotenv file path.
- **keys** (string) - Optional - Comma-separated list of keys to copy.
- **include-regex** (string) - Optional - Regex to include keys.
- **exclude-regex** (string) - Optional - Regex to exclude keys.
- **rename** (string) - Optional - Comma-separated list of key renames (e.g., `OLD_KEY=NEW_KEY`).
- **on-conflict** (string) - Optional - Conflict resolution strategy (`overwrite`, `skip`).
- **write** (boolean) - Optional - If true, apply changes to the destination file.
- **json** (boolean) - Optional - Output in JSON format.

### Request Example (Dry-run)
```bash
envsitter copy --from .env.production --to .env.staging --keys API_URL,REDIS_URL --json
```

### Request Example (Apply Changes)
```bash
envsitter copy --from .env.production --to .env.staging \
  --keys API_URL,REDIS_URL \
  --on-conflict overwrite \
  --write --json
```

### Request Example (Regex Filter & Rename)
```bash
envsitter copy --from .env.production --to .env.staging \
  --include-regex "/^DB_/" \
  --exclude-regex "/_PASSWORD$/" \
  --rename DATABASE_URL=STAGING_DATABASE_URL \
  --write
```

### Response
#### Success Response (200)
- **file** (string) - The destination file.
- **keys** (array) - List of keys processed.
- **wrote** (boolean) - Indicates if changes were written to the file.
- **hasChanges** (boolean) - Indicates if there were any changes.
- **plan** (object) - Details of the changes made.

#### Response Example
```json
{
  "file": ".env.staging",
  "keys": ["API_URL", "REDIS_URL"],
  "wrote": true,
  "hasChanges": true,
  "plan": [
    { "key": "API_URL", "action": "copied", "line": 5 },
    { "key": "REDIS_URL", "action": "copied", "line": 10 }
  ]
}
```
```

--------------------------------

### Match one candidate against all keys

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Check a single candidate value against every key present in the file.

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

--------------------------------

### Initialize EnvSitter from External Command

Source: https://context7.com/boxpositron/envsitter/llms.txt

Creates an EnvSitter instance from an external command that outputs in dotenv format.

```typescript
import { EnvSitter } from 'envsitter';

// Load secrets from external provider
const es = EnvSitter.fromExternalCommand('vault', ['kv', 'get', '-format=dotenv', 'secret/myapp']);
const keys = await es.listKeys();

// Or from AWS Secrets Manager with custom script
const awsEs = EnvSitter.fromExternalCommand('./scripts/fetch-secrets.sh', ['--env', 'production']);
```

--------------------------------

### Set Key Values

Source: https://context7.com/boxpositron/envsitter/llms.txt

Creates or updates a key-value pair idempotently, with automatic quoting for special characters.

```bash
# Via argument
envsitter set --file .env --key API_KEY --value "updated-value" --write

# Via stdin (recommended)
node -e "process.stdout.write('updated-value')" \
  | envsitter set --file .env --key API_KEY --value-stdin --write

# Values with special characters are auto-quoted
envsitter set --file .env --key MESSAGE --value "Hello World # with hash" --write
# Result in file: MESSAGE="Hello World # with hash"
```

--------------------------------

### Add a new key

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Insert a new key-value pair, failing if the key already exists.

```bash
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
```

--------------------------------

### Match a candidate against a key

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Verify a candidate secret against an existing key using stdin to avoid shell history exposure.

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

--------------------------------

### Add New Key

Source: https://context7.com/boxpositron/envsitter/llms.txt

Adds a new key-value pair to a dotenv file. Fails if the key already exists.

```APIDOC
## ADD NEW KEY

Adds a new key-value pair. Fails if key already exists.

### Method
POST

### Endpoint
`/add`

### Parameters
#### Query Parameters
- **file** (string) - Required - Path to the dotenv file.
- **key** (string) - Required - The new key to add.
- **value** (string) - Optional - The value for the new key (use `--value-stdin` for stdin).
- **value-stdin** (boolean) - Optional - Read value from stdin.
- **write** (boolean) - Optional - If true, apply changes to the file.

### Request Example (Via Argument)
```bash
envsitter add --file .env --key NEW_API_KEY --value "sk-newkey123" --write
```

### Request Example (Via Stdin)
```bash
node -e "process.stdout.write('sk-newkey123')" \
  | envsitter add --file .env --key NEW_API_KEY --value-stdin --write
```

### Response
#### Success Response (200)
- **file** (string) - The processed file path.
- **key** (string) - The added key.
- **willWrite** (boolean) - Indicates if changes were intended to be written.
- **wrote** (boolean) - Indicates if changes were actually written.
- **hasChanges** (boolean) - Indicates if there were any changes.
- **issues** (array) - List of issues found.
- **plan** (object) - Details of the addition.
  - **key** (string) - The added key.
  - **action** (string) - Action performed (`added`).
  - **line** (integer) - Line number where the key was added.

#### Response Example
```json
{
  "file": ".env",
  "key": "NEW_API_KEY",
  "willWrite": true,
  "wrote": true,
  "hasChanges": true,
  "issues": [],
  "plan": {
    "key": "NEW_API_KEY",
    "action": "added",
    "line": 15
  }
}
```
```

--------------------------------

### Annotate keys with comments

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Add inline comments to specific keys within an environment file.

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

--------------------------------

### Match environment variables using operators

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Perform conditional checks on environment variables using various operators like prefix, regex, or existence checks.

```bash
# 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
```

--------------------------------

### CLI Output Contracts

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Standardized JSON output structures for EnvSitter CLI commands.

```APIDOC
## CLI JSON Output Contracts

### Description
Defines the JSON response structures for various CLI operations. All values are treated as sensitive.

### Exit Codes
- 0: Match found
- 1: No match
- 2: Error/Usage

### Response Examples
- `keys --json`: { "keys": string[] }
- `fingerprint`: { "key": string, "algorithm": "hmac-sha256", "fingerprint": string, "length": number, "pepperSource": "env"|"file", "pepperFilePath"?: string }
- `scan --json`: { "findings": Array<{ "key": string, "detections": Array<"jwt"|"url"|"base64"> }> }
- `validate --json`: { "ok": boolean, "issues": Array<{ "line": number, "column": number, "message": string }> }
```

--------------------------------

### setEnvFileKey

Source: https://context7.com/boxpositron/envsitter/llms.txt

Creates or updates a key-value pair in an environment file idempotently.

```APIDOC
## setEnvFileKey

### Description
Sets a key value, updating if it exists or adding if it does not.

### Parameters
#### Request Body
- **file** (string) - Required - Path to the file.
- **key** (string) - Required - Key name.
- **value** (string) - Required - Key value.
```

--------------------------------

### Copy Keys Between .env Files

Source: https://context7.com/boxpositron/envsitter/llms.txt

Utilize `copyEnvFileKeys` to transfer environment variables between files. It supports conflict resolution strategies like 'overwrite', 'skip', or 'error', and can filter keys using regex or specific names.

```typescript
import { copyEnvFileKeys, type CopyEnvFilesResult } from 'envsitter';

const result: CopyEnvFilesResult = await copyEnvFileKeys({
  from: '.env.production',
  to: '.env.staging',
  keys: ['API_URL', 'REDIS_URL'],
  onConflict: 'overwrite', // 'error' | 'skip' | 'overwrite'
  write: true
});

console.log(`Copied: ${result.wrote}`);
console.log('Plan:', result.plan);
// [
//   { fromKey: 'API_URL', toKey: 'API_URL', action: 'copy', fromLine: 5, toLine: 12 },
//   { fromKey: 'REDIS_URL', toKey: 'REDIS_URL', action: 'overwrite', fromLine: 8, toLine: 15 }
// ]

// Copy with regex filters and renaming
const filtered = await copyEnvFileKeys({
  from: '.env.production',
  to: '.env.staging',
  include: /^DB_/, 
  exclude: /_PASSWORD$/,
  rename: 'DB_HOST=STAGING_DB_HOST,DB_PORT=STAGING_DB_PORT',
  write: true
});
```

--------------------------------

### EnvSitter.matchKey

Source: https://context7.com/boxpositron/envsitter/llms.txt

Matches a key against various matchers for boolean checks.

```APIDOC
## EnvSitter.matchKey

### Description
Matches a key against various matchers for boolean checks such as existence, emptiness, prefix/suffix matching, regex, or type checks.

### Parameters
#### Request Body
- **key** (string) - Required - The environment variable key to check.
- **matcher** (object) - Required - The operation object defining the check (e.g., { op: 'exists' }, { op: 'partial_match_prefix', prefix: 'sk-' }).
```

--------------------------------

### Match candidates-by-key

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Perform bulk assignment checks using a JSON mapping of keys to candidate values.

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

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

--------------------------------

### Validate dotenv syntax

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Check the integrity and syntax of a .env file.

```bash
envsitter validate --file .env
envsitter validate --file .env --json
```

--------------------------------

### EnvSitter Library API

Source: https://context7.com/boxpositron/envsitter/llms.txt

Programmatic interface for managing .env files using the EnvSitter Node.js library.

```APIDOC
## LIBRARY API

### EnvSitter.fromDotenvFile

Creates an EnvSitter instance from a local dotenv file.

```typescript
import { EnvSitter } from 'envsitter';

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

// List all keys
const keys = await es.listKeys();
console.log(keys); // ['API_KEY', 'DATABASE_URL', 'OPENAI_API_KEY']

// List keys with filter
const filteredKeys = await es.listKeys({ filter: /API/ });
console.log(filteredKeys); // ['API_KEY', 'OPENAI_API_KEY']
```

### EnvSitter.fromExternalCommand

Creates an EnvSitter instance from an external command that outputs dotenv format.

```typescript
import { EnvSitter } from 'envsitter';

// Load secrets from external provider
const es = EnvSitter.fromExternalCommand('vault', ['kv', 'get', '-format=dotenv', 'secret/myapp']);
const keys = await es.listKeys();

// Or from AWS Secrets Manager with custom script
const awsEs = EnvSitter.fromExternalCommand('./scripts/fetch-secrets.sh', ['--env', 'production']);
```
```

--------------------------------

### Perform boolean and pattern checks on environment variable values

Source: https://context7.com/boxpositron/envsitter/llms.txt

Use the `match` command with the `--op` flag to perform various checks on environment variable values without exposing them. Supported operations include checking for existence, emptiness, prefix/suffix matches, regex matches, and type checks (number, boolean, string).

```bash
# Check if key exists
envsitter match --file .env --key OPENAI_API_KEY --op exists --json
# Output: { "key": "OPENAI_API_KEY", "op": "exists", "match": true }
```

```bash
# Check if value is empty
envsitter match --file .env --key OPTIONAL_KEY --op is_empty --json
# Output: { "key": "OPTIONAL_KEY", "op": "is_empty", "match": false }
```

```bash
# Prefix match (e.g., verify OpenAI key format)
node -e "process.stdout.write('sk-')" \
  | envsitter match --file .env --key OPENAI_API_KEY --op partial_match_prefix --candidate-stdin --json
# Output: { "key": "OPENAI_API_KEY", "op": "partial_match_prefix", "match": true }
```

```bash
# Suffix match
node -e "process.stdout.write('.com')" \
  | envsitter match --file .env --key API_URL --op partial_match_suffix --candidate-stdin --json
```

```bash
# Regex match
node -e "process.stdout.write('/^sk-[a-zA-Z0-9]+$/')" \
  | envsitter match --file .env --key OPENAI_API_KEY --op partial_match_regex --candidate-stdin --json
```

```bash
# Type checks (no candidate required)
envsitter match --file .env --key PORT --op is_number --json
envsitter match --file .env --key DEBUG --op is_boolean --json
envsitter match --file .env --key API_KEY --op is_string --json
```

--------------------------------

### Securely match a candidate value against a stored secret

Source: https://context7.com/boxpositron/envsitter/llms.txt

The `match` command securely compares a candidate value against a secret stored in a dotenv file. It supports matching via stdin (recommended for security) or directly via an argument. The output indicates if a match occurred, and the exit code reflects the result.

```bash
# Match via stdin (recommended - avoids shell history)
node -e "process.stdout.write('sk-abc123...')" \
  | envsitter match --file .env --key OPENAI_API_KEY --candidate-stdin --json
# Output: { "key": "OPENAI_API_KEY", "match": true }
# Exit code: 0 (match), 1 (no match), 2 (error)
```

```bash
# Match via argument (less secure)
envsitter match --file .env --key OPENAI_API_KEY --candidate "sk-abc123..." --json
```

--------------------------------

### Match one candidate against multiple keys

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Check a single candidate value against a comma-separated list of keys.

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

--------------------------------

### annotateEnvFile

Source: https://context7.com/boxpositron/envsitter/llms.txt

Adds or updates comments associated with specific keys in an environment file.

```APIDOC
## annotateEnvFile

### Description
Adds documentation comments to a key.

### Parameters
#### Request Body
- **file** (string) - Required - Path to the file.
- **key** (string) - Required - The key to annotate.
- **comment** (string) - Required - The comment text.
```

--------------------------------

### Match a candidate value against multiple specified keys

Source: https://context7.com/boxpositron/envsitter/llms.txt

Compare a single candidate value against a comma-separated list of keys using the `--keys` flag. This is useful for verifying a value against a subset of secrets. The output details which of the specified keys matched.

```bash
# Match against specific keys
node -e "process.stdout.write('sk-secret123')" \
  | envsitter match --file .env --keys OPENAI_API_KEY,ANTHROPIC_API_KEY --candidate-stdin --json
# Output:
# {
#   "matches": [
#     { "key": "OPENAI_API_KEY", "match": true },
#     { "key": "ANTHROPIC_API_KEY", "match": false }
#   ]
# }
```

--------------------------------

### Annotate .env File Keys with Comments

Source: https://context7.com/boxpositron/envsitter/llms.txt

Add or update comments for specific environment variables using `annotateEnvFile`. This function allows you to provide descriptive comments that will be associated with a given key in the .env file.

```typescript
import { annotateEnvFile, type AnnotateEnvFileResult } from 'envsitter';

const result: AnnotateEnvFileResult = await annotateEnvFile({
  file: '.env',
  key: 'DATABASE_URL',
  comment: 'Production read replica - do not use for writes',
  write: true
});

console.log(result.plan);
// { key: 'DATABASE_URL', action: 'inserted', line: 5 }
```

--------------------------------

### Library File Operations

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

TypeScript methods for performing CRUD and formatting operations on environment files.

```APIDOC
## Library File Operations

### Description
Functions for programmatically managing .env files including validation, copying, formatting, and key manipulation.

### Methods
- `validateEnvFile(file: string)`: Validates the structure of an env file.
- `copyEnvFileKeys(options)`: Copies keys between files.
- `annotateEnvFile(options)`: Adds comments to specific keys.
- `formatEnvFile(options)`: Formats and sorts env file content.
- `addEnvFileKey(options)`: Adds a new key.
- `setEnvFileKey(options)`: Creates or updates a key.
- `unsetEnvFileKey(options)`: Unsets a key.
- `deleteEnvFileKeys(options)`: Deletes multiple keys.
```

--------------------------------

### Generate HMAC-SHA-256 fingerprint for a key's value

Source: https://context7.com/boxpositron/envsitter/llms.txt

The `fingerprint` command generates a deterministic HMAC-SHA-256 hash for a specific environment variable's value using a local pepper. It outputs the key, algorithm, fingerprint, length, and pepper source details.

```bash
envsitter fingerprint --file .env --key OPENAI_API_KEY
# Output:
# {
#   "key": "OPENAI_API_KEY",
#   "algorithm": "hmac-sha256",
#   "fingerprint": "a1b2c3d4e5f6...",
#   "length": 51,
#   "pepperSource": "file",
#   "pepperFilePath": ".envsitter/pepper"
# }
```

--------------------------------

### Match Key Against Various Matchers

Source: https://context7.com/boxpositron/envsitter/llms.txt

Utilize `matchKey` for boolean checks on keys using various matchers like 'exists', 'is_empty', 'partial_match_prefix', 'partial_match_suffix', 'partial_match_regex', 'is_number', 'is_boolean', 'is_string', and 'is_equal'.

```typescript
import { EnvSitter, type EnvSitterMatcher } from 'envsitter';

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

// Check if key exists
const exists = await es.matchKey('OPENAI_API_KEY', { op: 'exists' });

// Check if value is empty
const isEmpty = await es.matchKey('OPTIONAL_KEY', { op: 'is_empty' });

// Prefix match
const hasPrefix = await es.matchKey('OPENAI_API_KEY', { op: 'partial_match_prefix', prefix: 'sk-' });

// Suffix match
const hasSuffix = await es.matchKey('API_URL', { op: 'partial_match_suffix', suffix: '.com' });

// Regex match
const matchesRegex = await es.matchKey('OPENAI_API_KEY', {
  op: 'partial_match_regex',
  regex: /^sk-[a-zA-Z0-9]+$/
});

// Type checks
const isNumber = await es.matchKey('PORT', { op: 'is_number' });
const isBoolean = await es.matchKey('DEBUG', { op: 'is_boolean' });
const isString = await es.matchKey('API_KEY', { op: 'is_string' });

// Equality match (same as matchCandidate)
const isEqual = await es.matchKey('API_KEY', { op: 'is_equal', candidate: 'secret-value' });
```

--------------------------------

### Bulk Test Candidate Against Multiple Keys

Source: https://context7.com/boxpositron/envsitter/llms.txt

Use `matchCandidateBulk` to efficiently test a single candidate value against an array of keys. Returns an array indicating which keys matched.

```typescript
import { EnvSitter, type EnvSitterKeyMatch } from 'envsitter';

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

const results: EnvSitterKeyMatch[] = await es.matchCandidateBulk(
  ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'COHERE_API_KEY'],
  'sk-shared-secret'
);

console.log(results);
// [
//   { key: 'OPENAI_API_KEY', match: true },
//   { key: 'ANTHROPIC_API_KEY', match: false },
//   { key: 'COHERE_API_KEY', match: false }
// ]
```

--------------------------------

### Test Candidate Against All Keys

Source: https://context7.com/boxpositron/envsitter/llms.txt

Use `matchCandidateAll` to test a single candidate value against all keys loaded in EnvSitter. Returns results for each key, allowing identification of where the secret might exist.

```typescript
import { EnvSitter } from 'envsitter';

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

// Find which key(s) contain a specific secret
const results = await es.matchCandidateAll('leaked-secret-value');
const matchingKeys = results.filter(r => r.match).map(r => r.key);
console.log('Secret found in:', matchingKeys);
```

--------------------------------

### Add a New Key-Value Pair to .env File

Source: https://context7.com/boxpositron/envsitter/llms.txt

Use `addEnvFileKey` to insert a new key-value pair into your .env file. This function will fail if the key already exists, ensuring that you do not accidentally overwrite existing variables.

```typescript
import { addEnvFileKey, type AddEnvFileKeyResult } from 'envsitter';

const result: AddEnvFileKeyResult = await addEnvFileKey({
  file: '.env',
  key: 'NEW_API_KEY',
  value: 'sk-newkey123',
  write: true
});

if (result.plan.action === 'key_exists') {
  console.error('Key already exists');
} else {
  console.log(`Added at line ${result.plan.line}`);
}
```

--------------------------------

### Scan Dotenv File

Source: https://context7.com/boxpositron/envsitter/llms.txt

Scans a dotenv file for specific keys or patterns and detects certain types of values.

```APIDOC
## SCAN DOTENV FILE

Scans a dotenv file for specific keys or patterns and detects certain types of values.

### Method
GET

### Endpoint
`/scan`

### Parameters
#### Query Parameters
- **file** (string) - Required - Path to the dotenv file.
- **keys-regex** (string) - Optional - Regex to filter keys to scan.
- **detect** (string) - Optional - Type of detection (e.g., `jwt`, `url`).

### Request Example
```bash
envsitter scan --file .env --keys-regex "/(TOKEN|JWT)/" --detect jwt
```

### Response
#### Success Response (200)
- **key** (string) - The key found.
- **detections** (array) - List of detected types for the key.

#### Response Example
```json
{
  "key": "API_ENDPOINT",
  "detections": ["url"]
}
```
```

--------------------------------

### EnvSitter File Operations via Library

Source: https://github.com/boxpositron/envsitter/blob/main/README.md

Perform file operations on .env files using dedicated functions. Ensure to set the 'write' option to true to persist changes.

```typescript
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 });
```

--------------------------------

### Delete Keys

Source: https://context7.com/boxpositron/envsitter/llms.txt

Removes keys entirely from the environment file.

```bash
# 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:
# {
#   "file": ".env",
#   "keys": ["OLD_KEY", "UNUSED_KEY"],
#   "wrote": true,
#   "hasChanges": true,
#   "plan": [
#     { "key": "OLD_KEY", "action": "deleted", "line": 5 },
#     { "key": "UNUSED_KEY", "action": "deleted", "line": 12 }
#   ]
# }
```