> ## Documentation Index
> Fetch the complete documentation index at: https://encryptd.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# secure-env CLI Reference: encrypt and decrypt Commands

> Full reference for the secure-env CLI: encrypt and decrypt subcommands, argument defaults, environment variables, exit codes, and usage without npx.

The `secure-env` binary ships with `@vernonthedev/encryptd` and provides two subcommands: `encrypt` converts a plaintext `.env` file into an encrypted `.env.enc` JSON file, and `decrypt` reverses that process, printing the plaintext to stdout. Both commands require the passphrase to be available in the `ENV_PASSPHRASE` environment variable before they run.

***

## `secure-env encrypt`

The `encrypt` subcommand reads the plaintext input file, encrypts it with AES-256-GCM using the key derived from `ENV_PASSPHRASE`, and writes the resulting [`EnvPayload`](/reference/env-payload) JSON to the output file. A success message is printed to stdout on completion.

### Syntax

```sh theme={null}
ENV_PASSPHRASE="<passphrase>" npx secure-env encrypt [inputFile] [outputFile]
```

### Arguments

<ParamField path="inputFile" default=".env" type="string">
  Path to the plaintext `.env` file to encrypt. Resolved relative to the current working directory. The file must exist or the command exits with an error.
</ParamField>

<ParamField path="outputFile" default=".env.enc" type="string">
  Path where the encrypted JSON file will be written. The file is created or overwritten. Resolved relative to the current working directory.
</ParamField>

### Environment variables

| Variable         | Required | Description                                                                                                                                               |
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ENV_PASSPHRASE` | Yes      | Passphrase used to derive the AES-256-GCM encryption key via PBKDF2-HMAC-SHA256. The command exits immediately with an error if this variable is not set. |

### Examples

<CodeGroup>
  ```sh Default paths (.env → .env.enc) theme={null}
  ENV_PASSPHRASE="my-secret-passphrase" npx secure-env encrypt
  # Encrypted .env -> .env.enc
  ```

  ```sh Custom input and output paths theme={null}
  ENV_PASSPHRASE="s3cr3t" npx secure-env encrypt .env.production .env.production.enc
  # Encrypted .env.production -> .env.production.enc
  ```

  ```sh Using an npm script theme={null}
  # In package.json:
  # "scripts": { "encrypt": "secure-env encrypt" }

  ENV_PASSPHRASE="s3cr3t" npm run encrypt
  ```
</CodeGroup>

***

## `secure-env decrypt`

The `decrypt` subcommand reads the encrypted JSON file produced by `secure-env encrypt`, decrypts it using `ENV_PASSPHRASE`, and prints the recovered plaintext to **stdout**. Nothing is written to disk.

### Syntax

```sh theme={null}
ENV_PASSPHRASE="<passphrase>" npx secure-env decrypt [inputFile]
```

### Arguments

<ParamField path="inputFile" default=".env.enc" type="string">
  Path to the encrypted `.env.enc` file to decrypt. Must be valid JSON matching the [`EnvPayload`](/reference/env-payload) schema.
</ParamField>

### Environment variables

| Variable         | Required | Description                                               |
| ---------------- | -------- | --------------------------------------------------------- |
| `ENV_PASSPHRASE` | Yes      | Must exactly match the passphrase used during encryption. |

### Examples

<CodeGroup>
  ```sh Default path (.env.enc) theme={null}
  ENV_PASSPHRASE="my-secret-passphrase" npx secure-env decrypt
  # DATABASE_URL=postgres://localhost/mydb
  # API_KEY=abc123
  ```

  ```sh Custom input path theme={null}
  ENV_PASSPHRASE="s3cr3t" npx secure-env decrypt .env.production.enc
  ```

  ```sh Pipe decrypted output to a file (emergency recovery) theme={null}
  ENV_PASSPHRASE="s3cr3t" npx secure-env decrypt > .env.recovered
  ```
</CodeGroup>

<Note>
  The `decrypt` command prints decrypted content to stdout only it does **not** write a file or mutate `process.env`. If you need the env vars loaded into a running Node.js process, use the [`config()`](/reference/api) library function instead.
</Note>

***

## Exit behavior

The CLI exits with a non-zero status code in the following situations:

| Condition                                            | Error message                                              |
| ---------------------------------------------------- | ---------------------------------------------------------- |
| `ENV_PASSPHRASE` not set                             | `[SrcIndex] Set ENV_PASSPHRASE env var.`                   |
| Input file does not exist                            | `[SrcIndex] <inputFile> not found.`                        |
| Decryption fails (wrong passphrase or tampered file) | `[RustLib] Decryption failed. Wrong key or tampered file.` |
| Encrypted file is not valid JSON                     | Standard `JSON.parse` error                                |

<Warning>
  If you receive `[RustLib] Decryption failed`, check that `ENV_PASSPHRASE` is set to exactly the same value that was used when the file was encrypted including case and any special characters. The error is intentionally non-specific: the CLI cannot distinguish between a wrong passphrase and a tampered file.
</Warning>

***

## Usage without `npx`

If you install `@vernonthedev/encryptd` as a local dev dependency, the `secure-env` binary is available inside `node_modules/.bin/`. You can invoke it directly or through your package manager's exec command.

<CodeGroup>
  ```sh pnpm exec theme={null}
  ENV_PASSPHRASE="s3cr3t" pnpm exec secure-env encrypt
  ```

  ```sh node_modules/.bin/ theme={null}
  ENV_PASSPHRASE="s3cr3t" ./node_modules/.bin/secure-env encrypt
  ```
</CodeGroup>

You can also wire `encrypt` and `decrypt` up as npm scripts to avoid typing the full binary path every time:

```json package.json theme={null}
{
  "scripts": {
    "encrypt": "secure-env encrypt",
    "decrypt": "secure-env decrypt"
  }
}
```