---
title: @envlock/cli Reference
description: Command reference for the envlock CLI — validate, document, diff, and inspect environment schemas.
url: https://pr-1-7cfcfe393d12.thally.app/envlock-cli
---

# @envlock/cli Reference

Command reference for the envlock CLI — validate, document, diff, and inspect environment schemas.

Command reference for `@envlock/cli` v0.1.0. Binary name: `envlock`.

## Commands

| Command | Usage | Description |
| --- | --- | --- |
| `check` | `envlock check [flags]` | Validate environment against schema |
| `example` | `envlock example [flags]` | Render `.env.example` |
| `diff` | `envlock diff [flags]` | Show differences between schema and env file |
| `inspect` | `envlock inspect [flags]` | Describe schema variables |
| `init` | `envlock init` | Create starter config file |

Global flags: `envlock --help`, `envlock --version`.

---

## Flags by command

### check

| Flag | Description |
| --- | --- |
| `--schema <path>` | Path to config file |
| `--env-file <path>` | Path to `.env` file to validate |
| `--merge-process-env` | Layer env file over `process.env` (file values win) |
| `--strict` | Report unknown variables (env-file sources only) |
| `--json` | Output results as JSON |
| `--help` | Show help |

> **Note:**
  The `--strict` flag only applies when validating an `--env-file` source.
  When validating `process.env` directly, strict mode is ignored and a note is
  printed.

### example

| Flag | Description |
| --- | --- |
| `--schema <path>` | Path to config file |
| `--out <path>` | Output file path (default `.env.example`) |
| `--check` | Compare rendered text to `--out` path; exit 1 on drift |
| `--help` | Show help |

### diff

| Flag | Description |
| --- | --- |
| `--schema <path>` | Path to config file |
| `--env-file <path>` | Path to `.env` file (default `.env`) |
| `--json` | Output results as JSON |
| `--help` | Show help |

Diff is always strict. The `--env-file` flag defaults to `.env`.

### inspect

| Flag | Description |
| --- | --- |
| `--schema <path>` | Path to config file |
| `--json` | Output results as JSON |
| `--help` | Show help |

### init

| Flag | Description |
| --- | --- |
| `--help` | Show help |

Creates a starter `envlock.config.mjs` in the current directory. Exits with
code 1 if a config file already exists.

---

## Config file discovery

The CLI looks for config files in the following order in the current working
directory:

1. `envlock.config.mjs`
2. `envlock.config.js`

Override with `--schema <path>` on any command.

The config file must export a schema using either a default export or a named
`schema` export:

```js
// Default export
export default defineEnv({ /* ... */ });

// Or named export
export const schema = defineEnv({ /* ... */ });
```

---

## Exit codes

| Code | Name | Meaning |
| --- | --- | --- |
| 0 | `ok` | Passed / no drift |
| 1 | `failure` | Validation failed, drift detected, or `init` found existing config |
| 2 | `usage` | Unknown command or flag, missing flag value, stray argument |
| 3 | `config` | Config not found, import failed, no schema exported, env file unreadable |

---

## Programmatic API

The CLI is also available as a testable function.

### runCli

```ts
function runCli(
  argv: readonly string[],
  io: CliIo,
): Promise<ExitCode>;
```

Runs the entire CLI with the given arguments and I/O bindings. `argv` is
`process.argv.slice(2)`.

### EXIT_CODES

```ts
const EXIT_CODES: {
  ok: 0;
  failure: 1;
  usage: 2;
  config: 3;
};
```

### CliIo

```ts
interface CliIo {
  readonly stdout: (chunk: string) => void;
  readonly stderr: (chunk: string) => void;
  readonly cwd: string;
  readonly env: Readonly<Record<string, string | undefined>>;
}
```

### parseArgs

```ts
function parseArgs(
  argv: readonly string[],
  specs: Readonly<Record<string, FlagSpec>>,
): ParsedArgs | ArgsError;
```

### Config loading

- `resolveConfigPath(cwd, explicit?)` — find the config file in a directory
- `importSchema(path)` — dynamic-import a config file and extract the schema
- `loadSchema(cwd, explicit?)` — resolve and import in one step

### STARTER_CONFIG

```ts
const STARTER_CONFIG: string;
```

String constant containing the starter config file content written by
`envlock init`.

---

## Programmatic usage example

```ts
import { runCli, EXIT_CODES, type CliIo } from "@envlock/cli";

const io: CliIo = {
  stdout: (chunk) => process.stdout.write(chunk),
  stderr: (chunk) => process.stderr.write(chunk),
  cwd: process.cwd(),
  env: process.env,
};

const code = await runCli(["check", "--env-file", ".env"], io);
process.exitCode = code;
```