@wocha/cli

Command-line tool for scaffolding Wocha authentication in existing projects. Detects your framework, installs the right SDK, and generates starter files.

Quick start

From your project root:

npx @wocha/cli init

The interactive wizard will:

1. Ask whether you use Wocha Cloud or a self-hosted instance
2. Collect your tenant slug or custom base URL
3. Prompt for credentials relevant to your framework
4. Detect your framework (or let you choose manually)
5. Install the appropriate SDK and generate starter files
6. Validate connectivity to your Wocha instance

Supported frameworks

| Framework | SDK installed | Auth model | |-----------|---------------|------------| | Next.js | @wocha/nextjs | OAuth BFF (confidential client) | | React SPA (Vite) | @wocha/react | OAuth PKCE (public client) | | React SPA (CRA) | @wocha/react | OAuth PKCE (public client) | | Vue | @wocha/vue | OAuth PKCE (public client) | | Nuxt | @wocha/nuxt | OAuth BFF (confidential client) | | SvelteKit | @wocha/sveltekit | OAuth BFF (confidential client) | | Remix | @wocha/remix | OAuth BFF (confidential client) | | Express / Node.js | @wocha/sdk | Management API (API key) | | Other | @wocha/sdk | Management API (API key) |

The CLI auto-detects Next.js, Vite, Create React App, Vue, Nuxt, SvelteKit, Remix, and Express from your package.json and config files. Each detected framework is fully scaffolded with env files and starter routes.

Generated files

Next.js

| File | Purpose | |------|---------| | .env.local | WOCHA_CLIENT_ID, WOCHA_CLIENT_SECRET, WOCHA_ISSUER | | app/api/auth/[...wocha]/route.ts | OAuth route handler (login, callback, logout, session, refresh, switch-org) | | middleware.ts | Route protection with withWochaAuth() | | app/providers.tsx | Client wrapper with WochaSessionProvider |

After scaffolding, set your OAuth credentials in .env.local and visit /api/auth/login to test.

React SPA (Vite or CRA)

| File | Purpose | |------|---------| | .env | VITE_WOCHA_ISSUER / REACT_APP_WOCHA_ISSUER and *_WOCHA_CLIENT_ID | | src/wocha-provider.tsx | WochaProvider wrapper with config from env vars | | src/pages/callback.tsx (or src/callback.tsx) | OAuth callback page |

Wire AppWithWochaAuth into your root component and add the callback route to your router.

Vue

| File | Purpose | |------|---------| | .env | VITE_WOCHA_ISSUER, VITE_WOCHA_CLIENT_ID | | src/main.ts | WochaProvider wrapper | | src/callback.vue | OAuth callback page |

Nuxt

| File | Purpose | |------|---------| | .env | WOCHA_CLIENT_ID, WOCHA_CLIENT_SECRET, WOCHA_ISSUER | | nuxt.config.ts | @wocha/nuxt module configuration |

SvelteKit

| File | Purpose | |------|---------| | .env | WOCHA_CLIENT_ID, WOCHA_CLIENT_SECRET, WOCHA_ISSUER | | src/hooks.server.ts | Server-side session handling | | src/routes/auth/[...wocha]/+server.ts | OAuth route handler |

Remix

| File | Purpose | |------|---------| | .env | WOCHA_CLIENT_ID, WOCHA_CLIENT_SECRET, WOCHA_ISSUER | | app/routes/auth.$.tsx | OAuth route handler (login, callback, logout) |

Express / Other

| File | Purpose | |------|---------| | .env | WOCHA_TENANT, WOCHA_API_KEY | | wocha-client.ts | Pre-configured WochaClient instance |

Import wocha in your server code to manage users, sessions, permissions, and webhooks.

Auto-provisioning

When you provide a Management API key, the CLI can create an OAuth application for your project automatically:

Would you like Wocha to create an OAuth application for this project? (Y/n)

If you accept, the CLI calls the Management API to create an application with the correct grant types, redirect URIs, and response types for your detected framework, then writes the resulting client_id (and client_secret for Next.js) directly into your .env file.

This removes the manual step of creating an OAuth client in the Console and copying credentials.

Self-hosted vs Wocha Cloud

Wocha Cloud

Provide your tenant slug (e.g. my-company). The CLI resolves:

• Issuer: https://my-company.auth.wocha.ai
• API URL: https://my-company.api.wocha.ai

Self-hosted

Provide a custom base URL (e.g. https://auth.internal.example.com). The same URL is used for both issuer and API unless you configure them separately in your generated env file.

For React SPAs, also set apiUrl in the provider config if your Platform API is on a different host:

const config = {
  issuer: import.meta.env.VITE_WOCHA_ISSUER,
  clientId: import.meta.env.VITE_WOCHA_CLIENT_ID,
  redirectUri: window.location.origin + "/callback",
  apiUrl: import.meta.env.VITE_WOCHA_API_URL,
};

Package manager detection

The CLI detects your package manager from lockfiles and uses it for SDK installation:

| Lockfile | Command | |----------|---------| | pnpm-lock.yaml | pnpm add | | yarn.lock | yarn add | | bun.lockb | bun add | | (none) | npm install |

Commands

npx @wocha/cli init    # Interactive setup wizard
npx @wocha/cli help    # Show usage

Non-interactive mode

Pass flags to skip prompts — useful for CI or scripted setup. Combine with --yes / -y to accept defaults without confirmation.

npx @wocha/cli init \
  --yes \
  --tenant my-company \
  --framework nextjs \
  --client-id "$WOCHA_CLIENT_ID" \
  --client-secret "$WOCHA_CLIENT_SECRET"

Flags

| Flag | Description | |------|-------------| | --tenant <slug> | Wocha Cloud tenant slug (required unless --base-url is set) | | --base-url <url> | Self-hosted auth issuer URL (implies self-hosted mode) | | --api-url <url> | Self-hosted Platform API base URL (defaults to --base-url if omitted) | | --framework <name> | Target framework: nextjs, react-spa, vue, nuxt, sveltekit, remix, express, or other | | --client-id <id> | OAuth client ID (required for OAuth frameworks) | | --client-secret <s> | OAuth client secret (required for nextjs, nuxt, sveltekit, and remix) | | --api-key <key> | Management API key (required for express / other; optional for OAuth frameworks when validating or auto-provisioning) | | --auto-provision | Create an OAuth application via the Management API (requires --api-key; uses default app name and redirect URI) | | --yes, -y | Skip confirmation prompts (does not enable auto-provision — use --auto-provision explicitly) |

Examples:

# React SPA on Wocha Cloud
npx @wocha/cli init -y --tenant acme --framework react-spa --client-id "$CLIENT_ID"

# Self-hosted Express app
npx @wocha/cli init -y \
  --base-url https://auth.internal.example.com \
  --api-url https://api.internal.example.com \
  --framework express \
  --api-key "$WOCHA_API_KEY"

# Next.js with auto-provisioned OAuth app
npx @wocha/cli init -y \
  --tenant acme \
  --framework nextjs \
  --api-key "$WOCHA_API_KEY" \
  --auto-provision

Related documentation

• React SDK
• Next.js SDK
• TypeScript SDK
• SDK overview