Quickstart

Five steps, about five minutes. Everything here also works against a self-hosted deployment — set XECRET_API_URL and the steps are identical.

If a word here is unfamiliar, core concepts defines all of them in one page.

1. Create an account

Sign up with Google or with an email address and password. On your first sign-in xecret creates your personal organisation — a workspace with just you in it. Set up your vault, then create your first project: one project per application, and it starts with three environments — development, staging and production.

Each environment gets its own encryption key at the moment it is created — generated in your browser and sealed to you, so the server never holds it. A secret stored in staging is encrypted under a different key from the same secret in production.

2. Import the .env you already have

Open your project in the dashboard, pick an environment, and drag your .env file into the import dialog.

The file is parsed in your browser. A dry-run preview shows exactly what will be created, renamed or skipped before a single value is sent anywhere — which means a pasted blob of production credentials never becomes a request body you have to trust us with.

Multiline PEM blocks, export prefixes, CRLF line endings and trailing comments all parse the way you would hope. JSON and YAML work too.

3. Install the CLI

# macOS
brew install playxoft/tap/xecret

# Linux, WSL, CI — verifies the release checksum before unpacking
curl -fsSL https://xecret.playxoft.com/install.sh | sh

# anywhere you already have Node
npm install -g @playxoft/xecret

Windows, other package managers and manual installs are covered in installing the CLI. Check it worked:

xecret version

4. Sign in and point at your project

xecret login     # opens your browser; approve this device
xecret init      # pick a project and environment; writes .xecret.yaml

xecret login opens a browser page where you approve the device by name. The credential it receives is stored in your operating system's keychain — macOS Keychain, Windows Credential Manager, or Secret Service on Linux — never in a dotfile you might commit or sync.

xecret init writes a file called .xecret.yaml:

project: my-app
environment: development

Two slugs and no secrets. Commit it. Everyone who clones the repository is then one command away from a working app.

5. Run your app

xecret run -- npm run dev

Everything after -- is your command, run exactly as you would have run it yourself. The difference is that its environment already contains every secret in the environment you selected.

What happens under the hood:

1. The CLI resolves which project and environment you mean (flags, then .xecret.yaml).
2. It asks the server for that environment; the server decrypts the values and returns them over TLS.
3. The CLI starts your command with those values in its environment, forwards signals such as Ctrl-C, and exits with your command's exit code.

Secrets never touch disk, never appear in ps output, and never enter your shell history. Every read is written to the audit log.

If the API is unreachable, an encrypted local cache answers instead — loudly, printing its age to stderr — so an outage on our side does not stop your npm run dev. See the offline cache.

Now delete your .env file, and make sure .env* is in .gitignore.

6. Put it in CI

Mint a service token in the dashboard, under Tokens → New service token. A service token is pinned to exactly one project and one environment, is read-only by default, and is shown to you exactly once — copy it straight into your CI provider's secret store.

# GitHub Actions
- uses: playxoft/xecret@v1
- run: xecret run -- npm run build
  env:
    XECRET_TOKEN: ${{ secrets.XECRET_TOKEN }}

No login, no .xecret.yaml, no configuration: the token knows its own scope. GitLab, CircleCI and Docker recipes are in secrets in CI.

Where to go next