CLI Reference

@wocha/cli is the command-line tool for Wocha developer workflows: scaffolding auth in existing projects, running a local sandbox server, validating configuration, seeding test data, testing webhooks, and migrating users from other providers.

Installation

Install globally:

pnpm add -g @wocha/cli

npx @wocha/cli init --framework nextjs

Or run without installing:

npx @wocha/cli

Verify the install:

wocha --version
wocha help

Quick start

From your project root:

npx @wocha/cli init

The wizard detects your framework, installs the right SDK, generates starter files, and can auto-provision an OAuth application when you provide a Management API key.

For instant local development with zero cloud setup:

npx @wocha/cli init --sandbox
wocha dev

Commands

wocha init

Interactive setup wizard that scaffolds Wocha auth in an existing project.

Supported frameworks: Next.js, React SPA, Vue, Nuxt, SvelteKit, Remix, Express/Node.js, and Other (Management API only).

The CLI auto-detects your stack from package.json and lockfiles, installs the matching @wocha/* package, and writes framework-specific starter files (route handlers, middleware, env files, providers).

Init modes:

Non-interactive example (Next.js on Wocha Cloud):

npx @wocha/cli init -y \
  --tenant acme \
  --framework nextjs \
  --client-id "$WOCHA_CLIENT_ID" \
  --client-secret "$WOCHA_CLIENT_SECRET"

Sandbox example:

npx @wocha/cli init --sandbox --framework nextjs -y

wocha dev

Starts a lightweight sandbox auth server for local development. The server exposes OIDC endpoints (/oauth/authorize, /oauth/token, /userinfo, /.well-known/jwks.json) with locally signed RS256 tokens.

wocha dev

Run in a separate terminal after wocha init --sandbox. Your app uses the sandbox issuer URL and pre-configured client credentials written during init.

Options:

Subcommands:

wocha dev stack    # Start full Docker stack (Kratos, Hydra, SpiceDB)
wocha dev stop     # Stop the Docker development stack

Env vars written by --write-env:

WOCHA_SANDBOX=true
WOCHA_ISSUER=http://localhost:4000
WOCHA_CLIENT_ID=wocha-sandbox
WOCHA_CLIENT_SECRET=wocha-sandbox-secret-dev-only

Non-production only — do not use sandbox mode in staging or production.

wocha doctor

Diagnoses common integration issues without starting your app.

wocha doctor

Checks performed:

• Required environment variables (with alias support)
• Installed @wocha/* packages and version currency
• Tenant API connectivity (GET /api/v1/health)
• Management API key validity
• Framework detection and auth route files (Next.js middleware, auth handler)
• OIDC discovery, JWKS, token, and authorization endpoints
• Local auth login route (/api/auth/login)

Fix any failures reported before debugging in your application code.

wocha seed

Provisions organisations, users, roles, permissions, and OAuth applications from a YAML seed file. Idempotent — existing resources are skipped.

wocha seed
wocha seed --file ./config/staging.seed.yaml

Requires: WOCHA_MANAGEMENT_API_KEY (or WOCHA_API_KEY) and WOCHA_TENANT_SLUG (or WOCHA_TENANT).

Example wocha.seed.yaml:

organisations:
  - slug: acme
    display_name: Acme Corporation
 
users:
  - email: admin@acme.example
    password: ChangeMe-Dev-Only-123!
    name: Acme Admin
    org_slug: acme
    org_role: owner
 
applications:
  - client_name: Acme Local Dev
    redirect_uris:
      - http://localhost:3000/api/auth/callback
    grant_types:
      - authorization_code
      - refresh_token
    response_types:
      - code
    token_endpoint_auth_method: client_secret_basic

wocha webhook listen

Local webhook receiver with automatic public tunnel URL, temporary subscriber registration, and signature verification.

wocha webhook listen
wocha webhook listen --events user.created,session.created
wocha webhook listen --forward-to http://localhost:3000/api/webhooks/wocha

Options:

Tunnel priority: existing ngrok → Cloudflare Quick Tunnel (cloudflared) → Wocha relay (tunnel.wocha.ai).

Requires: WOCHA_MANAGEMENT_API_KEY and WOCHA_TENANT_SLUG. Optional WOCHA_API_BASE_URL for self-hosted tenants.

wocha webhook test

Sends a signed test webhook payload to any endpoint — useful for unit testing handlers without a live tenant.

wocha webhook test http://localhost:3000/api/webhooks/wocha user.created
wocha webhook test https://example.com/hooks/wocha session.revoked --secret whsec_abc

Supported event types include user.created, user.updated, session.created, session.revoked, org.created, connection.created, and more. Run wocha webhook test --help for the full list.

wocha migrate

Imports users from Auth0, Clerk, or Firebase into Wocha.

wocha migrate auth0
wocha migrate clerk --dry-run
wocha migrate firebase --batch-size 50

Options:

The command prompts for provider credentials interactively (Auth0 domain + Management API token, Clerk secret key, or Firebase export JSON path).

Configuration

Project config (.wocha/)

CLI project state is stored under .wocha/ (there is no separate .greetrc file):

Example .wocha/config.json:

{
  "active_environment": "staging"
}

Infrastructure-as-code exports live in .wocha/ when using wocha config pull (YAML files per resource type with a manifest.yaml).

Environment variables

The CLI reads from .env, .env.local, and .env.development (merged with process.env).

WOCHA_CLIENT_ID=your-client-id
WOCHA_CLIENT_SECRET=your-client-secret
WOCHA_ISSUER=https://your-tenant.auth.wocha.ai
WOCHA_API_URL=https://your-tenant.api.wocha.ai  # optional

Common aliases accepted by wocha doctor and other commands: WOCHA_TENANT_SLUG, WOCHA_ISSUER_URL, WOCHA_MANAGEMENT_API_KEY.

Common workflows

New Next.js app (fastest path)

npx @wocha/cli init --sandbox --framework nextjs -y
wocha dev          # terminal 1
npm run dev        # terminal 2 — visit /api/auth/login

CI scaffolding

npx @wocha/cli init -y \
  --tenant "$WOCHA_TENANT" \
  --framework nextjs \
  --api-key "$WOCHA_API_KEY" \
  --auto-provision
wocha doctor

Webhook development loop

# Terminal 1 — receive live events from your tenant
wocha webhook listen --forward-to http://localhost:3000/api/webhooks/wocha
 
# Terminal 2 — send a one-off test payload
wocha webhook test http://localhost:3000/api/webhooks/wocha user.created

Staging data setup

export WOCHA_TENANT=staging
export WOCHA_API_KEY=wocha_mgmt_...
wocha seed --file ./wocha.seed.yaml

Other commands

Learn more

• Getting started
• Testing library — mock providers and E2E tokens
• Webhooks overview