RRaterunnerGitHub

Docs / quickstart

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:

Homebrew

bash
brew install raterunner/tap/raterunner

Binary

bash
# macOS Apple Siliconcurl -sL https://github.com/raterunner/cli/releases/download/v0.0.1/raterunner_0.0.1_darwin_arm64.tar.gz | tar xzsudo mv raterunner /usr/local/bin/# Linux x64curl -sL https://github.com/raterunner/cli/releases/download/v0.0.1/raterunner_0.0.1_linux_amd64.tar.gz | tar xzsudo mv raterunner /usr/local/bin/

Go

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

Verify the installation:

bash
raterunner --version

Step 2: Initialize Your Project

Navigate to your project directory and run:

bash
raterunner init

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

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

Step 3: Configure Your Plans

Edit raterunner/billing.yaml to define your pricing:

yaml
version: 1providers:  - stripesettings:  currency: usd  trial_days: 14entitlements:  projects:    type: int    unit: project  api_calls:    type: int    unit: call  priority_support:    type: boolplans:  - 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:

bash
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:

bash
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:

bash
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:

bash
raterunner apply --env sandbox raterunner/billing.yaml

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

text
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:

yaml
# stripe_sandbox.yaml (auto-generated)provider: stripeenvironment: sandboxsynced_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:

bash
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

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

Add addons

yaml
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:

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

Next Steps