dotkit
Version:
A powerful CLI toolkit for managing environment variables and .env files.
230 lines (157 loc) • 5.67 kB
Markdown
# dotkit
A powerful CLI toolkit for managing environment variables and dotenv files.
## Features
- **Sync** environment variables from template files (like `.env.example`) to your `.env` files
- **Generate** random hex values for secrets and authentication tokens
- **Smart filtering** with `--only` to sync specific variables
- **Custom length** generation with `--length` parameter
- **Force overwrite** existing values with `-f/--force` when generating
- **Safe by default** - won't overwrite existing values unless forced
- **Dry-run support** to preview exact changes before applying them
- **Bootstrap mode** to create new `.env` files from templates
- **Value quoting** - new values are automatically quoted for consistency
## Installation
```bash
npm install -g dotkit
```
## Usage
### Sync Command
Sync environment variables from a template file to your `.env` file:
```bash
# Basic sync from .env.example to .env
dotkit sync
# Sync with custom paths
dotkit sync --source .env.local.example --target .env.local
# Sync only specific variables
dotkit sync --only API_KEY DB_URL
# Preview changes with exact values
dotkit sync --dry-run
```
### Secret Command
Generate random hex values for environment variables:
```bash
# Generate random values for multiple variables
dotkit secret AUTH_SECRET JWT_SECRET SESSION_KEY
# Generate with custom length (in bytes)
dotkit secret AUTH_SECRET --length 16
# Generate to a specific file
dotkit secret AUTH_SECRET --target .env.local
# Preview what would be generated with sample values
dotkit secret AUTH_SECRET --dry-run
# Force overwrite existing values
dotkit secret AUTH_SECRET --force
# Use short flags
dotkit secret AUTH_SECRET -t .env.local -l 16 -f
# Deprecated aliases (use secret instead)
dotkit generate AUTH_SECRET --length 16
```
## Options
### Sync Command Options
- `-t, --target <path>` - Target .env file (default: `.env`)
- `-s, --source <path>` - Source template file (default: `.env.example`)
- `--only <variables...>` - Only sync these specific variables
- `--dry-run` - Show what would be copied without making changes
### Secret Command Options
- `-t, --target <path>` - Target .env file (default: `.env`)
- `-l, --length <bytes>` - Length in bytes for generated values (default: `32`)
- `-f, --force` - Overwrite existing values (default: skip existing)
- `--dry-run` - Show what would be generated without making changes
## Examples
### Basic Workflow
1. **Create a template file** (`.env.example`):
```env
API_KEY=your_api_key_here
DB_URL=postgres://localhost:5432/myapp
AUTH_SECRET=replace_with_random_value
JWT_SECRET=replace_with_random_value
```
2. **Bootstrap your .env file**:
```bash
# First sync template values (preserves original format)
dotkit sync
# Then generate secrets separately
dotkit secret AUTH_SECRET JWT_SECRET
```
This creates `.env` with:
```env
API_KEY=your_api_key_here
DB_URL=postgres://localhost:5432/myapp
AUTH_SECRET=replace_with_random_value
JWT_SECRET=replace_with_random_value
AUTH_SECRET="a1b2c3d4e5f6789..."
JWT_SECRET="9f8e7d6c5b4a321..."
```
### Dry-Run Examples
Preview exact changes before applying:
```bash
# See what sync would copy
dotkit sync --dry-run
# Output:
# [DRY RUN] Would copy these variables:
# API_KEY="your_api_key_here"
# DB_URL="postgres://localhost:5432/myapp"
# See what secret would create
dotkit secret AUTH_SECRET --dry-run
# Output:
# [DRY RUN] Would generate values for:
# AUTH_SECRET="d805b72dcf114e7f05fce56ede679cdbd71655de2066582ce21e53e9f0ad84b2"
```
### Custom Length Generation
```bash
# Generate 16-byte (32 hex characters) values
dotkit secret SHORT_SECRET --length 16
# Generate 64-byte (128 hex characters) values
dotkit secret LONG_SECRET --length 64
# Default is 32 bytes (64 hex characters)
dotkit secret DEFAULT_SECRET
```
### Adding New Variables
Add new variables to your `.env.example`:
```env
API_KEY=your_api_key_here
DB_URL=postgres://localhost:5432/myapp
NEW_FEATURE_FLAG=false
```
Sync only the new variable:
```bash
dotkit sync --only NEW_FEATURE_FLAG
# Creates: NEW_FEATURE_FLAG="false"
```
### Force Overwriting Existing Values
By default, `dotkit secret` skips variables that already exist:
```bash
# .env already contains AUTH_SECRET=old_value
dotkit secret AUTH_SECRET NEW_SECRET
# Result: Skips AUTH_SECRET, only generates NEW_SECRET
# Output: "Already exist (skipped): AUTH_SECRET"
```
Use `--force` to overwrite existing values:
```bash
dotkit secret AUTH_SECRET NEW_SECRET --force
# Result: Overwrites AUTH_SECRET with new random value, generates NEW_SECRET
```
## How It Works
### Bootstrap Mode
When your `.env` file doesn't exist, `dotkit sync` creates it from your template file, preserving the original formatting. Use `--only` to filter which variables to include.
### Sync Mode
When your `.env` file exists, `dotkit sync` appends missing variables from the template with quoted values. Existing variables are never modified.
### Generate Mode
`dotkit secret` creates cryptographically secure random hex values. It works independently of templates and can create new files or append to existing ones.
By default, it **skips variables that already exist** in the target file. Use `-f` or `--force` to overwrite existing values.
### Random Value Generation
Generated values are hexadecimal strings created using Node.js `crypto.randomBytes()` for cryptographic security. Default length is 32 bytes (64 hex characters).
## Development
```bash
# Install dependencies
bun install
# Run tests
bun test
# Build
bun build
# Run all checks (format, lint, typecheck)
bun check
# Auto-fix issues
bun fix
```
## License
MIT