CLI Configuration

Configure the CLI behavior with a config file in your project root.

Supported Formats

Format	File Name	Type Safety
TypeScript	ctroenv.config.ts	Full autocomplete with defineConfig()
JavaScript	ctroenv.config.js	JSDoc hints via @type
JSON	ctroenv.json	Simple, no imports needed

The CLI auto-detects which file to load. If multiple exist, the first found in the order above is used.

TypeScript (recommended)

import { defineConfig } from "@ctroenv/cli"

export default defineConfig({
  // ... configuration
})

defineConfig() provides autocomplete and type checking. At runtime it simply returns the config object.

JSON

{
  "schema": "./src/env.ts",
  "sources": {
    "default": ".env"
  },
  "output": {
    "example": ".env.example",
    "docs": "ENVIRONMENT.md"
  },
  "secrets": {
    "mask": ["JWT_SECRET"],
    "maskWith": "***"
  }
}

JSON configs are parsed natively — no transformation or imports are needed. Use ctroenv init --json to generate one.

Configuration Options

interface CliConfig {
  schema?: string
  sources?: Record<string, string>
  output?: {
    example?: string
    docs?: string
  }
  secrets?: {
    mask?: string[]
    maskWith?: string
  }
}

Option	Type	Default	Description
schema	string	"./src/env.ts"	Path to the schema file
sources.default	string	".env"	Path to the default .env file
output.example	string	".env.example"	Output path for generate
output.docs	string	"ENVIRONMENT.md"	Output path for docs command
secrets.mask	string[]	[]	Keys to mask in output
secrets.maskWith	string	"***"	Mask string

ResolvedConfig

At runtime, defaults are applied to produce a ResolvedConfig:

interface ResolvedConfig {
  schema: string
  sources: Record<string, string>
  output: {
    example: string
    docs: string
  }
  secrets: {
    mask: string[]
    maskWith: string
  }
}

Example

import { defineConfig } from "@ctroenv/cli"

export default defineConfig({
  schema: "./src/env.ts",
  sources: {
    default: ".env",
  },
  output: {
    example: ".env.example",
    docs: "docs/environment-variables.md",
  },
  secrets: {
    mask: ["JWT_SECRET", "API_KEY", "PASSWORD"],
    maskWith: "••••••••",
  },
})