CipherStash CLI

stash is a dev-time CLI and library for managing CipherStash EQL (Encrypted Query Language) in PostgreSQL.

@cipherstash/stack is the runtime encryption SDK. It stays lean with no heavy dependencies like pg. stash is a devDependency that handles database tooling: installing EQL extensions, checking permissions, validating schemas, and managing the schema lifecycle.

Think of it like Prisma CLI or Drizzle Kit. It sets up the database while the main SDK handles runtime operations.

Quick start

Interactive (recommended)

The setup lifecycle has three explicit save-points. Each command can be run standalone; the chain prompts after init and plan are convenience for first-time users.

npx stash init

npx stash plan

npx stash impl

Manual setup

If you prefer to configure things yourself rather than running stash init, you can scaffold the config file manually and run stash db install directly.

npm install -D stash

import { defineConfig } from 'stash'

export default defineConfig({
  databaseUrl: process.env.DATABASE_URL!,
})

DATABASE_URL=postgresql://user:password@localhost:5432/mydb

npx stash db install

Good to know: Using Drizzle? The CLI auto-detects a drizzle.config.* file or drizzle-orm/drizzle-kit in package.json and generates a migration automatically. You can also pass --drizzle explicitly. Run npx drizzle-kit migrate after to apply it.

Configuration

The stash.config.ts file is the single source of truth for the CLI. Use defineConfig for type safety.

import { defineConfig } from 'stash'

export default defineConfig({
  databaseUrl: process.env.DATABASE_URL!,
  client: './src/encryption/index.ts',
})

The CLI loads .env.local, .env.development.local, .env.development, then .env (first-win, Next.js precedence) before evaluating the config, so process.env references work without any extra setup. The config file is resolved by walking up from the current working directory, similar to how tsconfig.json resolution works.

Wizard

stash wizard (also available as @cipherstash/wizard) is the CipherStash-hosted AI setup tool. It reads your codebase, asks which columns to encrypt, and wires up @cipherstash/stack for you.

The primary setup path is stash init → stash plan → stash impl, which can hand off to Claude Code, Codex, AGENTS.md (Cursor, Windsurf, Cline), or the wizard. The wizard is one handoff target among these options.

Run it directly with:

npx stash wizard

Or via the package runner:

npx @cipherstash/wizard       # npm / Node
pnpm dlx @cipherstash/wizard  # pnpm
bunx @cipherstash/wizard      # bun
yarn dlx @cipherstash/wizard  # yarn

Prerequisites

Before running the wizard, your project should have:

• An authenticated CipherStash session (npx stash auth login)
• A stash.config.ts (run npx stash init or npx stash db install to scaffold one)
• A reachable database via DATABASE_URL

What the wizard does

1. Detects your framework (Drizzle, Supabase, Prisma, generic) and TypeScript usage.
2. Runs health checks against the CipherStash gateway and your database.
3. Prompts you to pick the tables and columns to encrypt.
4. Sends a prompt to the Claude Agent SDK, which edits your schema and call sites to use @cipherstash/stack's encryption APIs. The agent runs against a CipherStash-hosted LLM gateway. No Anthropic API key is required.
5. Runs post-agent steps: package install, db install, db push, and framework-specific migrations.
6. Scans for remaining call sites that need encryptModel/decryptModel wiring and prints a summary. These locations are not edited automatically.
7. Offers to install integration-appropriate agent skills into ./.claude/skills/.

Wizard log

Each run writes a timestamped log to .cipherstash/wizard-log.md in your project root. The log records phases, decisions, and touched files.

Backfilling existing data

When the wizard adds encryptedType to columns that already have data, you must backfill the existing rows with encryptModel before dropping the old column. The wizard prints a reminder with the recommended pattern. You are responsible for writing and running this backfill.

Experimental commands

env

The env command prints a .env.production.local block with your CipherStash credentials. Pass --write to write it to disk.

STASH_EXPERIMENTAL_ENV_CMD=1 npx stash env
STASH_EXPERIMENTAL_ENV_CMD=1 npx stash env --write

This command is experimental and gated behind the STASH_EXPERIMENTAL_ENV_CMD=1 environment variable. It is not ready for production use.

Next steps