Getting started
Set up CipherStash in under 2 minutes with device-based authentication
Getting started
CipherStash uses device-based authentication for local development. Each developer on your team gets a unique identity — no shared secrets, no environment variables.
Initialize CipherStash
npx @cipherstash/cli initThe init command walks you through a complete setup:
Authenticate
The CLI opens your browser for device-based authentication.
Once you authorize, your token is saved to ~/.cipherstash/auth.json.
This creates a device tied to your user identity on this machine, with a client that has access to the default keyset in your workspace.
No environment variables are needed for local development.
Select your database connection
Choose how you connect to your database:
- Drizzle ORM
- Supabase JS Client
- Prisma
- Raw SQL / pg
For Supabase projects, run npx @cipherstash/cli init --supabase to get Supabase-optimized defaults.
Build your encryption schema
The wizard lets you define your encryption schema interactively — choose table names, column names, data types, and search operations (equality, free-text search, order and range).
Or use a placeholder schema to get started quickly.
The generated encryption client file is saved to ./src/encryption/index.ts by default.
Install dependencies
The CLI detects your package manager (npm, pnpm, yarn, or bun) and installs:
@cipherstash/stack— the encryption and secrets SDK@cipherstash/cli— database tooling and CLI (as a devDependency)
Next steps
The CLI shows what to do next:
- Set up your database:
npx @cipherstash/cli db setup - Run the AI-powered setup wizard:
npx @cipherstash/cli wizard - Edit your encryption schema
- Read the docs
What just happened?
The npx @cipherstash/cli init command set up three things:
- Device — A unique identity for this machine, tied to your user account. Each machine you develop on gets its own device.
- Client — The programmatic identity created for your device, used to access encryption keys and secrets.
- Keyset — The default set of encryption keys your client can now access. Keysets provide cryptographic isolation between tenants or environments.
Every developer on your team will get their own device and client when they run npx @cipherstash/cli init.
This means every operation is traceable to a specific developer.
Re-authenticating
If your session expires or you need to re-authenticate without running the full init again:
npx @cipherstash/cli auth loginThis opens your browser, polls for authorization, and saves the refreshed token to ~/.cipherstash/auth.json. Your project configuration is unchanged.
Next steps
Encryption SDK
Encrypt fields in your TypeScript application with searchable queries.
CipherStash Proxy
Drop-in SQL proxy for PostgreSQL with transparent encryption.
Secrets
Store and retrieve end-to-end encrypted secrets.
Going to production
Set up machine clients and environment variables for production and CI/CD.
Team onboarding
Invite team members with per-developer device-based access.