CLI

Always use the CLI to set up and maintain kavach. Never hand-write kavach.config.js, vite patches, or hooks files.

For AI agents: Never hand-craft kavach integration files. Use npx kavach init for first-time setup and npx kavach doctor --fix to repair existing setups. Hand-written files are the most common source of broken integrations.

kavach init

Scaffolds a complete kavach setup. Run once per project from the SvelteKit project root.

# run from your SvelteKit project root
npx kavach init
# or with bun
bunx kavach init

Interactive prompts

Choose adapter — supabase | firebase | auth0 | amplify | convex
Choose providers — email/password, magic link, Google, GitHub, etc.
Configure data route (optional, adapter-dependent)
Configure RPC route (optional, adapter-dependent)
Configure logging (optional, adapter-dependent)
Set auth route path (default: (public)/auth)
Set logout route (default: /logout)
Enable cached logins
Define route protection rules

Files generated / patched

kavach.config.js                        adapter, providers, rules, env var names
vite.config.js                          kavach() plugin injected before sveltekit()
src/hooks.server.js                     kavach.handle registered
src/routes/+layout.server.js            session: locals.session passed to pages
src/routes/(public)/auth/+page.svelte   auth page with configured providers
.env                                    env var keys added (values left empty)

kavach doctor

Validates an existing kavach integration and optionally auto-repairs fixable issues. Use this after kavach init, after manual changes, or when diagnosing a broken setup.

npx kavach doctor        # check only — no changes made
npx kavach doctor --fix  # check and auto-repair fixable issues

Checks performed

#	Check	Auto-fixable
1	kavach.config.js exists with adapter, env, rules	No — run kavach init
2	vite.config.js has kavach() from @kavach/vite before sveltekit()	Yes
3	hooks.server imports $kavach/auth and exports kavach.handle	Yes
4	+layout.server passes session: locals.session	Yes
5	All env keys from config exist in .env	Yes — adds empty keys
6	.env values are non-empty	No — prints set KEY=<value> instruction
7	Adapter + kavach packages in package.json	Yes — installs missing

Example output

  ✓ kavach.config.js — valid
  ✗ vite.config.js — kavach() plugin missing
      Run kavach doctor --fix
  ✗ hooks.server.ts — must import from '$kavach/auth' and export kavach.handle
      Run kavach doctor --fix
  ✓ +layout.server.ts — valid
  ✗ .env — empty values: PUBLIC_SUPABASE_URL
      set PUBLIC_SUPABASE_URL=<your-value> in .env
  ✓ dependencies — all installed

  3 issues found. Run kavach doctor --fix to repair what can be fixed automatically.

After running with --fix:

  ✓ kavach.config.js — valid
  ✔ vite.config.js — patched
  ✔ hooks.server.ts — patched
  ✓ +layout.server.ts — valid
  ✗ .env — empty values: PUBLIC_SUPABASE_URL
      set PUBLIC_SUPABASE_URL=<your-value> in .env
  ✓ dependencies — all installed

  1 issue requires manual action — see above.

kavach add

Add components to an existing setup.

npx kavach add auth-page   # auth page with configured providers
npx kavach add routes      # data and RPC route handlers

Command	Generates
`kavach add auth-page`	Auth page with all configured providers using `<AuthPage />`
`kavach add routes`	Data and RPC route handlers under configured paths

Anti-patterns

These patterns look reasonable but cause broken integrations. The CLI avoids them automatically.

// ✗ No default export — will throw at runtime
import kavach from 'kavach'

// ✗ Don't call createKavach in hooks.server — $kavach/auth already has a configured instance
import { createKavach } from 'kavach'
export const handle = createKavach(adapter).handle

// ✗ Do not alias the kavach package in vite.config
resolve: { alias: { kavach: '/path/to/src/index.ts' } }

// ✗ Not needed — $kavach/auth handles SSR bundling
ssr: { noExternal: ['kavach'] }

// ✓ Always use the virtual module in hooks.server
import { kavach } from '$kavach/auth'
export const handle = kavach.handle

Verifying your setup

After kavach init or any manual changes:

npx kavach doctor

All 7 checks should show ✓. If any show ✗, run kavach doctor --fix and follow the printed instructions for any remaining manual items.