Quickstart

Add auth + billing + feature gating to your app in under 10 minutes. We'll use HORIZON (a Next.js military intel dashboard) as the example throughout.

Prerequisites

Node.js 18+, an existing app (Next.js, Express, Hono, etc.), and optionally a Stripe account (test mode works). You don't need Stripe to start — free-plan gating works without it.

Step 1 — Initialize Corral

Start with npm create corral@latest, then run corral init in your project root. The CLI analyzes your project structure, detects your framework and database, and scaffolds everything.

~/projects/horizon

npm create corral@latest ? What do you want to do? Initialize Corral in an existing app ? Project path: . corral init Analyzing project structure… Detected: Next.js 14.2, TypeScript, PostgreSQL (Prisma) ? App name: HORIZON ? Auth providers: Google, Email magic link ? Add billing (Stripe)? Yes ? Plans: free, pro ($49/mo), enterprise (custom) Created corral.yaml Created src/app/api/auth/[...corral]/route.ts Created src/app/api/billing/[...corral]/route.ts Created src/lib/corral.ts Created src/components/corral/FeatureGate.tsx Created src/components/corral/PlanGate.tsx Created src/components/corral/AuthGate.tsx Created src/components/corral/PageGate.tsx Created src/app/admin/page.tsx Created CORRAL.md Added to .env.local: CORRAL_SECRET, STRIPE_SECRET_KEY (placeholder) Feature showcase: auth, billing, gates, admin UI, llms.txt, and agent checklist ready Done in 1.2s. Next: edit corral.yaml, then npm run dev.

Install the generated dependencies:

bash

npm install @corral/core @corral/next

What detection looks like (v0.4.1)

text

Detected framework: Next.js (App Router)
Detected database: PostgreSQL
Detected package manager: npm
Detected monorepo: no
Generated: auth routes, billing routes, AdminPanel, ProfilePage, AccountMenu, gates.tsx, auth-context.tsx, CORRAL.md, .corral/agent-checklist.json, llms-agent-prompt.md

Copy-paste prompt for your coding agent

prompt

Add Corral auth + billing to this app using v0.4.1 defaults.
Run: npm create corral@latest, then corral init.
Plans: free, pro ($49/mo, 14-day trial), enterprise (custom).
Gate ai_analysis to pro+ with blur preview for free users.
After changes run: corral validate --json and corral doctor --json.

Step 2 — Edit corral.yaml

The generated corral.yaml is a starting point. Customize it for HORIZON's needs — add providers, define plans, gate features:

        corral.yaml
        yaml
      

app:
  name: HORIZON
  url: https://horizon.mil
  description: Military intelligence dashboard

# Auth providers — each one generates login UI + session handling
auth:
  session_ttl: 7d
  providers:
    - google
    - email:
        magic_link: true
        otp: false
    - device  # CLI auth for HORIZON's own CLI

# Billing plans — synced to Stripe with `corral stripe push`
plans:
  free:
    price: 0
    description: Basic access. No credit card required.
  pro:
    price: 49
    interval: month
    description: Full analysis suite for analysts.
    trial_days: 14
  enterprise:
    price: custom
    description: Air-gapped deployment + custom SLA.

# Features — map to plans, define gate behavior
features:
  basic_search:
    plans: [free, pro, enterprise]
  export_csv:
    plans: [free, pro, enterprise]
  ai_analysis:
    plans: [pro, enterprise]
    gate: blur        # show blurred preview to free users
  real_time_feed:
    plans: [pro, enterprise]
    gate: skeleton    # show skeleton loader to free users
  bulk_export:
    plans: [enterprise]
    gate: block       # hard block with upgrade CTA
  admin_console:
    roles: [admin]      # role-based, not plan-based

# Usage meters — track consumption, enforce limits
meters:
  api_calls:
    plans:
      free: 500
      pro: 10000
      enterprise: unlimited
    window: month
    overage: block      # or: charge, warn
  export_rows:
    plans:
      free: 1000
      pro: 100000
    window: month
    overage: warn

# Database — Corral shares your app's database
database:
  adapter: prisma
  url: env:DATABASE_URL

# Admin page
admin:
  enabled: true
  path: /admin
  roles: [admin]

