CLI Reference

The corral CLI is how you scaffold, configure, and manage your Corral installation. Every command supports --json for machine-readable output and --help for usage info.

Installation

Use npm create corral@latest to install/run the latest scaffolder and then run corral <command> inside your project. All commands support --json.

Global Flags

These flags work on every command:

Flag	Description
`--json`	Output structured JSON. Exit code 0 = success, 1 = error.
`--config <path>`	Path to `corral.yaml` (default: `./corral.yaml`)
`--env <name>`	Load `.env.<name>` (e.g. `--env production`)
`--yes`	Skip all interactive prompts, accept defaults
`--no-color`	Disable color output
`--verbose`	Show debug output
`--help`	Show help for this command

Command Catalog (18 commands in v0.4.1)

bash

corral init
corral add feature|plan|provider|meter
corral doctor
corral stripe sync   # alias: corral stripe push
corral deploy docker|fly|railway|render
corral dev
corral seed
corral test
corral validate
corral config validate|edit|set|diff
corral users list|create|set-plan
corral backup now|list|restore
corral status
corral analyze
corral verify
corral llms-txt
corral rollback

init

Scaffold Corral into an existing project. Analyzes your project and generates all necessary files.

bash

npx corral init [options]

Options:
  --framework <name>   Force framework (nextjs|express|hono|fastify|vite)
  --db <adapter>       Force database adapter (prisma|drizzle|sqlite|postgres)
  --no-billing         Skip Stripe setup
  --no-admin           Skip admin page generation
  --yes                Accept all defaults (agent mode)
  --output <dir>       Output directory (default: cwd)

corral init --yes --json

corral init --yes --json { "status": "ok", "framework": "nextjs", "files_created": [ "corral.yaml", "src/app/api/auth/[...corral]/route.ts", "src/app/api/billing/[...corral]/route.ts", "src/lib/corral.ts", "CORRAL.md" ], "next_steps": ["npm install @corral/core @corral/next", "corral validate"] }

analyze

Analyze a project's structure and report what Corral would detect. Read-only — writes nothing.

bash

corral analyze [path] [options]

Options:
  --json   Output structured detection report

corral analyze --json { "framework": "nextjs", "router": "app", "typescript": true, "database": "prisma", "existing_auth": null, "existing_billing": null, "corral_installed": false, "recommended_adapters": ["@corral/core", "@corral/next"] }

add

Incrementally add capabilities to an existing Corral installation. All add subcommands are idempotent — safe to run multiple times.

add subcommands

corral add page <path> [--gate <feature>] [--plan <plan>]

Add a new gated page to the app.

bash

corral add page /reports/advanced --gate ai_analysis --plan pro
# Creates src/app/reports/advanced/page.tsx with PageGate wrapper

corral add feature <name> --plans <list> [--gate <mode>]

Define a new feature gate in corral.yaml.

bash

corral add feature ai_analysis --plans pro,enterprise --gate blur
corral add feature bulk_export --plans enterprise --gate block

corral add meter <name> [--limit <n>] [--window <period>] [--overage <mode>]

Add a usage meter with per-plan limits.

bash

corral add meter api_calls \
  --free 500 --pro 10000 --enterprise unlimited \
  --window month --overage block

corral add provider <name> [--scopes <list>]

Add an auth provider. Updates corral.yaml and generates OAuth callback routes.

bash

corral add provider google
corral add provider github --scopes read:user,user:email
corral add provider saml --metadata-url https://idp.example.com/metadata

corral add plan <name> [--price <n>] [--interval month|year] [--trial <days>]

Add a billing plan. Run corral stripe push after to sync to Stripe.

bash

corral add plan pro --price 49 --interval month --trial 14
corral add plan annual --price 490 --interval year --inherits pro

corral add webhook <event> [--handler <path>]

Add a Stripe webhook handler.

bash

corral add webhook customer.subscription.updated
corral add webhook invoice.payment_failed --handler src/handlers/invoice-failed.ts

corral add device-verify [--page <path>]

Generate the device auth approval page (user enters code from CLI).

bash

corral add device-verify --page /auth/activate

corral add admin-page [--path <route>]

Generate the admin dashboard page at the specified route.

bash

corral add admin-page --path /admin

validate

Validate the corral.yaml config against live state: environment variables, database connectivity, Stripe product sync, and feature consistency.

bash

corral validate [options]

Options:
  --strict     Fail on warnings (for CI)
  --json       Structured output
  --env <name> Environment to validate against

