/stash-cli

name: stash-cli
description: Drive CipherStash setup and encryption migrations through the `stash` CLI — `init`, `plan`, `impl`, `status`, `auth login`, `eql preflight/install/verify/migration/repair/upgrade/status/validate`, `encrypt backfill/drop`, `decrypt status/plan/backfill/drop`, `schema build`, and `manifest --json`. Covers the agent / non-interactive interface, credential rules, the staged EQL v3 rollout lifecycle, and its reverse (moving encrypted columns back to plaintext).

CipherStash CLI (`stash`)

`stash` is the **dev-time CLI** for CipherStash. It owns authentication, project setup, the EQL (Encrypted Query Language) Postgres extension, and the machinery that migrates an existing plaintext column to an encrypted one. Its runtime counterpart is `@cipherstash/stack`, which encrypts and decrypts values in your application.

Think Prisma Migrate or Drizzle Kit: a dev-time tool that prepares the database, while the runtime SDK handles queries.

**All setup and migration work is driven through this CLI.** Don't hand-write EQL SQL, don't hand-edit `.cipherstash/`, and don't introspect the database yourself. The CLI owns that state; hand-edits desync it.

Trigger

Use this skill when:

• The user wants to set up CipherStash or install EQL in a PostgreSQL database.
• Any `stash` command is being run: `init`, `plan`, `impl`, `status`, `auth`, `eql`, `db`, `encrypt`, `schema`, `manifest`, `doctor`, `telemetry`, `wizard`, `env`.
• A `stash.config.ts` file exists or needs to be created.
• A `.cipherstash/` directory exists (`context.json`, `plan.md`, `migrations.json`, `setup-prompt.md`).
• The user mentions "stash CLI", "EQL install", "encryption schema", or an encryption rollout/cutover.

Do **not** trigger when:

• Working with `@cipherstash/stack` (the runtime SDK) with no database setup involved — see the `stash-encryption` skill.
• Running the AI wizard directly — that's `@cipherstash/wizard`, a separate package.
• General PostgreSQL questions unrelated to CipherStash.

Start here

The entry point, for humans and agents alike:

npx stash init              # PostgreSQL / Drizzle / Prisma (auto-detected)
npx stash init --supabase   # Supabase
npx stash init --prisma     # Prisma Next
npx stash init --drizzle --supabase   # Drizzle on Supabase (the flags combine)

`stash init` installs the CLI as a project dev dependency, so subsequent commands can drop the `npx`. The CLI is package-manager aware — before init, use whichever one-shot runner your project uses (`npx`, `pnpm dlx`, `bunx`, `yarn dlx`). Installs are **pinned to the exact `@cipherstash/*` versions this CLI release shipped with** (never bare dist-tags, which can lag behind a release), and init flags any already-installed `@cipherstash/*` package whose resolved version differs from the release's. The fix depends on direction, and init says which applies: an **older** install should be aligned to the release (init offers the exact command); a **newer** install must NOT be downgraded — update the `stash` CLI to the matching release instead (init prints that command too). **Non-interactively, an older ("behind") skew is fatal** — init refuses with a non-zero exit and the align command rather than scaffolding against mismatched packages and reporting a false success. Interactively it offers to align. **Init installs the agent skills first, before anything else.** The per-integration set — the `stash-*` skills bundled in the `stash` tarball, chosen by integration — is copied into `.claude/skills/` when Claude Code is detected — the `claude` binary on `PATH`, or a `.claude/` directory in the project — and into `.codex/skills/` for Codex, both when both are detected. `--target claude-code|codex` names the destination explicitly and skips detection. Skills install ahead of authentication deliberately: it is the only step needing neither network nor credentials, so the guidance survives a run that later fails at auth, at the database URL, or at EQL — which is when it is needed most. The summary reports the outcome either way, and `.cipherstash/context.json` records the names under `installedSkills`. When no agent is detected nothing is written and the summary says so, with the command that will install them. Likewise, if the EQL extension isn't installed at the end, init reports **"Setup incomplete"** and exits non-zero — it never claims a setup is complete when encryption would fail at query time. Integrations that install EQL through a migration are the exception and exit 0: **Prisma Next** installs it via the top-level `prisma-next migrate`, and the **Drizzle** and **local Supabase** flows (a Supabase project with a local `supabase/` directory — a hosted one with no CLI scaffolding installs directly) *generate* an EQL migration, which init reports honestly as "EQL migration generated — apply it with `drizzle-kit migrate`" (Supabase: `supabase db reset` locally, `supabase db push` remotely) rather than claiming the extension is already installed. Re-running init over a project whose install migration is already on disk reports "EQL migration **already present**" — same apply step, same zero exit, no claim that this run generated anything.

**If you are an agent, do this first:**

1. **`npx stash manifest --json`** — the structured, version-stamped command surface. Read it before running anything else. 2. **`npx stash auth login --json --region <slug>`** — only if not already authenticated. Surface the URL to the human (see [Authentication](#authentication)). Do this *before* `init`. 3. **`npx stash init`** — now finds the token and proceeds without prompting. It installs the per-integration skills into `.claude/skills/` or `.codex/skills/` as its **first** step, before authenticating, so read them from there once init has run — pass `--target` if you want to name the destination yourself. If the summary says `No agent skills installed`, no agent was detected: run `stash plan --target <name>` to install