Runenv CLI

Securely inject environment variables at runtime without .env files on disk.

Installation

npm install -g runenv-cli

Current release: [email protected]. See CHANGELOG.md for release notes.

Quick Start

# 1. Link current directory (.runenv.json — allows omitting -p, -e)
runenv link -p my-project -e development

# 2. Login
runenv login

# 3. Check current auth + link status
runenv status

# 4. Open the optional read-only dashboard
runenv ui --refresh 5000

# 5. Inject secrets and run a command
runenv run -- npm start

# 6. Download as .env file
runenv pull

# 7. Upload .env file
runenv push

💡 With .runenv.json present, you can omit -p and -e options.

The default CLI stays script-friendly. runenv ui and --ui flows are opt-in and never replace plain or JSON output automatically.

Commands

runenv init

Create a .runenv.json configuration file in the current folder. Other commands can then omit -p and -e options. When the workspace includes framework markers such as next.config.*, vite.config.*, or pubspec.yaml, RunEnv also auto-detects and stores the matching env-file preset, including a first-class Flutter preset.

runenv init -p my-project                  # defaults to development
runenv init -p my-project -e production    # specify environment

runenv login

Login to the Runenv server. Running runenv login without options launches an interactive menu where you select your auth method with arrow keys:

? Select login method:
❯ Email / Password
  GitHub
  Google
  Apple

runenv login                                       # interactive selector
runenv login --method password                     # email + password directly
runenv login --method github                       # GitHub OAuth
runenv login --method google                       # Google OAuth
runenv login --method apple                        # Apple OAuth
runenv login -e [email protected]                   # specify email

OAuth methods open your browser for authentication and return the token to CLI automatically.

On macOS, login tokens are stored in Keychain. On Windows, RunEnv stores them in a user-scoped DPAPI blob. On Linux, RunEnv uses secret-tool when available. If no secure store exists, plaintext token storage is blocked by default; only set RUNENV_ALLOW_PLAINTEXT_TOKEN_FALLBACK=1 if you explicitly accept that tradeoff.