corral validate --strict --json { "status": "ok", "checks": { "config_syntax": "pass", "env_vars": "pass", "database": "pass", "stripe_products": "pass", "feature_gates": "pass" }, "warnings": [], "errors": [] }

doctor

Deep health check: validates config, tests all provider connections, checks for known misconfigurations and version mismatches.

bash

corral doctor

# Output:
# ✓ corral.yaml valid
# ✓ @corral/core v0.4.1 matches CLI v0.4.1
# ✓ Database connection OK
# ✓ Google OAuth: client_id set, callback URL registered
# ✗ SMTP: connection refused at smtp.example.com:587
#   → Fix: check SMTP_URL in .env.local

status

Show the current state of Corral in the running app (plan counts, active meters, recent auth events).

bash

corral status [--json] [--env <name>]

# Output:
# Users:     1,284 total  (47 new this week)
# Plans:     free=892  pro=347  enterprise=45
# Meters:    api_calls=89,234/1,000,000 this month
# Stripe:    live mode, webhooks OK
# Last auth: 3 minutes ago

rollback

Rollback to the previous corral.yaml state. Corral keeps a history of config snapshots (default: 10).

bash

corral rollback [--to <snapshot-id>] [--list] [--json]

# List available snapshots:
corral rollback --list

# Rollback to previous:
corral rollback

# Rollback to specific snapshot:
corral rollback --to snap_2024-01-15_14-23

stripe

Commands for managing Stripe integration.

stripe subcommands

corral stripe push [--dry-run]

Sync corral.yaml plans to Stripe. Creates or updates Products and Prices. Writes price IDs to env.

bash

corral stripe push
corral stripe push --dry-run    # preview changes without applying
corral stripe push --env production

corral stripe verify

Verify that Stripe products + prices match corral.yaml. Reports drift.

corral stripe test [--plan <name>] [--email <email>]

Run a test checkout + webhook cycle using Stripe test mode. Useful in CI.

bash

corral stripe test --plan pro --email test@horizon.mil

seed

Seed test users into the database. Useful for development and CI.

bash

corral seed [options]

Options:
  --env <name>     Environment (default: development)
  --count <n>      Number of users per plan (default: 3)
  --plan <name>    Seed only this plan
  --reset          Delete all test users first
  --json           Structured output with created user IDs

# Example: seed 5 users per plan
corral seed --count 5 --json

# Output:
# Created user: alice@horizon-test.com (plan: free)
# Created user: bob@horizon-test.com (plan: pro)
# Created user: carol@horizon-test.com (plan: enterprise)
# Created user: admin@horizon-test.com (role: admin)

dev

Run a development server for Corral's auth + billing routes independently of your app. Useful when testing the auth flow in isolation or when your app's dev server conflicts with Corral's routes.

bash

corral dev [options]

Options:
  --port <n>       Port to listen on (default: 3001)
  --host <host>    Host to bind to (default: localhost)
  --watch          Watch corral.yaml for changes and reload

# Example:
corral dev --port 3001 --watch

# Corral dev server running at http://localhost:3001
# Auth:    http://localhost:3001/api/auth
# Billing: http://localhost:3001/api/billing
# Admin:   http://localhost:3001/admin
# llms.txt: http://localhost:3001/api/llms.txt

deploy

Generate deployment config for supported targets.

bash

corral deploy docker
corral deploy fly
corral deploy railway
corral deploy render

verify

Verify that generated auth + billing endpoints are reachable and correctly wired.

bash

corral verify --json

test

Run auth smoke tests for signup/signin/session/gating flows.

bash

corral test --json

config

bash

corral config validate
corral config edit
corral config set app.url https://example.com
corral config diff

users

bash

corral users list
corral users create --email dev@example.com --plan free
corral users set-plan --email dev@example.com --plan pro

backup

bash

corral backup now
corral backup list
corral backup restore --id bkp_2026_02_17

llms-txt

Generate (or print) the llms.txt for the current project. This is also auto-served at /api/llms.txt when your app is running.

bash

corral llms-txt [options]

Options:
  --output <path>   Write to file instead of stdout
  --full            Generate llms-full.txt (extended version with examples)
  --update          Regenerate and overwrite CORRAL.md in project root

# Examples:
corral llms-txt                        # print to stdout
corral llms-txt --output llms.txt      # write to file
corral llms-txt --full --output llms-full.txt
corral llms-txt --update               # refresh CORRAL.md