# Kavach — CLI (@kavach/cli)

> Scaffolding CLI for adding and maintaining Kavach in SvelteKit projects.
> Always use the CLI — never hand-write config files or patches.

## IMPORTANT — For AI Agents

Never hand-craft kavach integration files. The CLI is the only supported path.

    npx kavach init            # first-time setup
    npx kavach doctor          # verify existing setup
    npx kavach doctor --fix    # auto-repair issues

## Install

    npm install -g @kavach/cli
    # or without installing:
    npx kavach <command>
    bunx kavach <command>

## Commands

### kavach init

Scaffolds a complete kavach setup from the SvelteKit project root.

    npx kavach init

Interactive prompts:
1. Choose adapter: supabase | firebase | auth0 | amplify | convex
2. Choose providers: email/password, magic link, Google, GitHub, etc.
3. Configure data route (optional, adapter-dependent)
4. Configure RPC route (optional, adapter-dependent)
5. Configure logging (optional, adapter-dependent)
6. Set auth route path (default: (public)/auth)
7. Set logout route (default: /logout)
8. Enable cached logins
9. 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 providers
- .env — env var keys added with empty values

### kavach doctor [--fix]

Validates an existing kavach integration. Use after init, after manual changes,
or when diagnosing a broken setup.

    npx kavach doctor        # check only
    npx kavach doctor --fix  # check and auto-repair

Checks:

| # | 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> instructions |
| 7 | Adapter + kavach packages in package.json | Yes — installs missing |

Example output:

    kavach doctor

      ✓ 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 --fix:

    kavach doctor --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

Adds components to an existing setup.

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

## Anti-Patterns

    // No default export — will throw
    import kavach from 'kavach'

    // Don't call createKavach in hooks.server
    import { createKavach } from 'kavach'

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

    // Not needed when using $kavach/auth
    ssr: { noExternal: ['kavach'] }

    // Correct
    import { kavach } from '$kavach/auth'
    export const handle = kavach.handle

## Verifying Your Setup

    npx kavach doctor

All 7 checks should show ✓. If any show ✗:
- Run npx kavach doctor --fix for auto-fixable issues
- For env value issues: set the values in .env manually

## Related

- [Auth](./auth.txt) — manual setup reference and API
- [Vite Plugin](./vite.txt) — kavach.config.js reference