serun

Secure environment variable runner.

Installation

npm install -g @vietor/serun

Quick Start

1. Set the safe key environment variable:

export SERUN_SAFEKEY="your-safe-key"

2. Configure environment variables:

serun-cfg set API_KEY abc123

3. Run commands with encrypted environment variables:

serun npm run dev

Commands

serun

Execute commands with encrypted environment variables loaded from ~/.serun/global and optionally a channel-specific file.

Usage: serun [options] <command> [args...]

Options:
  -h, --help           Show help message
  -V, --version        Show version number
  -c, --channel <name> Load additional env from ~/.serun/<name>

Description:
  Load encrypted environment variables from ~/.serun/global and optionally
  from a channel-specific file, then execute the specified command.

Examples:
  serun npm install           Run with global env
  serun -c dev npm run        Run with global + ~/.serun/dev
  serun --channel prod node   Run with global + ~/.serun/prod

serun-cfg

Configure encrypted environment variables for use with serun.

Usage: serun-cfg [options] <action> [args...]

Options:
  -h, --help           Show help message
  -V, --version        Show version number
  -c, --channel <name> Target config file ~/.serun/<name> (default: global)

Actions:
  import <file>        Import environment variables from a file (e.g., .env)
  set <key> <value>    Set an environment variable
  del <key1> [key2...] Delete one or more environment variables
  delete               Alias for del
  show                 Show all saved environment variables from the config
  list                 List all channel names (ignores -c option)

Description:
  Configure encrypted environment variables for serun.
  Variables are stored in ~/.serun/global or channel-specific files.

Examples:
  serun-cfg set API_KEY abc123        Set global variable
  serun-cfg -c dev set DB_URL pg://   Set variable in dev channel
  serun-cfg -c prod show              Show variables in prod channel
  serun-cfg del API_KEY DB_URL        Delete multiple variables
  serun-cfg import ./project.env      Import from .env file

Variable References

Environment variables can reference other variables using ${VAR} syntax:

# Set base URL
serun-cfg set BASE_URL https://api.example.com

# Reference BASE_URL in another variable
serun-cfg set API_ENDPOINT "${BASE_URL}/v1"
# API_ENDPOINT resolves to: https://api.example.com/v1

# References can use system environment variables
serun-cfg set LOG_DIR "${HOME}/logs"

Notes:

• References are resolved when serun loads the environment
• If a referenced variable is not found, it resolves to an empty string
• Multiple references in a single value are all resolved

Environment Variables

| Variable | Description | |----------|-------------| | SERUN_SAFEKEY | Safe key for encrypting/decrypting environment variables |

Storage

Environment variables are stored encrypted in:

• ~/.serun/global - Default global configuration
• ~/.serun/<channel> - Channel-specific configurations

Security

• All environment variables are encrypted using AES-256-CBC
• The safe key (SERUN_SAFEKEY) is never stored on disk
• Each channel provides isolated environment variable sets