@ctroenv/cli

@ctroenv/cli

CLI tooling for CtroEnv — validate, generate, check, document, and scaffold environment variables.

Installation

npm install @ctroenv/cli

Or use directly with npx:

npx @ctroenv/cli validate

Commands

Command	Description
validate	Validate environment variables against your schema
generate	Generate .env.example from your schema
check	CI-friendly diff of .env vs schema (exit code 1 on issues)
docs	Generate Markdown or JSON documentation from your schema
init	Scaffold a ctroenv.config file

validate

Validate current environment against schema.

ctroenv validate [--source <path>] [--watch] [--json]

Flag	Default	Description
--source <path>	Config sources.default or process.env	Path to .env file
--watch	false	Watch files and re-validate on change
--json	false	Output JSON instead of formatted text

generate

Generate .env.example from schema.

ctroenv generate [--output <path>] [--no-comments]

Flag	Default	Description
--output <path>	".env.example"	Output file path
--no-comments	false	Minimal output without comments

check

CI-friendly diff of .env vs schema.

ctroenv check [--source <path>] [--strict] [--warn-unknown] [--json]

Flag	Default	Description
--source <path>	Config sources.default or ".env"	Path to .env file
--strict	false	Also validate values against schema
--warn-unknown	false	Warn about keys in source not in schema (with "did you mean?" suggestions)
--json	false	Output JSON instead of formatted text

Exit code 0 on success, 1 on missing/unused keys or validation errors.

docs

Generate documentation from schema.

ctroenv docs [--output <path>] [--format <format>]

Flag	Default	Description
--output <path>	"ENVIRONMENT.md"	Output file path
--format <format>	"markdown"	Output format: markdown or json

init

Scaffold a configuration file.

ctroenv init [--ts | --js | --json] [--minimal]

Flag	Default	Description
--ts	Default format	Generate TypeScript config
--js	—	Generate JavaScript config
--json	—	Generate JSON config
--minimal	false	Generate minimal config (schema path only)

Configuration

Create ctroenv.config.ts in your project root:

import { defineConfig } from "@ctroenv/cli"

export default defineConfig({
  schema: "./src/env.ts",
  sources: {
    default: ".env",
    production: ".production.env",
  },
  output: {
    example: ".env.example",
    docs: "ENVIRONMENT.md",
  },
  secrets: {
    mask: ["EXTRA_KEY"],
    maskWith: "***",
  },
})

Config Options

Option	Type	Default	Description
schema	string	"src/env.ts"	Path to schema file
sources.default	string	".env"	Default env file path
sources.production	string	—	Production env file path
output.example	string	".env.example"	Output path for generate
output.docs	string	"ENVIRONMENT.md"	Output path for docs
secrets.mask	string[]	[]	Additional keys to mask
secrets.maskWith	string	"***"	Mask string override

Types:

import { defineConfig } from "@ctroenv/cli"
import type { CliConfig, Format, ResolvedConfig } from "@ctroenv/cli"

const config: CliConfig = defineConfig({ schema: "./env.ts" })

Documentation

Full documentation at ctroenv.vercel.app

License

MIT