Quick Start

This guide will help you set up Raterunner and sync your first billing configuration to Stripe.

Prerequisites

A Stripe account (for syncing)
Git (for version control)

Step 1: Install the CLI

Choose your preferred installation method:

brew install raterunner/tap/raterunner

# macOS Apple Silicon
curl -sL https://github.com/raterunner/cli/releases/download/v0.0.1/raterunner_0.0.1_darwin_arm64.tar.gz | tar xz
sudo mv raterunner /usr/local/bin/

# Linux x64
curl -sL https://github.com/raterunner/cli/releases/download/v0.0.1/raterunner_0.0.1_linux_amd64.tar.gz | tar xz
sudo mv raterunner /usr/local/bin/

go install github.com/raterunner/cli/cmd/raterunner@latest

Verify the installation:

raterunner --version

Step 2: Initialize Your Project

Navigate to your project directory and run:

raterunner init

This creates a raterunner/ directory with a sample billing.yaml:

your-project/
└── raterunner/
    └── billing.yaml

Step 3: Configure Your Plans

Edit raterunner/billing.yaml to define your pricing:

version: 1

providers:
  - stripe

settings:
  currency: usd
  trial_days: 14

entitlements:
  projects:
    type: int
    unit: project
  api_calls:
    type: int
    unit: call
  priority_support:
    type: bool

plans:
  - id: starter
    name: Starter
    headline: Perfect for individuals
    default: true
    prices:
      monthly: { amount: 0 }
    limits:
      projects: 3
      api_calls: 10000
      priority_support: false
    features:
      - Up to 3 projects
      - 10,000 API calls/month
      - Community support

  - id: pro
    name: Pro
    headline: For growing teams
    trial_days: 14
    prices:
      monthly: { amount: 2900 }
      yearly: { amount: 29000 }
    limits:
      projects: unlimited
      api_calls: 1000000
      priority_support: true
    features:
      - Unlimited projects
      - 1M API calls/month
      - Priority support

Step 4: Validate Your Configuration

Before syncing, validate your configuration:

raterunner validate raterunner/billing.yaml

This checks for:

Schema compliance
Required fields
Valid entitlement references
Pricing model correctness

Step 5: Connect to Stripe

Set your Stripe sandbox API key:

export STRIPE_SANDBOX_KEY=sk_test_...

You can find your test API key in the Stripe Dashboard.

Step 6: Preview Changes

See what will be created in Stripe:

raterunner apply --env sandbox --dry-run raterunner/billing.yaml

This shows you what products, prices, and coupons will be created without actually creating them.

Step 7: Apply to Stripe

Apply the changes:

raterunner apply --env sandbox raterunner/billing.yaml

After applying, Raterunner creates a provider file with Stripe IDs:

your-project/
└── raterunner/
    ├── billing.yaml           # Your billing configuration
    └── stripe_sandbox.yaml    # Generated: Stripe IDs

The provider file maps your plan IDs to Stripe product/price IDs:

# stripe_sandbox.yaml (auto-generated)
provider: stripe
environment: sandbox
synced_at: "2026-01-28T10:30:00Z"

plans:
  starter:
    product_id: prod_ABC123
    prices:
      monthly: price_XYZ789
  pro:
    product_id: prod_DEF456
    prices:
      monthly: price_UVW012
      yearly: price_RST345

Step 8: Commit to Git

Commit both files to version control:

git add raterunner/
git commit -m "Add billing configuration"

Now your pricing is:

Version controlled — full history in Git
Synced to Stripe — products and prices created
Reviewable — future changes go through PRs

What's Next?

Add promotions

promotions:
  - code: LAUNCH50
    description: 50% off first 3 months
    discount: { percent: 50 }
    duration: { months: 3 }
    new_customers_only: true

Add addons

addons:
  - id: extra_projects
    name: Extra Projects Pack
    price: { amount: 1000 }
    grants:
      projects: "+10"

Set up CI/CD

Automate validation and syncing in your CI pipeline. See CLI Reference for GitHub Actions examples.

Deploy to production

When ready, sync to production:

export STRIPE_PRODUCTION_KEY=sk_live_...
raterunner apply --env production raterunner/billing.yaml

Next Steps

Schema Reference — Full documentation of all configuration options
CLI Reference — All commands and options
Stripe Integration — Stripe-specific details

Quick Start

On this page