seekrit
View as Markdown ↗

Quickstart

This walkthrough runs the whole stack on your machine and encrypts your first secret with the CLI. It uses local development auth (no Stytch project required).

note

seekrit runs entirely on your Cloudflare account in production, but every part runs locally for development — no cloud resources needed to try it.

Prerequisites

  • Node.js ≥ 22 and pnpm ≥ 10
  • A clone of the repository

1. Install and build

pnpm install
pnpm build

2. Start the API

The API is a Cloudflare Worker. In development it runs against a local D1 database and a local KV namespace.

cd apps/api
cp .dev.vars.example .dev.vars   # enables AUTH_MODE=dev
pnpm db:migrate:local            # apply migrations to the local D1
pnpm dev                         # http://localhost:8787

AUTH_MODE=dev lets you authenticate with a simple x-seekrit-dev-user header instead of a real identity provider. It only works locally and is never enabled in production.

3. Encrypt a secret with the CLI

In a second terminal, from the repository root:

# Point the CLI at the local API as a dev user
alias seekrit="node $PWD/apps/cli/dist/index.js"
export SEEKRIT_PASSPHRASE=dev-only-passphrase

seekrit login --dev-user you@example.com --api-url http://localhost:8787
seekrit keys setup                 # generate your keypair (client-side)

seekrit org create --name "Acme" --slug acme
seekrit app create --org acme --name "Storefront" --slug storefront
seekrit env create --org acme --app storefront --name Production --slug production

seekrit init --org acme --app storefront            # writes seekrit.json (org + app; no env)
seekrit secrets set DATABASE_URL 'postgres://user:pass@host/db' --env production
note

seekrit.json names the default org and app but never an environment — so it's safe to commit and runs everywhere. The environment is chosen at runtime by a service token (or, interactively, the --env flag).

tip

seekrit keys setup generates a P-256 keypair in the CLI and uploads only your public key and a passphrase-encrypted copy of your private key. Setting SEEKRIT_PASSPHRASE avoids the interactive prompt — omit it and you'll be asked.

4. Use your secrets

Inject the resolved environment into any process, or print it:

seekrit run --app storefront --env production -- printenv DATABASE_URL
seekrit export --app storefront --env production --format dotenv
seekrit secrets list --app storefront --env production

For a deployed app you'd instead mint a token bound to the environment, and it selects everything at runtime — no flags:

TOKEN=$(seekrit token create --name local-dev --app storefront --env production)
SEEKRIT_TOKEN=$TOKEN seekrit run -- printenv DATABASE_URL

Everything you just did was encrypted on your machine. The API only ever received ciphertext.

5. Try the web dashboard (optional)

cd apps/web
cp .env.example .env.local
pnpm dev            # http://localhost:3000

Sign in with the dev identity form, set up your keys, and manage the same orgs and secrets in the browser. To enable Google/GitHub sign-in, see the Web dashboard guide.

Next steps

← previousIntroductionnext →Encryption model