@m1z23r/flags

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

Installation

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:

# 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:

# 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:

flags init

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

Push Encrypted Env

Push an encrypted .env file to the server:

# 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:

# 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:

# 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:

flags delete

Logout

Clear stored credentials:

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:

{
  "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