| Option | Description | | ----------------------- | ---------------------------------------------------- | | -e, --email <email> | Email address (interactive prompt if omitted) | | -m, --method <method> | Auth method: password, github, google, apple | | -s, --server <url> | Runenv server URL (default: https://runenv.dev) |

runenv logout

Delete stored authentication token.

runenv run

Fetch secrets from Runenv, inject as environment variables, and execute a command. Variables are automatically discarded when the process exits (Zero-Disk-first).

If a .env.local file exists, it's automatically applied as local overrides.

runenv run -p my-project -e production -- npm start
runenv run -p my-project --override -- node server.js     # override existing env vars
runenv run --token rtk_abc123 -p my-project -- npm start  # service token

# With .runenv.json:
runenv run -- npm start

| Option | Description | Default | | ---------------------- | ------------------------------------------------------- | -------------- | | -p, --project <name> | Project name | .runenv.json | | -e, --env <name> | Environment name | development | | --override | Override existing env vars | — | | --no-resolve | Disable ${REF} reference resolution | — | | --token <token> | Service token (for CI/CD) | — | | --dotenv | Write secrets to .env file (for Flutter/React Native) | — | | --dotenv-path <path> | Custom .env path (default: .env) | — |

File-backed secrets (*_FILE)

Keys ending in *_FILE are resolved to real file paths before your command starts.

• Store Base64 content in Runenv if you want to keep the original file bytes encoded.
• Paste raw PEM or other multiline text directly in the dashboard if the file is text-based.
• Keep an existing local file path if you only want Runenv to pass it through unchanged on your machine.

runenv run materializes text or Base64-backed values as temporary 0600 files and injects the path into your process. This is useful for TLS certificates, private keys, kubeconfigs, SSH material, and binary bundles such as .p12 or .jks.

Offline cache

Offline fallback is opt-in. Set RUNENV_ENABLE_OFFLINE_CACHE=1 if you want a temporary local fallback during network outages. Cache entries are encrypted before they touch disk and expire after 15 minutes by default. Override the TTL with RUNENV_OFFLINE_CACHE_TTL_SECONDS=300.

Runtime controls

• RUNENV_API_TIMEOUT_MS=15000: override the default 10s API timeout
• RUNENV_DISABLE_UPDATE_CHECK=1: disable npm version checks entirely

Update checks are already disabled by default in CI and other non-interactive sessions.

runenv pull

Download secrets from Runenv and save as a .env file.

runenv pull -p my-project -e development              # save to .env
runenv pull -p my-project -e production -o .env.prod   # custom path
runenv pull -p my-project -y                           # overwrite without confirmation

Common profile outputs:

• .env or .env.production: shared team secrets
• .env.local or .env.production.local: your personal local overrides
• .env.example: key-only template for onboarding and CI

| Option | Description | Default | | ---------------------- | ------------------------------ | -------------- | | -p, --project <name> | Project name | .runenv.json | | -e, --env <name> | Environment name | development | | -o, --output <file> | Output file path | .env | | --token <token> | Service token | — | | -y, --yes | Overwrite without confirmation | — |

runenv push

Upload local .env file contents to the Runenv server. Existing keys are updated, new keys are created.

For safety, runenv push prints only key names before upload and never echoes values back to the terminal.

runenv push -p my-project -e development              # upload .env
runenv push -p my-project -e staging -f .env.staging   # specify file
runenv push -p my-project -y                           # upload without confirmation

| Option | Description | Default | | ---------------------- | --------------------------- | -------------- | | -p, --project <name> | Project name | .runenv.json | | -e, --env <name> | Environment name | development | | -f, --file <path> | .env file path | .env | | --token <token> | Service token | — | | -y, --yes | Upload without confirmation | — |

runenv list

List secret keys for a project.

runenv list -p my-project -e production
runenv list -p my-project --show-values    # show values (masked)

runenv export

Export secrets in various formats.

runenv export -p my-project -f dotenv    # KEY=VALUE (stdout)
runenv export -p my-project -f json      # JSON format
runenv export -p my-project -f yaml      # YAML format
runenv export -p my-project -f shell     # export KEY="VALUE" format
runenv export -o .env.prod               # save to file

runenv diff

Compare local .env file with server secrets. Quickly see which keys are added, deleted, or changed.

runenv diff -p my-project -e production
runenv diff -p my-project --keys-only      # compare keys only
runenv diff -p my-project --json           # machine-readable output
runenv diff -p my-project --fail-on-diff   # exit 1 when drift exists
runenv diff -p my-project -f .env.local    # compare inferred override profile
runenv diff -p my-project --cascade        # compare merged preset env stack
runenv diff -p my-project --all-envs --cascade --json

runenv validate

Validate a local env file against the project blueprint. It reports required-key drift, duplicate keys, malformed lines, empty required values, and, in --strict mode, unexpected local-only keys. Blueprint rules can now also enforce value type, format, regex, and enum constraints.

runenv validate -p my-project
runenv validate -p my-project -f .env.production.local
runenv validate -p my-project --strict --json
runenv validate -p my-project --cascade --preset vite
runenv validate -p my-project --all-envs --cascade

runenv status

Show authentication state, token storage mode, server URL, and the linked .runenv.json project context in one view. status also surfaces invalid project-link files and verifies that the linked environment still exists remotely when credentials are available.

runenv status
runenv status --ui
runenv status --json

runenv ui / runenv dashboard

Open the optional dashboard that combines authentication status, linked project health, doctor findings, watch-mode launch hints, and runnable next actions in one place.

In an interactive terminal, runenv ui opens a navigable dashboard. Use 1-5 or left/right to switch views, r to refresh, and q to quit. A persistent footer legend shows the active shortcuts. The actions view can launch safe commands directly, asks for confirmation before mutating actions such as runenv doctor --fix, shows structured result summaries for link, list, and doctor-fix flows, keeps command help inside the dashboard, and maintains a recent action history. In non-interactive contexts, it prints a single snapshot and exits.

runenv ui
runenv ui --view doctor
runenv ui --refresh 5000
runenv dashboard --refresh 3000

You can also jump into the same dashboard from focused commands:

runenv status --ui
runenv doctor --ui

Inside the actions view:

• up/down: select an action
• Enter: run the selected action
• y / n: confirm or cancel guarded actions
• x: clear the recent action history
• link, list, and doctor-fix flows render structured result cards in the dashboard
• help stays inside the dashboard and generic inline actions keep the latest output summary

runenv link

Create or update .runenv.json for the current directory. If you are logged in and only one project is accessible, runenv link can auto-select it. If --preset is omitted, RunEnv auto-detects the workspace preset from framework files when possible.

runenv link -p my-project -e production
runenv link --preset vite
runenv link --preset flutter
runenv link --force

For very large monorepos, you can tune nested auto-detection with:

• RUNENV_PRESET_SCAN_DEPTH=<n> to scan deeper than the default depth of 3
• RUNENV_PRESET_SCAN_IGNORE=dir1,dir2 to skip specific directory names while scanning

runenv env

List project environments or switch the linked environment for the current directory. If exactly one RunEnv-managed local env file already exists, env switch refreshes it automatically; if several exist, .env is preferred and otherwise you can force a specific path with --dotenv [path]. Already-running shells, apps, and debug sessions are not reloaded automatically.

runenv env list
runenv env switch staging
runenv env switch staging --dotenv
runenv env switch production --project my-project

runenv sync-example

Auto-generate/update .env.example from server secret keys. Commit to git so team members know which variables are needed.

runenv sync-example -p my-project
runenv sync-example -p my-project --format type          # type-inferred format
runenv sync-example -p my-project --with-descriptions    # include description comments

runenv scan

Scan the project directory for hardcoded secrets in source code. Useful for CI pipelines to prevent secret exposure.

Detects: AWS Access Key, Stripe Key, GitHub Token, Slack Token, Google API Key, DB Connection String

runenv scan                    # scan current directory
runenv scan -d ./src           # scan specific directory

💡 Returns exit code 1 if hardcoded secrets are found. Use in CI pipelines.

runenv generate-types

Auto-generate TypeScript type definitions (env.d.ts) from secret keys.

runenv generate-types -p my-project                    # namespace format
runenv generate-types -p my-project --format vite      # Vite ImportMeta
runenv generate-types -p my-project --format nextjs    # Next.js format

runenv watch

Real-time bidirectional sync between local .env file and Runenv server.

runenv watch -p my-project -e development
runenv watch -p my-project -e development --ui

runenv watch --ui adds an opt-in dashboard with recent events plus a persistent footer legend:

• p: pause/resume automatic sync
• r: pull from the server now
• u: push the current local file now
• c: clear the event list
• q: quit watch mode

runenv whoami

Display current login status and user information.

runenv doctor

Diagnose CLI configuration, server connectivity, authentication status, token storage mode, offline cache readiness, and update-check behavior.

runenv doctor
runenv doctor --ui
runenv doctor --json
runenv doctor --fix
runenv doctor --fix --dry-run

runenv doctor --fix can:

• enable tracked .husky hooks
• install shell completion
• repair invalid or missing .runenv.json when the project can be inferred
• add recommended .gitignore env ignore rules
• migrate leftover plaintext tokens into the secure store when possible

Use runenv doctor --fix --dry-run to preview the same automatic fixes without changing files.

runenv audit

View project audit logs.

runenv audit -p my-project -n 20           # last 20 entries
runenv audit -p my-project --action SECRET_UPDATE

runenv env list

List all environments in a project with secret counts.

runenv env list -p my-project

runenv snapshot

Manage secret version snapshots (coming soon).

runenv snapshot list -p my-project
runenv snapshot create -p my-project -e production -m "pre-deploy"
runenv snapshot restore -p my-project <snapshot-id>

runenv completion

Install shell auto-completion. The generated completion scripts dynamically complete project names and environment names from your current Runenv session, keep a short-lived cache for responsiveness, allow bounded stale fallback when the server is unavailable, and prune expired cache files automatically.

runenv completion                           # auto-detect shell, print script
runenv completion -s bash                   # bash script
runenv completion -s fish                   # fish script
runenv completion --install                 # auto-install to your shell rc

runenv upgrade

Self-update the globally installed CLI through npm, pnpm, or Homebrew. If Runenv is installed inside a project workspace, runenv upgrade updates that workspace dependency instead of using a global package command. When running via npx, the command prints the latest-run guidance instead of attempting a persistent upgrade.

runenv upgrade
runenv upgrade --manager pnpm
runenv upgrade --manager brew

runenv dotenv

Write secrets to a .env file for frameworks that need it (Flutter, React Native). Unlike runenv run --dotenv, this creates a persistent file for IDE F5 debugging.

runenv dotenv -p my-project -e development              # write .env
runenv dotenv -p my-project -o .env.staging             # custom output path
runenv dotenv --clean                                    # delete .env file
runenv dotenv --setup -p my-project -e development      # auto-setup VS Code F5 debug
runenv env switch staging --dotenv                       # switch link + refresh .env

--setup creates:

• .vscode/tasks.json — preLaunchTask (writes .env before F5)
• .vscode/launch.json — postDebugTask (deletes .env after stop)

| Option | Description | Default | | ---------------------- | ------------------------------------------- | -------------- | | -p, --project <name> | Project name | .runenv.json | | -e, --env <name> | Environment name | development | | -o, --output <path> | Output path for .env file | .env | | --token <token> | Service token | — | | --setup | Auto-configure VS Code preLaunchTask for F5 | — | | --clean | Delete the .env file | — |

🛡️ .env is auto-added to .gitignore if missing.

runenv config

Manage CLI settings.

runenv config set locale ko                # set language
runenv config set apiUrl http://localhost:5820   # for local development
runenv config get apiUrl
runenv config list
runenv config sync                         # sync team config files from server
runenv config sync --dry-run               # preview changes without writing
runenv config sync --yes                   # auto-accept all updates

runenv help

Show categorized help for all commands, or detailed help for a specific command.

runenv help                                # show all commands by category
runenv help run                            # detailed help for 'run' command
runenv help config                         # detailed help for 'config'

CI/CD Integration

Use service tokens to authenticate without interactive login.

GitHub Actions

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g runenv-cli
      - run: runenv run --token ${{ secrets.RUNENV_TOKEN }} -p my-project -e production -- npm start

Docker

RUN npm install -g runenv-cli
CMD ["runenv", "run", "--token", "$RUNENV_TOKEN", "-p", "my-project", "--", "node", "server.js"]

Configuration Files

| File | Location | Description | | -------------- | ----------------------- | ----------------------------------------- | | config.json | ~/.runenv/config.json | Server URL, email, locale, expiry metadata | | .runenv.json | Project root | Default project/environment settings |

Real-device validation steps for macOS Keychain, Linux libsecret, and Windows DPAPI are documented in docs/secure-store-validation.md.

License

MIT