# Envpilot

> Secure environment variable management for teams.

Envpilot is a platform for managing, sharing, and syncing environment variables across development teams. Secrets are encrypted at rest using AES-256 via WorkOS Vault with per-organization key isolation. Access is controlled through two-tier role-based permissions (organization roles + project roles) with optional per-variable grants.

The platform has five client surfaces:
- **CLI** (`@envpilot/cli`) — pull, push, run, and manage secret files from the terminal
- **VS Code Extension** — real-time sync inside VS Code and Cursor
- **Web Dashboard** — full management UI at envpilot.dev
- **REST API + GitHub Action** — read-only machine access with org-scoped API keys
- **MCP Server** — scoped, audited secret access for coding agents

## Key Links

- Website: https://www.envpilot.dev
- Documentation: https://docs.envpilot.dev
- npm: https://www.npmjs.com/package/@envpilot/cli
- VS Code Marketplace: https://marketplace.visualstudio.com/items?itemName=envpilot.envpilot
- GitHub: https://github.com/rafay99-epic/envpilot.dev
- Full LLM context: https://docs.envpilot.dev/llms-full.txt

## Documentation

### Start Here

- [Quickstart](https://docs.envpilot.dev/start/quickstart): From zero to a working secret in about five minutes — from the dashboard, the CLI, or VS Code.
- [Core concepts](https://docs.envpilot.dev/start/concepts): Organizations, projects, environments, variables, secret files, roles, and requests — the whole object model on one page.
- [Architecture: the machine surfaces](https://docs.envpilot.dev/start/architecture): How Envpilot's five client surfaces share one auth core, and why machine credentials can read secrets but never write them.

### Platform

- [Data model](https://docs.envpilot.dev/platform/data-model): What Envpilot stores, where each piece lives, and why no single store ever holds enough to read your secrets.
- [Variables](https://docs.envpilot.dev/platform/variables): The per-environment key uniqueness rule, version history, rollback, and the soft-delete trash — everything that happens to a variable from creation to purge.
- [Secret files](https://docs.envpilot.dev/platform/secret-files): Keystores, SSH keys, certificates and service-account JSON — binary secrets with a destination path, a mode, and envelope encryption.
- [Shared Accounts](https://docs.envpilot.dev/platform/shared-accounts): Store a team's shared service-login credentials (username + password) on a project — separate from environment variables, with the same encryption and access control.
- [Secret Sharing Links](https://docs.envpilot.dev/platform/sharing): Send a single secret to someone outside your organization with a time-limited, client-encrypted link — no Slack pastes, no email attachments.
- [Diagrams in documentation](https://docs.envpilot.dev/platform/doc-diagrams): Fence a diagram as mermaid inside a project documentation page and it renders in the reader, in the editor preview, and on shared pages — no image to upload and nothing to keep in sync.
- [Sharing documentation](https://docs.envpilot.dev/platform/doc-sharing): Hand one published documentation page to a named teammate, or mint an expiring public preview link — with a gate chain that is re-checked on every single read.
- [Roles & permissions](https://docs.envpilot.dev/platform/rbac): One role per member, expressed as a capability set — plus project assignments, environment scope, per-secret grants, and Security Hold.
- [Requests & approvals](https://docs.envpilot.dev/platform/requests): The one write path that isn't a write — how developers and agents ask for a secret, and how reviewers approve it.
- [Rotation & expiry](https://docs.envpilot.dev/platform/rotation): Put a variable on a rotation schedule and let Envpilot chase the reminders — plus the tier gates that cap how many variables can do it.
- [Security](https://docs.envpilot.dev/platform/security): Encryption at rest, envelope encryption for files, instant revocation, the audit trail, and what stays your responsibility.

### Plans & Limits

- [Plans & Limits](https://docs.envpilot.dev/limits/plans): The full Free vs Pro feature matrix — what's gated, what's capped, and how enforcement works.
- [Rate limits](https://docs.envpilot.dev/limits/rate-limits): Every machine-surface rate-limit bucket — REST API, MCP server, GitHub Action, and variable requests — with exact limits and behavior when exceeded.

### CLI

- [CLI overview](https://docs.envpilot.dev/cli/overview): Install the Envpilot CLI, run your first sync, and learn the shape of the command set.
- [Authentication & accounts](https://docs.envpilot.dev/cli/auth): Sign in with the device flow, hold several accounts at once, and inspect or reset local CLI state.
- [Linking projects](https://docs.envpilot.dev/cli/link): Bind a directory to one or more Envpilot projects, switch the active target, and unlink cleanly.
- [Pull & push](https://docs.envpilot.dev/cli/pull-push): Write variables to disk in seven formats, send local changes back, and understand exactly what your role lets through.
- [Running commands with secrets](https://docs.envpilot.dev/cli/run): Inject secrets straight into a child process — no .env on disk, nothing to gitignore, nothing to leak.
- [Single secrets](https://docs.envpilot.dev/cli/secrets): Change one secret without a pull/edit/push round trip, and delete one safely.
- [Requests](https://docs.envpilot.dev/cli/requests): File a variable request, review the queue, and approve or reject without opening the dashboard.
- [Secret files](https://docs.envpilot.dev/cli/files): Upload, inspect, and materialise keystores, SSH keys and certificates from the terminal.
- [Command reference](https://docs.envpilot.dev/cli/reference): Every CLI command, argument, and example — generated from the CLI's own command catalog.
- [CLI in CI & troubleshooting](https://docs.envpilot.dev/cli/ci): Non-interactive usage, keeping secrets out of argv and logs, and the failures worth recognising on sight.

### VS Code

- [VS Code overview](https://docs.envpilot.dev/extension/overview): Install the extension, sign in, and understand what it does in your workspace.
- [Linking & sync](https://docs.envpilot.dev/extension/sync): Link a project, sync several directories in one workspace, and control what happens when files already exist or access disappears.
- [Protection](https://docs.envpilot.dev/extension/protection): Commit guard, clipboard guard, value cloaking, and edit reversion — the four things standing between a synced secret and a leak.
- [Editor features](https://docs.envpilot.dev/extension/editor): CodeLens, autocomplete over your real variable names, masked hovers, and filing a request without leaving the file.
- [Commands](https://docs.envpilot.dev/extension/commands): Every Envpilot command in the VS Code palette, generated from the extension manifest.
- [Settings](https://docs.envpilot.dev/extension/settings): Every Envpilot setting, its type and default, generated from the extension manifest.
- [Troubleshooting](https://docs.envpilot.dev/extension/troubleshooting): The symptoms that look like bugs and usually aren't, and what to check when something really is wrong.

### GitHub Action

- [GitHub Action overview](https://docs.envpilot.dev/action/overview): Pull variables — and secret files — into a workflow run with one step.
- [Inputs & outputs](https://docs.envpilot.dev/action/reference): Every input and output of the Envpilot GitHub Action, generated from action.yml.
- [Secret files in CI](https://docs.envpilot.dev/action/secret-files): Materialise keystores, certificates and service-account JSON on the runner, at the paths your build already expects.
- [Recipes](https://docs.envpilot.dev/action/recipes): Matrix environments, dotenv artifacts, monorepos, and mobile release builds.
- [Action security](https://docs.envpilot.dev/action/security): The masking invariant, what a leaked CI key can and cannot do, and how to revoke it.

### API Reference

- [API overview](https://docs.envpilot.dev/api/overview): Base URL, conventions, and the rules every endpoint obeys — read-only, bounded, and loud on failure.
- [API Quickstart](https://docs.envpilot.dev/api/quickstart): Create an API key and pull your first environment variable over REST in under a minute.
- [Authentication](https://docs.envpilot.dev/api/authentication): The API key model — scoping, surfaces, revocation, audit, and the fail-loud contract shared by REST, MCP, and the GitHub Action.
- [Errors](https://docs.envpilot.dev/api/errors): Every status code the API returns, what it means, and why some of them are deliberately vague.
- [Organization](https://docs.envpilot.dev/api/organization): Read the key's own organization metadata.
- [Projects](https://docs.envpilot.dev/api/projects): List the projects a key can reach, or fetch one by slug.
- [Variables](https://docs.envpilot.dev/api/variables): The workhorse endpoint — pull values for one environment, or key names with nothing decrypted.
- [Shared accounts](https://docs.envpilot.dev/api/accounts): Read the credentials your team shares for third-party services.
- [Secret files](https://docs.envpilot.dev/api/files): Fetch keystores, certificates and service-account files — metadata to diff, or base64 contents to write.

### MCP Server

- [MCP overview](https://docs.envpilot.dev/mcp/overview): Give a coding agent scoped, audited access to real secrets — and no way to change them.
- [MCP setup](https://docs.envpilot.dev/mcp/setup): Mint a scoped key, keep it out of your config files, and rotate it without editing a single client.
- [Connecting a client](https://docs.envpilot.dev/mcp/clients): Claude Code, Codex, Cursor, and anything else that speaks Streamable HTTP.
- [Tools](https://docs.envpilot.dev/mcp/tools): All nine MCP tools, their parameters, and the API-key resource each one demands.
- [Agent requests](https://docs.envpilot.dev/mcp/agent-requests): The only mutation a machine credential can perform — asking a human for a secret.

### Web Dashboard

- [Dashboard overview](https://docs.envpilot.dev/dashboard/overview): Sign in, read the home page, and find the audit log and analytics.
- [Working in a project](https://docs.envpilot.dev/dashboard/project): Variables, requests, files, diff, trash, accounts, sharing, members, and project settings.
- [Organization administration](https://docs.envpilot.dev/dashboard/organization): Members and Security Hold, usage against plan limits, tags, API keys, and the danger zone.

### Integrations

- [Slack & Discord Notifications](https://docs.envpilot.dev/integrations/notifications): Send organization activity — variable changes, access requests, security events — to the channels your team already lives in.

### Guides

- [How to Share Environment Variables Securely](https://docs.envpilot.dev/guides/migrate-from-dotenv): Why sharing .env files over Slack or email is dangerous, and how to share environment variables and secrets with your team the right way.
- [Next.js Environment Variables Best Practices](https://docs.envpilot.dev/guides/nextjs): How Next.js loads .env files, what NEXT_PUBLIC_ really means, build-time inlining, runtime variables, and how to keep secrets out of the client bundle.
- [Android keystore in CI](https://docs.envpilot.dev/guides/android-keystore-ci): Stop emailing the upload keystore — store it once, pull it in the build, and keep the audit trail.
- [Giving an agent secrets safely](https://docs.envpilot.dev/guides/agents): An end-to-end setup where a coding agent can read what it needs, ask for what it doesn't, and change nothing.

## Quick Start

```bash
npm install -g @envpilot/cli
envpilot sync
```

## Environments

Three environments per project: development, staging, production.

## Roles

One capability-backed role per member: Owner, Project Manager, Team Lead, Editor, Developer, Viewer.
Project assignments decide where the role applies, with optional environment scope.

Owners, project managers, team leads and editors write directly. Developers write only what they hold a grant for and file requests for the rest. Viewers read only.

## Security

- AES-256 encryption via WorkOS Vault
- Zero-knowledge architecture (server never holds plaintext secrets)
- Per-variable access control with optional expiration
- Comprehensive audit trail (40+ action types)
- Instant revocation across CLI, extension, and dashboard