Quickstart

Run these commands from your application’s directory. This walkthrough uses the default local ingredient; no cloud setup is required.

Initialize your repository

ramenv init

Initialization creates a workspace, raw local keys, and a signed vault containing empty development and production environments. It adds .env and .ramenv.keys entries to .gitignore.

File	What to do with it
.ramenv.workspace.toml	Commit the workspace configuration.
.ramenv.vault.toml	Review plaintext values, then commit the vault.
.ramenv.keys	Keep private and back up securely. Never commit it.

Ignore entries do not untrack files already in Git. Check the repository before committing.

Add values

ramenv set development DATABASE_URL
ramenv set development PORT --plaintext

The first command prompts for a masked value and encrypts it before saving. The second prompts for a value and stores it as visible plaintext. Use plaintext only for non-secret configuration.

Enter values at the prompt; set accepts no value argument. Use uppercase variable names: run uppercases names when injecting them into the process environment.

To import an existing .env file:

ramenv onboard development

Onboarding reads .env in the current directory and asks which variables to encrypt. Unselected values are imported as plaintext. Matching keys are overwritten, and the original .env file remains on disk. Review the vault and remove the input file yourself when it is no longer needed.

Inspect and validate

ramenv list development
ramenv validate development

list masks values by default. Masking can still show parts of a value, so avoid shared logs. --reveal prints complete decrypted values.

New variables get required string rules. Customize the validation schema if you need ports, URLs, bounds, or other checks.

Run your application

Choose a command that matches your application:

ramenv run development -- python app.py
ramenv run development -- npm run dev
ramenv run production -- ./my-server --port 8080

The -- separates ramenv’s arguments from the application command. Vault values override matching inherited environment variables; other inherited variables remain available. ramenv returns the child process’s exit code.

run does not validate configuration. If validation must gate startup, run it separately.

In a POSIX shell, use && to stop startup if validation fails:

ramenv validate production && ramenv run production -- ./my-server

ramenv decrypts values in memory without generating a decrypted .env file. Your application receives those values in its process environment, where they may be accessible to other processes. See the security boundaries.

Share the repository

Commit the workspace and reviewed vault. Send collaborators the matching .ramenv.keys file through a secure channel so they can decrypt the vault.

For identity-based key access, choose a cloud ingredient when initializing a new workspace. Re-running init with another ingredient does not migrate an existing workspace.