xecret documentation
xecret stores your environment variables once, encrypted per environment, and injects them into whatever you are running — your laptop, your CI job, your container. These pages cover all of it, from the first command to running the whole thing on your own infrastructure.
New here? Start with the quickstart. If you have never used a secret manager before, read what xecret is first — it assumes nothing.
Start here
- QuickstartSign up, import the .env you already have, and start your app with secrets injected. About five minutes.
- Core conceptsOrganisations, projects, environments, secrets and versions — the five words the rest of the documentation assumes.
- CLI referenceEvery command and flag, with the exit conventions and what each one writes where.
- Secrets in CIService tokens end to end: GitHub Actions, GitLab, CircleCI and Docker builds.
Table of contents
Getting started
What xecret is, and how to have it running in five minutes.
- What is xecret?A plain-English explanation of the problem xecret solves, who it is for, and how it compares to keeping a .env file.
- QuickstartFrom sign-up to running your app with injected secrets in about five minutes, including your first CI job.
- Core conceptsOrganisations, projects, environments, secrets, versions and tokens — the vocabulary every other page assumes, defined once.
- Installing the CLIInstall the xecret command-line tool on macOS, Linux, Windows, from npm, in Docker and in CI — with checksum verification and upgrade instructions.
The CLI
The xecret binary: every command, every flag, and how it finds your project.
- The xecret CLIWhat the command-line tool does, the two rules it never breaks, how output is split between stdout and stderr, and where to find each command.
- CLI command referenceEvery xecret command and flag — login, init, projects, secrets, versions, import, pull, export, run, audit, tokens and cache — with examples and the exact behaviour of each.
- Configuration and scopeHow the CLI decides which project and environment you mean, the .xecret.yaml format, every environment variable, and where credentials are stored.
- The offline cacheHow xecret keeps working when the network does not — what the encrypted local cache stores, exactly when it answers, and why a revoked credential is never softened by it.
Guides
Wiring xecret into the framework, container or pipeline you already have.
- xecret with Next.jsReplace .env.local with xecret in a Next.js app — local development, NEXT_PUBLIC build-time variables, multiple environments, and deployment.
- xecret with Node.jsUse xecret in any Node project — npm scripts, dotenv removal, TypeScript, monorepos, tests, and reading configuration safely at startup.
- xecret with React and ViteUse xecret with a Vite front end — the VITE_ prefix, why browser configuration is never secret, and where the real credentials belong instead.
- xecret with GoUse xecret in a Go project — go run and go test under injected secrets, reading configuration at startup, and building static binaries in CI.
- xecret with DockerKeep secrets out of image layers — runtime injection, BuildKit secret mounts, Compose, and the export format that exists only for docker run.
- Secrets in CI/CDService tokens end to end — GitHub Actions, GitLab CI, CircleCI and generic runners — with scoping, rotation and the one anti-pattern to avoid.
- Importing and exporting secretsMove secrets in and out of xecret — .env, JSON, YAML and shell formats, conflict strategies, dry runs, and migrating from another secret manager.
- Teams, roles and accessInvite people, choose roles, grant access per project and environment, and understand why production is denied by default to developers.
Environments and policies
References, inheritance, overrides, promotion, restore, webhooks, and the rules an organisation sets.
- Secret references and environment inheritanceBuild one secret from others with ${env.KEY} templates, and let an environment inherit from a parent — resolved on your machine, never on our servers.
- Personal overridesUse your own value for one secret on your machine — a local database instead of staging's — without changing the environment anyone else reads, or any CI run.
- Environment promotion and point-in-time restorePromote values from staging to production with a masked diff, and put an environment back the way it was at an earlier moment — atomically, and without losing history.
- Webhooks on secret changeGet a signed HTTPS call when a secret is created, changed, rotated or deleted, or an environment is promoted or restored. Payloads carry names, never values.
- Policies and new-address read alertsRequire IP allowlists and short lifetimes on tokens, enforce secret naming and strength rules, disable plaintext export, and get told when a new address reads production.
HTTP API
The contract the dashboard, the CLI and CI all speak.
- HTTP API overviewThe contract the dashboard, CLI and CI all speak — authentication, request shape, error codes, pagination, rate limits and CSRF.
- API endpoint referenceEvery HTTP endpoint — auth, organisations, projects, environments, secrets, bulk read, import and export, members, tokens and the audit log.
- Tokens and credentialsSessions, CLI tokens and service tokens — what each can do, how they are scoped and stored, how to rotate them, and what happens when one leaks.
Security
What xecret can and cannot see, stated plainly rather than implied.
- What xecret can and cannot seeThe encryption model stated plainly — envelope encryption, the key hierarchy, what a database breach yields, and when you should choose a zero-knowledge product instead.
- The audit logEvery event xecret records, what each one means, how to filter the log, and how to use it during an incident when a credential has leaked.
- Resetting your vault, the archive, and the seven-day windowWhat happens when you reset a vault you cannot open — the emailed archive and its risk, the seven days to recover, and how to import or open the archive offline.
Running it yourself
Self-hosting: the honest dependency list and the deployment walk-through.
Reference
Answers to the things that go wrong, and the words this product uses.
- TroubleshootingEvery error message the CLI and API produce, what it actually means, and the fix — from "command not found" to "no such environment" in CI.
- Frequently asked questionsShort answers about pricing, security, offline use, team access, migrating away, self-hosting and how xecret compares to .env files and other tools.
- Using xecret with AI agentsThe one-line skill install for Claude, ChatGPT, Gemini and every other coding agent, the machine-readable documentation endpoints, and letting an agent run your app without production credentials.
Reading this with an AI agent?
Every page is published twice: as the HTML you are reading, and as the markdown it was written in. Append .md to any documentation URL to get the source — /docs/cli/commands.md, for instance. There is an index at /llms.txt and the entire documentation set concatenated into one file at /llms-full.txt.
Using xecret with AI agents covers the part that matters more: how to let a coding agent run your app without handing it your production credentials.