A Developer-First, End-to-End Encrypted CLI for Secure and Dynamic Environment Variable Management, Optimized for the Serverless Era.
In modern software development, managing environment variables and secrets (.env files) across different environments, teams, and platforms is a primary source of security vulnerabilities, operational friction, and development slowdowns. The rise of immutable infrastructure on serverless platforms (e.g., Vercel, Netlify) has introduced a new paradigm: the "rebuild to rotate" cycle, where simple configuration changes require a full application redeployment.
Redenv is a comprehensive solution designed to solve these problems. It is a CLI-first secret management system that centralizes environment variables in a Redis backend you control. It features a robust, zero-knowledge, end-to-end encrypted architecture, ensuring that your secrets are always protected. By decoupling configuration from deployment, Redenv allows development teams to manage secrets dynamically and securely, drastically improving workflow efficiency and security posture.
Get up and running with Redenv in under 60 seconds.
Install the Redenv CLI globally using your preferred package manager:
bun add -g @redenv/cliConnect your CLI to an Upstash Redis database. You can find your REST URL and Token in the Upstash Console.
redenv setupNavigate to your project directory and initialize it with an encrypted vault.
redenv register my-awesome-appNote: You will be prompted to create a Master Password. This password is the only key to your secrets—never lose it.
bun add -D @redenv/coreAdd your first encrypted secret and view it:
# Add a secret
redenv add API_KEY "super-secret-value"
# View the secret
redenv view API_KEYInstall the zero-knowledge client:
bun add @redenv/clientAccess secrets at runtime (fully decrypted in memory):
// lib/redenv.ts
import { Redenv } from "@redenv/client";
const redenv = new Redenv({
project: "my-awesome-app",
tokenId: process.env.REDENV_TOKEN_ID,
token: process.env.REDENV_TOKEN_KEY,
upstash: { ... },
});
// Load secrets (stale-while-revalidate caching built-in)
await redenv.load();// app/page.tsx
import { redenv } from "@/lib/redenv";
export default async function Home() {
const env = await redenv.load();
return (
<div>
<h1>My App</h1>
<p>API Key: {env.API_KEY}</p>
</div>
);
}For a rich, visual dashboard, install the Studio plugin. Redenv uses a plugin system, keeping the core lightweight while allowing you to add powerful features like this.
Install:
bun add -D @redenv/studioConfigure:
Add it to your redenv.config.ts:
import { defineConfig } from "@redenv/core";
import { studioPlugin } from "@redenv/studio";
export default defineConfig({
...
plugins: [studioPlugin],
});Launch:
redenv studioThis starts a local dashboard where you can drag-and-drop secrets, manage environments, and sync keys visually.
The management of application secrets has long been a challenge, but the evolution of development and deployment practices has created two distinct, significant problem areas.
The de-facto standard for local development configuration, the .env file, is a known anti-pattern when used at scale.
- Synchronization Drift: As teams grow, keeping
.envfiles synchronized between developers is a constant struggle. This often leads to "works on my machine" issues and hours of lost productivity. - Insecure Distribution: The lack of a central source of truth forces teams into insecure practices, such as sharing secrets over Slack, email, or text messages, creating a massive security liability.
Serverless and edge platforms have revolutionized deployment, but they have also cemented a new problem. By treating environment variables as immutable, build-time constants, they create a rigid and slow workflow for configuration changes.
- The "Rebuild to Rotate" Cycle: On these platforms, updating a secret (e.g., rotating a leaked API key) is a high-stakes, time-consuming process. A developer must manually change the variable in a web UI, trigger a new build, and wait for the entire deployment pipeline to complete. In an emergency, this delay is unacceptable.
- Coupling of Concerns: This paradigm tightly couples an application's configuration with its code. A simple change to a logging level or a feature flag requires the same process as a major code change, creating operational bottlenecks.
Redenv is architected to solve these problems by re-imagining the relationship between an application and its configuration. It is built on four core principles:
- Centralized & Synchronized: A single source of truth for all secrets, stored in a Redis database you control.
- Secure by Default (Zero-Knowledge): A robust end-to-end encryption model ensures that the database is considered "untrusted." Your secrets are never stored in plaintext.
- Complete Version History: Every change to a secret is recorded in an immutable history, providing a full audit trail and enabling instant rollbacks.
- Dynamic & Decoupled: Redenv is designed to be used with a runtime client (
@redenv/client), allowing applications to fetch their configuration on startup. This completely decouples secret rotation from the deployment cycle. - Developer-First Experience: A powerful and intuitive CLI provides a complete suite of commands covering the entire secret management lifecycle, with UX-focused features like secure password caching.
The effectiveness of Redenv stems from specific, deliberate technology and architectural choices.
Redenv is built exclusively for Upstash Redis, a deliberate design choice that enables universal connectivity and unmatched performance.
- Unmatched Speed: Upstash provides extremely low-latency data access, which is critical for application startup times. When an application boots, it must load its secrets instantly; any delay increases cold start times and degrades user experience.
- Serverless Model: Upstash's serverless pricing and connection model is a perfect fit for CLI tools and serverless functions, which have intermittent, spiky traffic patterns.
- HTTP-Based Client: The
@upstash/redisclient operates over a standard HTTP/REST API. This is a crucial advantage, as it guarantees connectivity from any environment, including restrictive corporate networks, serverless functions, and edge workers where traditional TCP connections may be blocked or impractical.
Redenv's security is its most critical component. It is architected to ensure that secrets are only ever held in plaintext on the user's machine or the application's runtime memory—never in the database.
The following diagram illustrates the decryption flow. The reverse process is used for encryption.
- Per-Project Encryption: Each project is an isolated security domain protected by a unique Project Encryption Key (PEK).
- Master Password: The PEK is "wrapped" (encrypted) by a key derived from a user-provided Master Password. This Master Password is known only to the user and is never stored or transmitted.
- Key Derivation: We use
PBKDF2-HMAC-SHA256with310,000iterations, a strong, industry-standard Key Derivation Function recommended by OWASP, to protect against brute-force attacks on the Master Password. This is implemented via the universal Web Crypto API, ensuring compatibility across all modern JavaScript runtimes. - Authenticated Encryption: All data, including all historical versions of secrets, is encrypted using
AES-256-GCM, which provides both confidentiality and integrity. - Service Tokens: For programmatic access, Redenv uses a secure token system. A token consists of a Public ID (a non-secret identifier) and a Secret Key. The Secret Key is used to decrypt the PEK for a specific project, allowing a server or CI/CD pipeline to securely fetch secrets without a password. This secret is displayed only once upon creation and must be stored securely by the user.
Redenv uses two primary key formats in Redis to organize data:
- Metadata Key (
meta@<project-name>): A Redis Hash that stores essential metadata for a project. This includes the encrypted Project Encryption Key (PEK), the salt for the Master Password, the history limit setting, and the configuration for any Service Tokens. - Environment Key (
<environment-name>:<project-name>): A Redis Hash where each field represents a secret's key. The value for each field is a JSON string containing an array of versioned secrets, with the most recent secret at the first index.
This structure provides efficient, project-scoped data retrieval while keeping all secrets for a given environment under a single Redis key.
Redenv provides a comprehensive suite of commands to manage secrets with confidence.
- Core Commands:
add,edit,view,list,remove - Project Management:
register,drop,switch - Advanced Workflows:
import,export,clone,diff,promote - Auditing & History:
history(view,limit),rollback - Security & Safety:
change-password,backup,restore,doctor,logout - Application Access:
token(create,list,revoke)
The Redenv ecosystem is completed by the @redenv/client, a lightweight library for any server-side JavaScript or TypeScript application. It allows applications to fetch, decrypt, and consume secrets securely and dynamically at runtime, fully realizing the vision of decoupling configuration from deployment.
- High-Performance Caching: The client features a built-in, in-memory cache with
stale-while-revalidatelogic. This ensures that secrets are served to your application instantly, eliminating latency and providing resilience against network issues, while still keeping secrets up-to-date in the background. - Zero-Knowledge, Too: All cryptographic operations happen on the client side, maintaining the same zero-knowledge security guarantee as the CLI. The application uses a Service Token to decrypt the Project Encryption Key locally.
- Seamless Integration: It can automatically populate
process.envor provide a client object (get,getAll) for programmatic access, fitting easily into existing application logic.
By using the @redenv/client, you can rotate an API key or change a feature flag and have it reflect in your running applications in seconds, without requiring a new build or deployment.
For those who prefer a visual interface over the command line, Redenv offers @redenv/studio (NPM | GitHub). This plugin launches a modern, local web dashboard that provides a rich graphical interface for managing your secrets.
- Visual Dashboard: View and edit secrets across all environments in a table view.
- Environment Management: Create, delete, and manage environments with ease.
- Access Control: Generate and manage Service Tokens for your applications and CI/CD pipelines visually.
- Secure: Runs locally on your machine, maintaining the same zero-knowledge security model as the CLI.
To use it, simply install the plugin and run:
redenv studio| Feature / Aspect | Redenv | .env Files |
Cloud Secret Managers (AWS, GCP) | HashiCorp Vault (Self-Hosted) |
|---|---|---|---|---|
| Hosting Model | Self-managed on Upstash | Local files | Fully managed by cloud provider | Fully self-hosted |
| Primary Use Case | Dynamic secrets for Serverless/Edge/CLI | Local development | IAM-integrated secrets for cloud infra | Enterprise-grade, centralized secret hub |
| Security Model | Zero-Knowledge (E2EE) | None (Plaintext) | Server-side encryption with IAM controls | Server-side encryption, requires hardening |
| Ease of Setup | Very High (seconds) | High (instant) | Medium (requires IAM config) | Low (complex, requires infrastructure) |
| Dynamic Updates | Yes (via @redenv/client) |
No (requires file change + restart) | Yes (via SDK) | Yes (via SDK/API) |
| Cost | Low (Upstash free/serverless tier) | Free | Low to Medium (per secret/per API call) | High (infrastructure and operational cost) |
| Version Control | Built-in per secret | Via Git (exposes history if not ignored) | Yes (managed versions) | Yes (via audit logs/versioned KV) |
Redenv is in active development, and I am looking for technical feedback to improve its architecture and security model.
- Roast the Architecture: I'm particularly interested in feedback regarding the client-side encryption flow and the trade-offs of using Redis as a primary secret store.
- Feature Requests: Is the
stale-while-revalidatecaching logic sufficient for your production needs? What integrations are missing? - Bug Reports: If you find a way to break the CLI or the Studio, please open an issue.
Built with ❤️ for the Upstash community.