Step 3 — Run your app

Corral mounts its routes during your app's startup. No separate process needed — just run your app as normal:

~/projects/horizon

npm run dev ▲ Next.js 14.2.0 - Local: http://localhost:3000 🦙 Corral initialized (3 providers, 3 plans, 6 features) Auth: http://localhost:3000/api/auth Billing: http://localhost:3000/api/billing Admin: http://localhost:3000/admin llms.txt: http://localhost:3000/api/llms.txt ✓ Ready in 892ms

Visit http://localhost:3000/api/auth/signin to see your login page. Corral has auto-generated UI for every configured provider.

Step 4 — Validate your config

corral validate checks your YAML against live state — providers, plan definitions, feature gates, and database connectivity:

~/projects/horizon

corral validate Config Syntax valid Schema valid (corral@0.1) Auth provider: google → GOOGLE_CLIENT_ID ✓ GOOGLE_CLIENT_SECRET ✓ provider: email → SMTP_URL ✓ provider: device → no secrets needed Plans free → $0/mo (3 features) pro → $49/mo (6 features) enterprise → custom (6 features) Database Connection: OK (pg 16.2) Migrations: up to date All checks passed ✓

Step 5 — Sync to Stripe

If you added billing plans, push them to Stripe with one command. This creates Products and Prices in Stripe and writes the price IDs back into your YAML (or .env if you prefer):

~/projects/horizon

corral stripe push Using STRIPE_SECRET_KEY (test mode) Created product: HORIZON Pro → prod_QxK9mN2aLp Created price: $49/mo → price_1OvK9mN2aLp8xQJ Created product: HORIZON Enterprise → prod_QxK9mN3bMq Skipped: free plan (no Stripe product needed) Writing price IDs to .env.local… Done. Run corral validate to confirm.

Test Mode

Corral defaults to Stripe test mode when NODE_ENV !== "production". Use real Stripe test cards (4242 4242 4242 4242) to test the full checkout flow locally.

Step 6 — Gate your first feature

Now use Corral's components to gate the AI analysis panel in HORIZON. The ai_analysis feature is configured with gate: blur, so free-plan users see a blurred preview with an upgrade prompt:

        src/app/dashboard/page.tsx
        tsx
      

import { FeatureGate } from '@/components/corral/FeatureGate'
import { AIAnalysisPanel } from '@/components/AIAnalysisPanel'

export default function DashboardPage() {
  return (
    <div className="dashboard">
      <h1>Intelligence Overview</h1>

      {/* Free users see a blurred preview + upgrade CTA */}
      <FeatureGate feature="ai_analysis">
        <AIAnalysisPanel />
      </FeatureGate>

      {/* This renders for everyone on free+ */}
      <FeatureGate feature="basic_search">
        <SearchPanel />
      </FeatureGate>
    </div>
  )
}

That's it — FeatureGate reads the session server-side, checks the plan, and applies the gate mode from your YAML. No prop drilling, no context setup, no separate API call.

Step 7 — Deploy

Corral works with any deployment target that runs Node.js. Set your environment variables and deploy as normal:

Variable	Required	Description
`CORRAL_SECRET`	Required	32+ char random string for session signing
`DATABASE_URL`	Required	Your database connection string
`STRIPE_SECRET_KEY`	Billing	Stripe secret key (`sk_live_...`)
`STRIPE_WEBHOOK_SECRET`	Billing	Stripe webhook signing secret
`GOOGLE_CLIENT_ID`	OAuth	Google OAuth client ID
`GOOGLE_CLIENT_SECRET`	OAuth	Google OAuth client secret
`SMTP_URL`	Email	SMTP connection string for magic links

deploy to Railway

railway up Deployed to https://horizon-production.up.railway.app corral validate --env production All checks passed ✓ corral stripe push --env production Using STRIPE_SECRET_KEY (live mode) Products synced. Webhooks registered.

What's next?

Core Concepts →

Understand how auth, plans, and gating work under the hood.

Feature Gating →

All 15 gating patterns with examples.

Stripe Billing →

Checkout flows, webhooks, billing portal.

Agent Integration →

llms.txt, CORRAL.md, the 9-command workflow.