npm package: @motive_sx/envm
Description: Secure environment variable manager - store and sync .env files across machines
Latest version: 1.1.5

# envm

Secure environment variable manager - store and sync .env files across machines.

## Features

- **Encrypted storage**: All env files are encrypted with AES-256-GCM
- **Multi-environment support**: Manage dev, staging, prod, and custom environments
- **Remote sync**: Pull and push env files between server and local machine
- **Setup wizard**: Interactive setup for both server and client modes
- **Automatic SSH tunneling**: Built-in SSH tunnel management for secure remote access
- **Interactive mode**: Commands prompt for inputs when called without arguments
- **System service**: Auto-install as systemd (Linux) or launchd (macOS) service

## Installation

```bash
npm install -g @motive_sx/envm
```

## Quick Start

### Setup Wizard (Recommended)

The easiest way to get started is with the interactive setup wizard:

```bash
envm setup
```

This will guide you through:
- **Server mode**: Generate encryption key, configure port, install as system service
- **Client mode**: Configure SSH connection for automatic tunneling

### Server Setup (Manual)

1. Start the envm server:

```bash
envm server start --port 3737
```

2. Create a project and add variables:

```bash
envm init myapp
envm set myapp dev DB_HOST=localhost DB_PORT=5432
envm set myapp prod DB_HOST=prod.example.com DB_PORT=5432
```

### Client Setup (Manual)

1. Configure the CLI:

```bash
envm config set server http://localhost:3737
```

2. Set up SSH tunnel (if not using automatic tunneling):

```bash
ssh -L 3737:localhost:3737 your-server
```

3. Pull env files:

```bash
cd your-project
envm pull myapp dev           # Saves to .env
envm pull myapp prod -o .env.production
```

4. Push local changes:

```bash
envm push myapp dev           # Pushes .env
envm push myapp staging -f .env.staging
```

## Interactive Mode

Commands can be run without arguments for an interactive experience:

```bash
# Interactive project creation
envm init
? Project name: myapp

# Interactive variable setting
envm set
? Select project: myapp
? Select environment: dev
? Enter KEY=value (empty to finish): DATABASE_URL=postgres://localhost/myapp
? Enter KEY=value (empty to finish): REDIS_URL=redis://localhost:6379
? Enter KEY=value (empty to finish):
Set 2 variables in myapp/dev

# Interactive variable viewing
envm get
? Select project: myapp
? Select environment: dev
? Variable key (leave empty for all):
```

## Commands

### Setup & Configuration

| Command                        | Description                        |
| ------------------------------ | ---------------------------------- |
| `envm setup`                   | Interactive setup wizard           |
| `envm config set server <url>` | Configure remote server URL        |
| `envm config get [key]`        | View configuration                 |

### Server Commands

| Command                                 | Description                     |
| --------------------------------------- | ------------------------------- |
| `envm server start [--port 3737]`       | Start the envm server           |
| `envm init [project]`                   | Create a new project            |
| `envm set [project] [env] [KEY=value]`  | Set environment variables       |
| `envm get [project] [env] [key]`        | Get environment variables       |
| `envm edit <project> [env]`             | Edit env in your default editor |
| `envm list`                             | List all projects               |
| `envm envs <project>`                   | List environments for a project |

### Client Commands

| Command                        | Description                        |
| ------------------------------ | ---------------------------------- |
| `envm pull <project> [env]`    | Pull env from remote to local .env |
| `envm push <project> [env]`    | Push local .env to remote          |
| `envm list -r`                 | List projects from remote          |
| `envm envs <project> -r`       | List environments from remote      |

### Options

- `[env]` defaults to `dev` if not specified
- `--output, -o <file>` - Specify output file for pull (default: `.env`)
- `--file, -f <file>` - Specify input file for push (default: `.env`)
- `--force` - Overwrite existing files without prompting
- `--create` - Create project on push if it doesn't exist
- `--remote, -r` - Force remote server operation

## SSH Tunnel (Automatic)

When configured via `envm setup` in client mode, SSH tunnels are managed automatically:

```bash
envm setup
? How will you use envm? Client - Pull/push from remote server
? SSH host: myserver.com
? SSH username: deploy
? SSH port: 22
? Authentication method: SSH key
? Path to private key: ~/.ssh/id_rsa
Testing connection... Connected!
Setup complete!

# Now pull/push commands auto-connect via SSH
envm pull myapp dev
Establishing SSH tunnel... Connected.
Pulled 5 variables to .env
```

Supported authentication methods:
- **SSH key**: Path to private key (recommended)
- **Password**: Prompted at runtime, never stored

## System Service

During server setup, envm can install itself as a system service:

**Linux (systemd):**
```bash
envm setup
? Install as system service? Yes
Installing systemd service...
Service installed and started.

# Manage with systemctl
sudo systemctl status envm
sudo systemctl restart envm
```

**macOS (launchd):**
```bash
envm setup
? Install as system service? Yes
Installing launchd service...
Service installed and started.

# Manage with launchctl
launchctl list | grep envm
```

## Data Storage

### Server

All data is stored in `~/.envm/`:

```
~/.envm/
├── master.key          # Auto-generated encryption key (chmod 600)
├── config.json         # Configuration (chmod 600)
├── projects.json       # Project metadata
└── projects/
    └── myapp/
        ├── dev.enc     # Encrypted env files
        ├── staging.enc
        └── prod.enc
```

### Client

Client configuration is stored in `~/.envm/config.json`:

```json
{
  "server": "http://localhost:3737",
  "mode": "client",
  "ssh": {
    "host": "myserver.com",
    "port": 22,
    "username": "deploy",
    "authMethod": "key",
    "privateKeyPath": "~/.ssh/id_rsa",
    "localPort": 3737,
    "remotePort": 3737
  },
  "setupComplete": true
}
```

## Security

- **Encryption**: All env files are encrypted with AES-256-GCM
- **Master key**: Auto-generated on first run, stored with 0600 permissions
- **Config protection**: Config file stored with 0600 permissions
- **Localhost only**: Server binds to 127.0.0.1 by default
- **SSH tunneling**: Secure remote access via encrypted SSH connection
- **No password storage**: SSH passwords are prompted at runtime, never saved
- **No auth required**: Security is provided by SSH tunnel

## Development

```bash
# Install dependencies
npm install

# Run in development
npm run dev -- <command>

# Build
npm run build

# Run built version
npm start -- <command>
```

## License

MIT