npm package: @m1z23r/flags
Description: CLI tool for flags.dimitrije.dev encrypted environment variable sharing
Author: m1z23r
Latest version: 1.0.1

# @m1z23r/flags

CLI tool for flags.dimitrije.dev encrypted environment variable sharing.

## Installation

```bash
npm install -g @m1z23r/flags
```

## Prerequisites

1. An account on flags.dimitrije.dev
2. An SSH key (ed25519 or RSA) for encryption/decryption

## Usage

### Login

Authenticate with your Flags account:

```bash
# Browser-based login (recommended)
flags login

# This will:
# 1. Open your browser to authorize the CLI
# 2. Prompt you to add your SSH public key
# 3. Complete authentication automatically
```

Options:
- `--ssh` - Use SSH key-based authentication (requires pre-registered key)
- `--no-browser` - Don't open browser automatically, just show the URL
- `-p, --port <port>` - Specify callback server port (default: 9876)
- `-u, --api-url <url>` - Custom API URL (default: https://flags.dimitrije.dev)
- `-e, --email <email>` - Email address (for SSH auth only)

### SSH Keys

Manage your SSH keys:

```bash
# List your SSH keys
flags keys list
flags keys ls

# Add a new SSH key
flags keys add                          # Interactive mode
flags keys add ~/.ssh/id_ed25519.pub    # From file

# Remove an SSH key
flags keys remove
flags keys rm
```

### Initialize Project

Set up the project configuration:

```bash
flags init
```

This creates a `.flagsrc.json` file in your project root.

### Push Encrypted Env

Push an encrypted `.env` file to the server:

```bash
# Push with a key name
flags push production .env

# Push a specific file
flags push staging .env.staging

# Force overwrite without confirmation
flags push production -f
```

### Pull Encrypted Env

Pull and decrypt an env file from the server:

```bash
# Pull by key name
flags pull production

# Pull a specific version
flags pull production 2

# Pull to a different output path
flags pull production -o .env.local

# Overwrite without prompting
flags pull production -f
```

### List Available Envs

List all encrypted env files for the project:

```bash
# List all secrets
flags list
flags ls

# List versions of a specific secret
flags list production --versions
flags ls production -v
```

### Delete a Secret

Delete an encrypted env:

```bash
flags delete
```

### Logout

Clear stored credentials:

```bash
flags logout
```

## How It Works

1. **Authentication**: Browser-based OAuth with your Flags account, or SSH key challenge-response
2. **Encryption**: Files are encrypted with AES-256-GCM
3. **Key Wrapping**: The symmetric key is encrypted for each team member's SSH public key
4. **Server Storage**: The server only stores encrypted data - it never sees the plaintext

## Configuration Files

### `~/.config/flags-cli/credentials.json`

Stores your authentication tokens (encrypted).

### `.flagsrc.json`

Project-level configuration:

```json
{
  "teamId": "uuid",
  "appId": "uuid"
}
```

## Security

- The server never sees your plaintext env files
- Encryption uses AES-256-GCM with a random 256-bit key
- Each push generates a new symmetric key
- The symmetric key is encrypted for each team member's SSH public key
- Only team members with registered SSH keys can decrypt the files