diff --git a/content/stack/cipherstash/cli/troubleshooting.mdx b/content/docs/guides/troubleshooting/cli.mdx similarity index 86% rename from content/stack/cipherstash/cli/troubleshooting.mdx rename to content/docs/guides/troubleshooting/cli.mdx index 6018185..5586a59 100644 --- a/content/stack/cipherstash/cli/troubleshooting.mdx +++ b/content/docs/guides/troubleshooting/cli.mdx @@ -1,20 +1,22 @@ --- -title: Troubleshooting +title: CLI troubleshooting description: Fix common CipherStash CLI errors covering config files, database permissions, EQL installs, Supabase resets, and Drizzle migration issues. +type: guide +components: [cli, eql] --- ## Common errors | Error | Cause | Fix | |---|---|---| -| `Could not find stash.config.ts` | No config file in cwd or parent dirs | Run `npx stash init` (which runs `db install` automatically), or run `npx stash db install` directly, or create `stash.config.ts` manually | +| `Could not find stash.config.ts` | No config file in cwd or parent dirs | Run `npx stash init` (which runs `eql install` automatically), or run `npx stash eql install` directly, or create `stash.config.ts` manually | | `databaseUrl is required` | Config missing `databaseUrl` | Add `databaseUrl` to config and check `.env` is loaded | | `must be superuser to create an operator family` | Standard SQL requires superuser | The CLI falls back to OPE mode automatically on managed databases. Pass `--exclude-operator-family` if you see this on self-hosted Postgres. | | `Insufficient database permissions` | Role lacks `CREATE` privileges | Connect as superuser or grant permissions | | `EQL is already installed` | `eql_v2` schema exists | Use `--force` to reinstall | | `Encrypt client file not found` | `push`/`validate` can't find the file at `config.client` | Set `client` in `stash.config.ts` to the correct path | | `drizzle-kit generate failed` | drizzle-kit not installed or wrong output dir | Install `drizzle-kit` and set `--out` to match your Drizzle config | -| EQL missing after `supabase db reset` | EQL was installed via direct push, not as a migration | Re-run `db install --supabase --migration` to add EQL to `supabase/migrations/`. See [below](#supabase-db-reset). | +| EQL missing after `supabase db reset` | EQL was installed via direct push, not as a migration | Re-run `eql install --supabase --migration` to add EQL to `supabase/migrations/`. See [below](#supabase-db-reset). | ## Permission issues @@ -23,7 +25,7 @@ The `install` command checks database permissions before running. On managed dat If you still see permission errors: 1. Run `npx stash db test-connection` to verify your database URL is correct. -2. Run `npx stash db status` to check the current EQL state. +2. Run `npx stash eql status` to check the current EQL state. 3. Ensure the connected role has `CREATE` privileges on the database and `public` schema. 4. For the `pgcrypto` extension, the role needs `SUPERUSER` or extension owner privileges. @@ -54,10 +56,10 @@ When adding `encryptedType` to a column that already has data, the CLI rewrites ### Fix for new installs -Re-run `db install` and choose the migration-file path: +Re-run `eql install` and choose the migration-file path: ```bash -npx stash db install --supabase --migration +npx stash eql install --supabase --migration ``` The CLI writes EQL SQL to `supabase/migrations/00000000000000_cipherstash_eql.sql`. The all-zero timestamp prefix ensures it runs before any user migrations that reference `eql_v2_encrypted`. After the file is created, `supabase db reset` will reinstall EQL automatically on every reset. @@ -67,7 +69,7 @@ The CLI writes EQL SQL to `supabase/migrations/00000000000000_cipherstash_eql.sq If you already ran a direct-push install and your live database is working, your existing install is not broken. To get a migration file going forward without disrupting the live database, run: ```bash -npx stash db install --supabase --migration --force +npx stash eql install --supabase --migration --force ``` The EQL SQL is idempotent. The `--force` flag regenerates the install even though EQL is already present. Your live install is unaffected. After this, `supabase db reset` reinstalls EQL from the migration file. diff --git a/content/stack/cipherstash/cli/api.mdx b/content/docs/reference/cli/api.mdx similarity index 98% rename from content/stack/cipherstash/cli/api.mdx rename to content/docs/reference/cli/api.mdx index 2de1e65..a387b65 100644 --- a/content/stack/cipherstash/cli/api.mdx +++ b/content/docs/reference/cli/api.mdx @@ -1,6 +1,8 @@ --- title: Programmatic API description: Import the stash package programmatically to install EQL, load and validate stash.config.ts, and build custom CipherStash tooling or CI scripts. +type: reference +components: [cli] --- Import `stash` directly for custom tooling or CI scripts. diff --git a/content/stack/cipherstash/cli/impl.mdx b/content/docs/reference/cli/impl.mdx similarity index 87% rename from content/stack/cipherstash/cli/impl.mdx rename to content/docs/reference/cli/impl.mdx index 12db2c2..76b32c0 100644 --- a/content/stack/cipherstash/cli/impl.mdx +++ b/content/docs/reference/cli/impl.mdx @@ -1,10 +1,10 @@ --- title: Execute an encryption plan description: Run stash impl to execute your CipherStash encryption plan by handing off to a coding agent such as Claude Code, Codex, or AGENTS.md. +type: reference +components: [cli] --- -# Execute an encryption plan - `stash impl` is the third step in the setup lifecycle. It reads your plan, confirms the scope, and hands off to a coding agent to make the changes. Run `stash plan` first to produce `.cipherstash/plan.md`. ```bash @@ -121,15 +121,15 @@ No plan at `.cipherstash/plan.md`. Run `stash plan` first, or pass --continue-wi When the agent handoff completes, `stash impl` prints: ``` -Implementation handoff complete. Run `stash db status` to verify state. +Implementation handoff complete. Run `stash eql status` to verify state. ``` -Run `stash db status` to check EQL installation and `stash encrypt status` for per-column migration state. +Run `stash eql status` to check EQL installation and `stash encrypt status` for per-column migration state. ## Next steps - - - + + + diff --git a/content/docs/reference/cli/index.mdx b/content/docs/reference/cli/index.mdx index 8eeffd3..3361207 100644 --- a/content/docs/reference/cli/index.mdx +++ b/content/docs/reference/cli/index.mdx @@ -1,8 +1,196 @@ --- -title: CLI -description: "CLI documentation — being built as part of the docs V2 overhaul." +title: CipherStash CLI +description: The stash dev-time CLI installs EQL in PostgreSQL, scaffolds an encryption client, and manages schemas with init, plan, and impl commands. +type: reference +components: [cli] --- -This section is being built as part of the docs V2 overhaul ([CIP-3307](https://linear.app/cipherstash/issue/CIP-3307)). Track progress in [IA.md](https://github.com/cipherstash/docs/blob/v2/IA.md). +`stash` is a dev-time CLI and library for managing CipherStash EQL (Encrypted Query Language) in PostgreSQL. -Until it lands, current documentation lives in the [existing docs](/stack). +`@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. + +| Package | Role | Install as | +|---|---|---| +| `@cipherstash/stack` | Runtime encryption and decryption | dependency | +| `stash` | Database setup and schema management | devDependency | + +## 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. + + + + ### Run init + + `stash init` authenticates you, resolves your database, scaffolds an encryption client, installs dependencies, installs EQL, and writes `.cipherstash/context.json`. + + ```bash + npx stash init + ``` + + When init finishes, it asks (default-yes) whether to continue to `stash plan`. + + + + ### Draft an encryption plan + + `stash plan` hands off to a coding agent (Claude Code or Codex), which reads your project and writes `.cipherstash/plan.md`. The plan lists the tables and columns to encrypt. Review it before proceeding. + + ```bash + npx stash plan + ``` + + When plan finishes, it asks (default-yes) whether to continue to `stash impl`. + + + + ### Execute the plan + + `stash impl` reads the plan, shows a summary panel, asks you to confirm, and dispatches to the agent to make the changes. + + ```bash + 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 eql install` directly. + + + + ### Install the CLI + + ```bash + npm install -D stash + ``` + + + + ### Create stash.config.ts + + Create `stash.config.ts` in your project root: + + ```typescript filename="stash.config.ts" + import { defineConfig } from 'stash' + + export default defineConfig({ + databaseUrl: process.env.DATABASE_URL!, + }) + ``` + + + + ### Add your database URL + + ```bash filename=".env" + DATABASE_URL=postgresql://user:password@localhost:5432/mydb + ``` + + + + ### Install EQL + + ```bash + npx stash eql 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. + +```typescript filename="stash.config.ts" +import { defineConfig } from 'stash' + +export default defineConfig({ + databaseUrl: process.env.DATABASE_URL!, + client: './src/encryption/index.ts', +}) +``` + +| Option | Required | Default | Description | +|---|---|---|---| +| `databaseUrl` | Yes | | PostgreSQL connection string | +| `client` | No | `./src/encryption/index.ts` | Path to your encryption client file. Used by `push` and `validate`. | + +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: + +```bash +npx stash wizard +``` + +Or via the package runner: + +```bash +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 eql 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, `eql 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](/stack/reference/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. + +```bash +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 + + + + + + + + + diff --git a/content/stack/cipherstash/cli/init.mdx b/content/docs/reference/cli/init.mdx similarity index 82% rename from content/stack/cipherstash/cli/init.mdx rename to content/docs/reference/cli/init.mdx index 50459f6..410af98 100644 --- a/content/stack/cipherstash/cli/init.mdx +++ b/content/docs/reference/cli/init.mdx @@ -1,6 +1,8 @@ --- title: Interactive setup description: Run stash init to authenticate, resolve your database, scaffold an encryption client, install dependencies, and add the EQL extension to CipherStash. +type: reference +components: [cli] --- `npx stash init` is the first step in the CipherStash setup lifecycle. It authenticates you, resolves your database, scaffolds an encryption client, installs dependencies, installs the EQL extension, and writes a context file. When it finishes, it prompts you to continue to `stash plan`. @@ -17,7 +19,7 @@ Init runs six steps with minimal prompts: 2. **Resolves the database**: Reads your `DATABASE_URL` and verifies a connection can be made. Detects your Postgres provider (Supabase from the URL host, or generic Postgres). 3. **Generates the encryption client file**: Auto-detects your integration (Drizzle from `drizzle.config.*` or `drizzle-orm`/`drizzle-kit` in `package.json`, Supabase from the `DATABASE_URL` host, or generic Postgres). Writes a placeholder client to `./src/encryption/index.ts` silently. If that file already exists, it prompts you to keep it or overwrite it. 4. **Installs dependencies**: Checks whether `@cipherstash/stack` and `stash` are already in `node_modules`. If both are present, skips silently. If either is missing, shows a single combined install prompt. Detects your package manager (npm, pnpm, yarn, bun) automatically. -5. **Installs EQL**: Runs the same logic as `stash db install`. Scaffolds `stash.config.ts` if missing, detects your provider, and installs the EQL extension into your database. You do not need to run `stash db install` separately after init. +5. **Installs EQL**: Runs the same logic as `stash eql install`. Scaffolds `stash.config.ts` if missing, detects your provider, and installs the EQL extension into your database. You do not need to run `stash eql install` separately after init. 6. **Gathers context**: Writes `.cipherstash/context.json` with the detected integration, package manager, schemas, environment keys, and available agents. This file is required by `stash plan` and `stash impl`. Best case: 0 prompts (already authenticated, both packages installed, no existing client file, database reachable). Worst case: 2 prompts (region selection for first-time login, install confirmation for missing packages). @@ -73,24 +75,24 @@ Answering yes launches `stash plan` immediately. Answering no (or running non-in Next: run `stash plan` to draft your encryption plan. ``` -## db install flags +## eql install flags -If you need to run EQL installation with specific flags (for example, writing a Supabase migration file), use `stash db install` directly after init: +If you need to run EQL installation with specific flags (for example, writing a Supabase migration file), use `stash eql install` directly after init: ```bash -npx stash db install --supabase --migration -npx stash db install --drizzle -npx stash db install --drizzle --supabase +npx stash eql install --supabase --migration +npx stash eql install --drizzle +npx stash eql install --drizzle --supabase ``` > **Good to know**: You can pass `--drizzle` and `--supabase` together. The CLI combines both behaviors: Supabase-compatible SQL output as a Drizzle migration. -See [Install and upgrade EQL](/stack/cipherstash/cli/install) for the full flag reference. +See [Install and upgrade EQL](/reference/cli/install) for the full flag reference. ## Next steps - - + + diff --git a/content/stack/cipherstash/cli/install.mdx b/content/docs/reference/cli/install.mdx similarity index 82% rename from content/stack/cipherstash/cli/install.mdx rename to content/docs/reference/cli/install.mdx index 9c12b3e..f6250aa 100644 --- a/content/stack/cipherstash/cli/install.mdx +++ b/content/docs/reference/cli/install.mdx @@ -1,6 +1,8 @@ --- title: Install and upgrade EQL description: Install or upgrade EQL extensions in Postgres with the stash CLI, covering Supabase and Drizzle migrations, auto-detection, and permission fallbacks. +type: reference +components: [cli, eql] --- ## install @@ -8,10 +10,12 @@ description: Install or upgrade EQL extensions in Postgres with the stash CLI, c Install the CipherStash EQL extensions into your database. Uses bundled SQL by default for offline, deterministic installs. ```bash -npx stash db install [options] +npx stash eql install [options] ``` -`db install` scaffolds `stash.config.ts` if it is missing. The command: +`stash db install` is a deprecated alias for `stash eql install` — it still works, but prints a deprecation warning. Use `eql install` going forward. + +`eql install` scaffolds `stash.config.ts` if it is missing. The command: 1. **Scaffolds `stash.config.ts`** with the database URL and client path (if the file does not already exist). 2. **Scaffolds the encryption client file** at the path referenced in `stash.config.ts` if the file does not exist. Uses the same auto-detected integration template as `init` (Drizzle, Supabase, or generic Postgres). Silent, no prompt. @@ -37,36 +41,36 @@ After a successful install, the CLI prints a summary of what was installed. If y Standard install: ```bash -npx stash db install +npx stash eql install ``` Dry run to preview changes: ```bash -npx stash db install --dry-run +npx stash eql install --dry-run ``` Fetch the latest EQL from GitHub: ```bash -npx stash db install --latest +npx stash eql install --latest ``` ### Auto-detection -`db install` auto-detects two things before prompting you: +`eql install` auto-detects two things before prompting you: - **Supabase**: If `DATABASE_URL` contains a `*.supabase.co`, `*.supabase.com`, or `*.pooler.supabase.com` host, the CLI uses the Supabase-compatible install automatically. You can still pass `--supabase` explicitly to override. - **Drizzle**: If a `drizzle.config.*` file exists or `drizzle-orm`/`drizzle-kit` appears in `package.json`, the CLI generates a Drizzle migration automatically. You can still pass `--drizzle` explicitly. ### Automatic OPE fallback -On managed databases (Supabase, Neon, RDS), the connected role is often not a superuser. `db install` detects this and automatically uses the no-operator-family (OPE) install variant, logging a line to inform you. You do not need to pass `--exclude-operator-family` manually on these hosts. +On managed databases (Supabase, Neon, RDS), the connected role is often not a superuser. `eql install` detects this and automatically uses the no-operator-family (OPE) install variant, logging a line to inform you. You do not need to pass `--exclude-operator-family` manually on these hosts. ### Supabase install ```bash -npx stash db install --supabase +npx stash eql install --supabase ``` The `--supabase` flag uses the Supabase-specific SQL variant. It omits `CREATE OPERATOR FAMILY` and grants `USAGE`, table, routine, and sequence permissions on the `eql_v2` schema to `anon`, `authenticated`, and `service_role`. @@ -83,13 +87,13 @@ The migration-file path writes EQL SQL into `supabase/migrations/00000000000000_ ```bash # Write EQL as a migration file -npx stash db install --supabase --migration +npx stash eql install --supabase --migration # Push EQL directly to the database -npx stash db install --supabase --direct +npx stash eql install --supabase --direct # Override the migrations directory -npx stash db install --supabase --migration --migrations-dir ./db/migrations +npx stash eql install --supabase --migration --migrations-dir ./db/migrations ``` @@ -97,7 +101,7 @@ npx stash db install --supabase --migration --migrations-dir ./db/migrations - EQL installed via direct push does not survive `supabase db reset`. The reset command drops the database and reruns only files in `supabase/migrations/`. If you use `supabase db reset`, install EQL as a migration file instead. See [Supabase db reset removes EQL](/stack/cipherstash/cli/troubleshooting#supabase-db-reset). + EQL installed via direct push does not survive `supabase db reset`. The reset command drops the database and reruns only files in `supabase/migrations/`. If you use `supabase db reset`, install EQL as a migration file instead. See [Supabase db reset removes EQL](/guides/troubleshooting/cli#supabase-db-reset). @@ -109,7 +113,7 @@ npx stash db install --supabase --migration --migrations-dir ./db/migrations If you use Drizzle ORM and want EQL installation as part of your migration history, use `--drizzle`: ```bash -npx stash db install --drizzle +npx stash eql install --drizzle npx drizzle-kit migrate ``` @@ -122,7 +126,7 @@ This process: To customize the migration name and output directory: ```bash -npx stash db install --drizzle --name setup-eql --out ./migrations +npx stash eql install --drizzle --name setup-eql --out ./migrations ``` `drizzle-kit` must be installed. The `--out` value must match your Drizzle config. @@ -130,7 +134,7 @@ npx stash db install --drizzle --name setup-eql --out ./migrations You can combine `--drizzle` and `--supabase`: ```bash -npx stash db install --drizzle --supabase +npx stash eql install --drizzle --supabase ``` This generates a Supabase-compatible EQL migration file. @@ -139,7 +143,7 @@ This generates a Supabase-compatible EQL migration file. When you add `encryptedType` to a Drizzle column that already has data, `drizzle-kit generate` emits an `ALTER TABLE ... ALTER COLUMN ... SET DATA TYPE eql_v2_encrypted` statement. Postgres cannot cast existing data to `eql_v2_encrypted` implicitly, so this migration would fail. -`db install --drizzle` automatically rewrites those statements into a safe `ADD COLUMN / DROP COLUMN / RENAME COLUMN` sequence. The rewrite adds a comment in the migration to remind you to backfill the new column with `encryptModel` before dropping the old one. You are responsible for writing and running that backfill in your application code before applying the DROP step. +`eql install --drizzle` automatically rewrites those statements into a safe `ADD COLUMN / DROP COLUMN / RENAME COLUMN` sequence. The rewrite adds a comment in the migration to remind you to backfill the new column with `encryptModel` before dropping the old one. You are responsible for writing and running that backfill in your application code before applying the DROP step. ### Permission pre-checks @@ -158,7 +162,7 @@ If the role is not a superuser, the CLI falls back automatically to the OPE (no- Upgrade an existing EQL installation to the version bundled with the package, or to the latest version from GitHub. ```bash -npx stash db upgrade [options] +npx stash eql upgrade [options] ``` | Option | Description | @@ -168,7 +172,7 @@ npx stash db upgrade [options] | `--exclude-operator-family` | Skip operator family creation | | `--latest` | Fetch the latest EQL from GitHub instead of using the bundled version | -The EQL install SQL is idempotent and safe to re-run. The CLI checks the current version, re-runs the install SQL, and reports the new version. If EQL is not installed, the CLI suggests running `npx stash db install` instead. +The EQL install SQL is idempotent and safe to re-run. The CLI checks the current version, re-runs the install SQL, and reports the new version. If EQL is not installed, the CLI suggests running `npx stash eql install` instead. ## Bundled EQL SQL diff --git a/content/docs/reference/cli/meta.json b/content/docs/reference/cli/meta.json index 0a67892..87977b0 100644 --- a/content/docs/reference/cli/meta.json +++ b/content/docs/reference/cli/meta.json @@ -1,4 +1,16 @@ { "title": "CLI", - "pages": ["..."] + "pages": [ + "---Setup---", + "init", + "plan", + "impl", + "status", + "---Database---", + "install", + "validate", + "push", + "---Reference---", + "api" + ] } diff --git a/content/stack/cipherstash/cli/plan.mdx b/content/docs/reference/cli/plan.mdx similarity index 90% rename from content/stack/cipherstash/cli/plan.mdx rename to content/docs/reference/cli/plan.mdx index 88e1f5c..be42a41 100644 --- a/content/stack/cipherstash/cli/plan.mdx +++ b/content/docs/reference/cli/plan.mdx @@ -1,10 +1,10 @@ --- title: Draft an encryption plan description: Run stash plan to hand off to a coding agent that drafts a reviewable encryption plan.md, with column paths, before any code changes are made. +type: reference +components: [cli] --- -# Draft an encryption plan - `stash plan` is the second step in the setup lifecycle. It hands off to a coding agent, which reads your project and produces a reviewable encryption plan at `.cipherstash/plan.md`. No code is changed. The plan is a checkpoint you review before running `stash impl`. ```bash @@ -91,7 +91,7 @@ Before running `stash impl`, open `.cipherstash/plan.md` and verify: ## Next steps - - - + + + diff --git a/content/stack/cipherstash/cli/push.mdx b/content/docs/reference/cli/push.mdx similarity index 88% rename from content/stack/cipherstash/cli/push.mdx rename to content/docs/reference/cli/push.mdx index 0146c61..4e52292 100644 --- a/content/stack/cipherstash/cli/push.mdx +++ b/content/docs/reference/cli/push.mdx @@ -1,6 +1,8 @@ --- title: Push and status -description: Push your CipherStash encryption schema to PostgreSQL and use db status and test-connection to check EQL installation and database connectivity. +description: Push your CipherStash encryption schema to PostgreSQL and use eql status and test-connection to check EQL installation and database connectivity. +type: reference +components: [cli, eql] --- ## push @@ -24,7 +26,7 @@ npx stash db push [options] When pushing, the CLI: 1. Loads the encryption client from the path in `stash.config.ts` -2. Runs [schema validation](/stack/cipherstash/cli/validate) (warns but doesn't block) +2. Runs [schema validation](/reference/cli/validate) (warns but doesn't block) 3. Transforms SDK data types to EQL-compatible `cast_as` values 4. Connects to Postgres and marks existing `eql_v2_configuration` rows as `inactive` 5. Inserts the new config as an `active` row @@ -48,7 +50,7 @@ The SDK uses developer-friendly type names, but EQL expects PostgreSQL-aligned t Show the current state of EQL in your database. ```bash -npx stash db status +npx stash eql status ``` Reports: diff --git a/content/stack/cipherstash/cli/status.mdx b/content/docs/reference/cli/status.mdx similarity index 81% rename from content/stack/cipherstash/cli/status.mdx rename to content/docs/reference/cli/status.mdx index 7c15002..3721df7 100644 --- a/content/stack/cipherstash/cli/status.mdx +++ b/content/docs/reference/cli/status.mdx @@ -1,10 +1,10 @@ --- title: Project status description: Run stash status for a fast, read-only view of your CipherStash setup lifecycle, reading disk state only with no network, database, or auth. +type: reference +components: [cli] --- -# Project status - `stash status` shows where your project stands in the CipherStash setup lifecycle. It reads disk state only: no network, no database connection, no authentication. It runs in milliseconds. ```bash @@ -34,7 +34,7 @@ Lifecycle ◯ Implementation waiting on plan Deeper inspection -Database state: `stash db status` +Database state: `stash eql status` Per-column state: `stash encrypt status` Next: run `stash plan` to draft your encryption plan. @@ -61,7 +61,7 @@ Next: run `stash plan` to draft your encryption plan. | Command | What it shows | |---|---| -| `stash db status` | EQL installation state, database permissions, active encrypt config | +| `stash eql status` | EQL installation state, database permissions, active encrypt config | | `stash encrypt status` | Per-column migration state: phase, progress, and drift | ## When to use stash status @@ -77,7 +77,7 @@ Common use cases: ## Next steps - - - + + + diff --git a/content/stack/cipherstash/cli/validate.mdx b/content/docs/reference/cli/validate.mdx similarity index 89% rename from content/stack/cipherstash/cli/validate.mdx rename to content/docs/reference/cli/validate.mdx index 33eb8d6..65ff662 100644 --- a/content/stack/cipherstash/cli/validate.mdx +++ b/content/docs/reference/cli/validate.mdx @@ -1,6 +1,8 @@ --- title: Schema validation description: Use stash db validate to check your CipherStash encryption schema for misconfigurations, with rules for search types, indexes, and operator families. +type: reference +components: [cli, eql] --- The `validate` command checks your encryption schema for common misconfigurations. @@ -43,4 +45,4 @@ The command loads your encryption schema from the file specified by `client` in - **Errors** cause the command to exit with code 1. - **Warnings** and **info** messages are printed but don't cause a non-zero exit. -- Validation also runs automatically before [`push`](/stack/cipherstash/cli/push). Issues are logged as warnings but don't block the push. +- Validation also runs automatically before [`push`](/reference/cli/push). Issues are logged as warnings but don't block the push. diff --git a/content/stack/cipherstash/cli/index.mdx b/content/stack/cipherstash/cli/index.mdx deleted file mode 100644 index 7197e5e..0000000 --- a/content/stack/cipherstash/cli/index.mdx +++ /dev/null @@ -1,194 +0,0 @@ ---- -title: CipherStash CLI -description: The stash dev-time CLI installs EQL in PostgreSQL, scaffolds an encryption client, and manages schemas with init, plan, and impl commands. ---- - -`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. - -| Package | Role | Install as | -|---|---|---| -| `@cipherstash/stack` | Runtime encryption and decryption | dependency | -| `stash` | Database setup and schema management | devDependency | - -## 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. - - - - ### Run init - - `stash init` authenticates you, resolves your database, scaffolds an encryption client, installs dependencies, installs EQL, and writes `.cipherstash/context.json`. - - ```bash - npx stash init - ``` - - When init finishes, it asks (default-yes) whether to continue to `stash plan`. - - - - ### Draft an encryption plan - - `stash plan` hands off to a coding agent (Claude Code or Codex), which reads your project and writes `.cipherstash/plan.md`. The plan lists the tables and columns to encrypt. Review it before proceeding. - - ```bash - npx stash plan - ``` - - When plan finishes, it asks (default-yes) whether to continue to `stash impl`. - - - - ### Execute the plan - - `stash impl` reads the plan, shows a summary panel, asks you to confirm, and dispatches to the agent to make the changes. - - ```bash - 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. - - - - ### Install the CLI - - ```bash - npm install -D stash - ``` - - - - ### Create stash.config.ts - - Create `stash.config.ts` in your project root: - - ```typescript filename="stash.config.ts" - import { defineConfig } from 'stash' - - export default defineConfig({ - databaseUrl: process.env.DATABASE_URL!, - }) - ``` - - - - ### Add your database URL - - ```bash filename=".env" - DATABASE_URL=postgresql://user:password@localhost:5432/mydb - ``` - - - - ### Install EQL - - ```bash - 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. - -```typescript filename="stash.config.ts" -import { defineConfig } from 'stash' - -export default defineConfig({ - databaseUrl: process.env.DATABASE_URL!, - client: './src/encryption/index.ts', -}) -``` - -| Option | Required | Default | Description | -|---|---|---|---| -| `databaseUrl` | Yes | | PostgreSQL connection string | -| `client` | No | `./src/encryption/index.ts` | Path to your encryption client file. Used by `push` and `validate`. | - -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: - -```bash -npx stash wizard -``` - -Or via the package runner: - -```bash -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](/stack/reference/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. - -```bash -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 - - - - - - - - - diff --git a/content/stack/cipherstash/cli/meta.json b/content/stack/cipherstash/cli/meta.json deleted file mode 100644 index 1c5523e..0000000 --- a/content/stack/cipherstash/cli/meta.json +++ /dev/null @@ -1,18 +0,0 @@ -{ - "title": "CipherStash CLI", - "pages": [ - "index", - "---Setup---", - "init", - "plan", - "impl", - "status", - "---Database---", - "install", - "validate", - "push", - "---Reference---", - "api", - "troubleshooting" - ] -} diff --git a/content/stack/cipherstash/encryption/drizzle.mdx b/content/stack/cipherstash/encryption/drizzle.mdx index 1ca35f9..5dc42e9 100644 --- a/content/stack/cipherstash/encryption/drizzle.mdx +++ b/content/stack/cipherstash/encryption/drizzle.mdx @@ -21,10 +21,10 @@ The Drizzle integration is included in `@cipherstash/stack` and imports from `@c ### Install EQL via Drizzle migrations -Use the [CipherStash CLI](/stack/cipherstash/cli) to generate a Drizzle migration that installs the [EQL](/stack/reference/eql-guide) extension: +Use the [CipherStash CLI](/reference/cli) to generate a Drizzle migration that installs the [EQL](/stack/reference/eql-guide) extension: ```bash -npx stash db install --drizzle +npx stash eql install --drizzle npx drizzle-kit migrate ``` @@ -33,7 +33,7 @@ npx drizzle-kit migrate | `--name ` | `install-eql` | Migration name | | `--out ` | `drizzle` | Output directory (must match your Drizzle config) | -See [CipherStash CLI — Drizzle migrations](/stack/cipherstash/cli/install#drizzle-migrations) for details. +See [CipherStash CLI — Drizzle migrations](/reference/cli/install#drizzle-migrations) for details. ### Column storage diff --git a/content/stack/cipherstash/encryption/index.mdx b/content/stack/cipherstash/encryption/index.mdx index aa55580..5fe6c23 100644 --- a/content/stack/cipherstash/encryption/index.mdx +++ b/content/stack/cipherstash/encryption/index.mdx @@ -47,7 +47,7 @@ All key management (key generation, derivation, and isolation) is handled by [Ze ## CipherStash CLI -[CipherStash CLI](/stack/cipherstash/cli) (`stash`) is the dev-time CLI for setting up your database. It handles installing the EQL extension, validating schemas, and managing the encryption lifecycle. Think of it like Drizzle Kit or Prisma CLI: a companion tool that sets up the database while `@cipherstash/stack` handles runtime encryption. +[CipherStash CLI](/reference/cli) (`stash`) is the dev-time CLI for setting up your database. It handles installing the EQL extension, validating schemas, and managing the encryption lifecycle. Think of it like Drizzle Kit or Prisma CLI: a companion tool that sets up the database while `@cipherstash/stack` handles runtime encryption. `stash init` scaffolds the encryption client, installs EQL, and writes `.cipherstash/context.json`. Then run `stash plan` to draft an encryption plan and `stash impl` to execute it. @@ -56,12 +56,12 @@ npx stash init # Interactive project setup (auth, EQL install, clien npx stash plan # Draft a reviewable encryption plan npx stash impl # Execute the plan with a coding agent npx stash db validate # Check schema for misconfigurations -npx stash db status # Show EQL installation state +npx stash eql status # Show EQL installation state ``` - - + + ## Next steps diff --git a/content/stack/cipherstash/encryption/prisma-next.mdx b/content/stack/cipherstash/encryption/prisma-next.mdx index 0ab08f2..f33e31c 100644 --- a/content/stack/cipherstash/encryption/prisma-next.mdx +++ b/content/stack/cipherstash/encryption/prisma-next.mdx @@ -7,7 +7,7 @@ description: Searchable field-level encryption for Postgres with Prisma Next, th CipherStash provides first-class [Prisma Next](https://www.npmjs.com/package/@prisma-next/cli) integration through [`@cipherstash/prisma-next`](https://www.npmjs.com/package/@cipherstash/prisma-next). Declare encrypted columns directly in `schema.prisma` with `cipherstash.Encrypted*()` constructors, and use auto-encrypting query operators that make encrypted queries look like standard Prisma Next code. -The Prisma Next integration has a meaningfully shorter onboarding path than the [Drizzle](/stack/cipherstash/encryption/drizzle) or [Supabase](/stack/cipherstash/encryption/supabase) integrations because the framework's migration system absorbs the database-side install. **You do not run `stash db install` for the EQL bundle** — `prisma-next migration apply` installs the EQL extension in the same control-plane sweep that creates your application tables. +The Prisma Next integration has a meaningfully shorter onboarding path than the [Drizzle](/stack/cipherstash/encryption/drizzle) or [Supabase](/stack/cipherstash/encryption/supabase) integrations because the framework's migration system absorbs the database-side install. **You do not run `stash eql install` for the EQL bundle** — `prisma-next migration apply` installs the EQL extension in the same control-plane sweep that creates your application tables. ## Installation @@ -478,4 +478,4 @@ Found 3 user(s) with emailVerified = true. - [Prisma Next CLI](https://www.npmjs.com/package/@prisma-next/cli). - [EQL reference](/stack/reference/eql-guide) — encrypted operator semantics and search-config index types. - [Indexes](/stack/cipherstash/encryption/indexes) — `unique`, `match`, `ore`, `ste_vec` index family details. -- [CipherStash CLI](/stack/cipherstash/cli) — `stash auth login`, workspace management, secrets. +- [CipherStash CLI](/reference/cli) — `stash auth login`, workspace management, secrets. diff --git a/content/stack/cipherstash/encryption/searchable-encryption.mdx b/content/stack/cipherstash/encryption/searchable-encryption.mdx index f15d179..82302c9 100644 --- a/content/stack/cipherstash/encryption/searchable-encryption.mdx +++ b/content/stack/cipherstash/encryption/searchable-encryption.mdx @@ -25,9 +25,9 @@ The result: your data is encrypted at rest, in transit, and during query evaluat ## Prerequisites -1. Install [EQL](/stack/reference/eql-guide) in your PostgreSQL database using the [CipherStash CLI](/stack/cipherstash/cli): +1. Install [EQL](/stack/reference/eql-guide) in your PostgreSQL database using the [CipherStash CLI](/reference/cli): ```bash - npx stash db install + npx stash eql install ``` 2. Define your encryption schema with the appropriate search indexes 3. Create PostgreSQL indexes on your encrypted columns. See [Setting up indexes](/stack/cipherstash/encryption/indexes) for the correct `CREATE INDEX` syntax for your deployment (self-hosted vs Supabase). diff --git a/content/stack/cipherstash/encryption/storing-data.mdx b/content/stack/cipherstash/encryption/storing-data.mdx index 16270c8..679d12c 100644 --- a/content/stack/cipherstash/encryption/storing-data.mdx +++ b/content/stack/cipherstash/encryption/storing-data.mdx @@ -27,10 +27,10 @@ The Encryption SDK works with any database that supports JSON or JSONB column ty ### Install EQL (optional) -To enable searchable encryption in PostgreSQL, install [EQL](/stack/reference/eql-guide) using the [CipherStash CLI](/stack/cipherstash/cli) so you can use the `eql_v2_encrypted` data type. If you don't need searchable encryption, use `jsonb` instead (you can migrate to EQL later). +To enable searchable encryption in PostgreSQL, install [EQL](/stack/reference/eql-guide) using the [CipherStash CLI](/reference/cli) so you can use the `eql_v2_encrypted` data type. If you don't need searchable encryption, use `jsonb` instead (you can migrate to EQL later). ```bash -npx stash db install +npx stash eql install ``` diff --git a/content/stack/cipherstash/encryption/supabase.mdx b/content/stack/cipherstash/encryption/supabase.mdx index be8851a..c73251b 100644 --- a/content/stack/cipherstash/encryption/supabase.mdx +++ b/content/stack/cipherstash/encryption/supabase.mdx @@ -6,11 +6,11 @@ description: Encrypt, search, and decrypt data with the encryptedSupabase wrappe The `encryptedSupabase` wrapper makes encrypted queries look nearly identical to normal Supabase queries. It automatically handles encryption, decryption, `::jsonb` casts, and search term formatting. - Install [EQL](/stack/cipherstash/supabase#how-this-works) in your Supabase database using the [CipherStash CLI](/stack/cipherstash/cli) so encrypted columns can use the `eql_v2_encrypted` type. + Install [EQL](/stack/cipherstash/supabase#how-this-works) in your Supabase database using the [CipherStash CLI](/reference/cli) so encrypted columns can use the `eql_v2_encrypted` type. ```bash -npx stash db install --supabase +npx stash eql install --supabase ``` The `--supabase` flag installs a Supabase-compatible version of EQL and grants the required permissions on the `eql_v2` schema to `anon`, `authenticated`, and `service_role`. @@ -411,12 +411,12 @@ type EncryptedSupabaseError = { ## Exposing EQL schema for Supabase -If you installed EQL with `npx stash db install --supabase`, the role grants are already applied. You still need to expose the schema in the Supabase dashboard: +If you installed EQL with `npx stash eql install --supabase`, the role grants are already applied. You still need to expose the schema in the Supabase dashboard: Go to [API settings](https://supabase.com/dashboard/project/_/settings/api) and add `eql_v2` to **Exposed schemas**. - If you installed EQL manually (without `--supabase`), you also need to grant permissions. See [CipherStash CLI — Supabase install](/stack/cipherstash/cli/install#supabase-install) for the required grants. + If you installed EQL manually (without `--supabase`), you also need to grant permissions. See [CipherStash CLI — Supabase install](/reference/cli/install#supabase-install) for the required grants. ## How it works diff --git a/content/stack/cipherstash/index.mdx b/content/stack/cipherstash/index.mdx index a6932c3..1765fe1 100644 --- a/content/stack/cipherstash/index.mdx +++ b/content/stack/cipherstash/index.mdx @@ -13,6 +13,6 @@ CipherStash is one product with four capabilities: - **[ZeroKMS](/stack/cipherstash/kms)**: The key management layer. Unique key per value, derived on demand, never stored. Powers everything else. -- **[CLI](/stack/cipherstash/cli)**: CLI tools for managing EQL installation, encryption schemas, and database setup. +- **[CLI](/reference/cli)**: CLI tools for managing EQL installation, encryption schemas, and database setup. Start with the [Quickstart](/stack/quickstart) to encrypt your first fields in 15 minutes. diff --git a/content/stack/cipherstash/supabase.mdx b/content/stack/cipherstash/supabase.mdx index 90a5904..2cec118 100644 --- a/content/stack/cipherstash/supabase.mdx +++ b/content/stack/cipherstash/supabase.mdx @@ -46,7 +46,7 @@ Encrypted values aren't strings or plain JSONB. They're structured ciphertext ob ### What the CLI installs on Supabase -`db install --supabase` uses a Supabase-compatible EQL variant. It omits `CREATE OPERATOR FAMILY` (which requires superuser), and grants `USAGE`, table, routine, and sequence permissions on the `eql_v2` schema to `anon`, `authenticated`, and `service_role`. +`eql install --supabase` uses a Supabase-compatible EQL variant. It omits `CREATE OPERATOR FAMILY` (which requires superuser), and grants `USAGE`, table, routine, and sequence permissions on the `eql_v2` schema to `anon`, `authenticated`, and `service_role`. ## Packages @@ -92,7 +92,7 @@ CipherStash splits its functionality across two packages: a runtime SDK that you ### Control how EQL is installed (optional) - `stash init` installs EQL automatically. If you need to control the install method — for example, to write a Supabase migration file instead of pushing directly — run `stash db install` with explicit flags. + `stash init` installs EQL automatically. If you need to control the install method — for example, to write a Supabase migration file instead of pushing directly — run `stash eql install` with explicit flags. The CLI prompts you to choose how EQL is installed. If a `supabase/migrations/` directory is detected, the migration-file option is pre-selected. @@ -101,7 +101,7 @@ CipherStash splits its functionality across two packages: a runtime SDK that you Pass `--migration` to write the EQL SQL into a Supabase migration file, or choose "Create a Supabase migration file" at the prompt. ```bash - npx stash db install --supabase --migration + npx stash eql install --supabase --migration ``` The CLI writes the EQL SQL to: @@ -115,7 +115,7 @@ CipherStash splits its functionality across two packages: a runtime SDK that you To write the migration file to a different directory, use `--migrations-dir`: ```bash - npx stash db install --supabase --migration --migrations-dir ./db/migrations + npx stash eql install --supabase --migration --migrations-dir ./db/migrations ``` @@ -127,17 +127,17 @@ CipherStash splits its functionality across two packages: a runtime SDK that you Pass `--direct` to push EQL directly to the database without creating a migration file. ```bash - npx stash db install --supabase --direct + npx stash eql install --supabase --direct ``` - Direct-push installs do not survive `supabase db reset`. The reset command drops the database and reruns only files in `supabase/migrations/`. EQL installed directly is not in migrations and will be wiped. Use the migration-file path for projects that use `supabase db reset`. See [Supabase db reset](/stack/cipherstash/cli/troubleshooting#supabase-db-reset). + Direct-push installs do not survive `supabase db reset`. The reset command drops the database and reruns only files in `supabase/migrations/`. EQL installed directly is not in migrations and will be wiped. Use the migration-file path for projects that use `supabase db reset`. See [Supabase db reset](/guides/troubleshooting/cli#supabase-db-reset). - If you hit issues with `supabase db reset` wiping EQL, see [Supabase db reset removes EQL](/stack/cipherstash/cli/troubleshooting#supabase-db-reset). + If you hit issues with `supabase db reset` wiping EQL, see [Supabase db reset removes EQL](/guides/troubleshooting/cli#supabase-db-reset). ## Database schema @@ -252,5 +252,5 @@ Local development uses device-based authentication. Production uses environment - [Supabase JS SDK reference](/stack/cipherstash/encryption/supabase) — Full API for the encryptedSupabase wrapper - [Drizzle ORM reference](/stack/cipherstash/encryption/drizzle) — Encrypted column types and operators - [Searchable encryption](/stack/cipherstash/encryption/searchable-encryption) — How queries over ciphertext work -- [Supabase db reset removes EQL](/stack/cipherstash/cli/troubleshooting#supabase-db-reset) — Fix for direct-push installs +- [Supabase db reset removes EQL](/guides/troubleshooting/cli#supabase-db-reset) — Fix for direct-push installs - [Dashboard](https://dashboard.cipherstash.com/workspaces) — Manage keysets, clients, and access keys diff --git a/content/stack/deploy/testing.mdx b/content/stack/deploy/testing.mdx index 9ba4c92..b5192be 100644 --- a/content/stack/deploy/testing.mdx +++ b/content/stack/deploy/testing.mdx @@ -61,7 +61,7 @@ export function createMockClient() { For integration tests that verify searchable encryption queries, you need: -1. A PostgreSQL database with [EQL](/stack/reference/eql-guide) installed (see [CipherStash CLI](/stack/cipherstash/cli)) +1. A PostgreSQL database with [EQL](/stack/reference/eql-guide) installed (see [CipherStash CLI](/reference/cli)) 2. A test CipherStash workspace 3. Your schema definitions @@ -77,8 +77,8 @@ beforeAll(async () => { pool = new Pool({ connectionString: process.env.TEST_DATABASE_URL }) // EQL must be installed before running tests. - // Run `npx stash db install` against your test database first. - // See: /stack/cipherstash/cli + // Run `npx stash eql install` against your test database first. + // See: /reference/cli // Initialize encryption client with test credentials // Encryption() throws on failure, so wrap in try/catch diff --git a/content/stack/deploy/troubleshooting.mdx b/content/stack/deploy/troubleshooting.mdx index 1042ff9..7ce8c76 100644 --- a/content/stack/deploy/troubleshooting.mdx +++ b/content/stack/deploy/troubleshooting.mdx @@ -87,10 +87,10 @@ If the stored ciphertext has been modified, decryption fails. AES-GCM-SIV provid Searchable encryption requires the [EQL PostgreSQL extension](/stack/reference/eql-guide). Without it, queries against encrypted columns won't work. -**Fix**: Install EQL using the [CipherStash CLI](/stack/cipherstash/cli): +**Fix**: Install EQL using the [CipherStash CLI](/reference/cli): ```bash -npx stash db install +npx stash eql install ``` ### Wrong query type diff --git a/content/stack/reference/agent-skills.mdx b/content/stack/reference/agent-skills.mdx index dbafbdd..de4114b 100644 --- a/content/stack/reference/agent-skills.mdx +++ b/content/stack/reference/agent-skills.mdx @@ -56,7 +56,7 @@ The CipherStash CLI (`stash`) for database setup, schema management, and project - `stash.config.ts` configuration - Setup lifecycle: `init` (scaffold + EQL + context), `plan` (draft plan.md), `impl` (execute plan), `status` (lifecycle map) -- Database commands: `db install`, `db upgrade`, `db push`, `db validate`, `db status`, `db test-connection` +- Database commands: `eql install`, `eql upgrade`, `db push`, `db validate`, `eql status`, `db test-connection` - Schema building with `schema build` - Authentication with `auth login` - Programmatic API (`EQLInstaller`, `loadStashConfig`, `defineConfig`, `loadBundledEqlSql`) @@ -67,7 +67,7 @@ The CipherStash CLI (`stash`) for database setup, schema management, and project **When it activates:** Your agent loads this skill when you are working with `stash.config.ts`, running CLI commands, or setting up EQL in a database. -**Related docs:** [CipherStash CLI](/stack/cipherstash/cli) +**Related docs:** [CipherStash CLI](/reference/cli) ### stash-drizzle diff --git a/content/stack/reference/dashboard-supabase-integration.mdx b/content/stack/reference/dashboard-supabase-integration.mdx index c8dd753..e958309 100644 --- a/content/stack/reference/dashboard-supabase-integration.mdx +++ b/content/stack/reference/dashboard-supabase-integration.mdx @@ -80,7 +80,7 @@ For the selected project, the dashboard verifies: When project health, EQL, and OIDC are all satisfied, the hub shows a **Stack-ready** badge. - EQL detection uses `eql_v2.version()`, not a `pg_extension` lookup. If EQL is missing, run `npx stash db install --supabase --migration` in your application repo. + EQL detection uses `eql_v2.version()`, not a `pg_extension` lookup. If EQL is missing, run `npx stash eql install --supabase --migration` in your application repo. ### Configure OIDC from the dashboard @@ -106,7 +106,7 @@ npm install @cipherstash/stack npm install -D stash npx stash auth login npx stash init --supabase -npx stash db install --supabase --migration +npx stash eql install --supabase --migration ``` It also generates a `.env.local` snippet for the selected project, including: diff --git a/content/stack/reference/drizzle.mdx b/content/stack/reference/drizzle.mdx index c7d67bd..0b88e15 100644 --- a/content/stack/reference/drizzle.mdx +++ b/content/stack/reference/drizzle.mdx @@ -115,12 +115,12 @@ const results = await db Run the migration generator after defining your table: ```bash -npx @cipherstash/cli db install +npx @cipherstash/cli eql install ``` The CLI reads your Drizzle config and calls `extractEncryptionSchema` internally to determine which columns need EQL indexes. It then produces a timestamped SQL migration file in your Drizzle migrations directory. -See the [CipherStash CLI reference](/stack/cipherstash/cli) for all `db install` options. +See the [CipherStash CLI reference](/reference/cli) for all `eql install` options. ## Cross-links