CLI Reference

The Raterunner CLI lets you manage your billing configuration as code. Define pricing plans, entitlements, and promotions in YAML, then sync them to payment providers like Stripe.

Installation

Homebrew (macOS/Linux)

bash

brew install raterunner/tap/raterunner

Download Binary

Download the latest release from GitHub Releases.

Available builds:

Platform	Architecture	File
macOS	Intel	`raterunner_VERSION_darwin_amd64.tar.gz`
macOS	Apple Silicon	`raterunner_VERSION_darwin_arm64.tar.gz`
Linux	x64	`raterunner_VERSION_linux_amd64.tar.gz`
Linux	ARM64	`raterunner_VERSION_linux_arm64.tar.gz`
Windows	x64	`raterunner_VERSION_windows_amd64.zip`
Windows	ARM64	`raterunner_VERSION_windows_arm64.zip`

bash

# Example: 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 Packages

Available on GitHub Releases:

.deb — Debian, Ubuntu
.rpm — RHEL, Fedora, CentOS
.apk — Alpine

bash

# Debian/Ubuntucurl -sLO https://github.com/raterunner/cli/releases/download/v0.0.1/raterunner_0.0.1_linux_amd64.debsudo dpkg -i raterunner_0.0.1_linux_amd64.deb

Go Install

bash

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

Build from Source

bash

git clone https://github.com/raterunner/cli.gitcd climake buildsudo mv bin/raterunner /usr/local/bin/

Verify Installation

bash

raterunner --version

Quick Start

1. Initialize a project

bash

raterunner init

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

text

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

2. Edit billing.yaml

Customize the generated configuration:

yaml

# raterunner/billing.yamlversion: 1providers:  - stripeentitlements:  seats:    type: int    unit: seat  api_calls:    type: int    unit: callplans:  - id: free    name: Free Plan    prices:      monthly: { amount: 0 }    limits:      seats: 1      api_calls: 1000  - id: pro    name: Pro Plan    trial_days: 14    prices:      monthly: { amount: 2900 }      yearly: { amount: 29000 }    limits:      seats: 10      api_calls: 50000  - id: pro_lifetime    name: Pro Lifetime    billing_model: one_time    prices:      one_time: { amount: 7900 }    limits:      seats: 10      api_calls: 50000

Note: Plans with billing_model: one_time create Stripe Payment Intents instead of Subscriptions. Use the one_time price key instead of monthly/yearly.

3. Validate the configuration

bash

raterunner validate raterunner/billing.yaml

4. Preview changes (dry run)

bash

export STRIPE_SANDBOX_KEY=sk_test_...raterunner apply --env sandbox --dry-run raterunner/billing.yaml

5. Apply to Stripe

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

Commands

`init`

Initialize a new billing configuration with example plans.

bash

raterunner init              # Creates raterunner/billing.yamlraterunner init ./my-app     # Creates my-app/raterunner/billing.yamlraterunner init --force      # Overwrite existing files

The generated billing.yaml includes: - Free, Pro, and Enterprise plan templates - Example entitlements (projects, API calls, support) - Comments with documentation links

---

`validate`

Validate a billing or provider configuration against the JSON Schema.

bash

raterunner validate raterunner/billing.yamlraterunner validate raterunner/stripe_sandbox.yaml

Validates: - Schema compliance - Required fields - Valid references (entitlements, plan IDs) - Pricing model correctness

---

`apply`

Sync billing configuration to Stripe. Creates products, prices, coupons, and promotion codes.

bash

# Preview changes (no writes to Stripe)raterunner apply --env sandbox --dry-run raterunner/billing.yaml# Apply changes to sandboxraterunner apply --env sandbox raterunner/billing.yaml# Apply to productionraterunner apply --env production raterunner/billing.yaml# Output diff as JSONraterunner apply --env sandbox --dry-run --json raterunner/billing.yaml

Options:

Option	Description
`--env`	Target environment: `sandbox` or `production`
`--dry-run`	Preview changes without applying
`--json`	Output diff as JSON
`--force`	Force application, skip confirmation

What it does:

Stripe API	Purpose
`POST /v1/products`	Create products for plans and addons
`POST /v1/prices`	Create prices (flat, per-unit, tiered)
`POST /v1/coupons`	Create discount coupons
`POST /v1/promotion_codes`	Create promotion codes
`POST /v1/prices/{id}`	Archive old prices when amounts change

Output file:

After successful apply, creates stripe_sandbox.yaml or stripe_production.yaml:

yaml

# raterunner/stripe_sandbox.yaml (auto-generated)provider: stripeenvironment: sandboxsynced_at: "2026-01-15T10:30:00Z"plans:  free:    product_id: prod_ABC123    prices:      monthly: price_XYZ789  pro:    product_id: prod_DEF456    prices:      monthly: price_UVW012      yearly: price_RST345

---

`import`

Import existing Stripe products/prices to YAML files. Useful for migrating existing Stripe setup to Raterunner.

bash

raterunner import --env sandbox --output raterunner/billing.yaml

Creates: - raterunner/billing.yaml — billing configuration - raterunner/stripe_sandbox.yaml — provider ID mappings

What it reads:

Stripe API	Purpose
`GET /v1/products`	Fetch all products
`GET /v1/prices`	Fetch all prices

---

`truncate`

Archive all products and prices in Stripe sandbox. Sandbox only — refuses to run against production.

bash

raterunner truncate           # Interactive confirmationraterunner truncate --confirm # Skip confirmation (for CI/CD)

What it does:

Stripe API	Purpose
`POST /v1/prices/{id}`	Archive prices (set `active: false`)
`POST /v1/products/{id}`	Archive products (set `active: false`)
`DELETE /v1/coupons/{id}`	Delete coupons

---

`config`

Manage CLI settings.

bash

raterunner config set quiet true   # Enable quiet moderaterunner config get quiet        # Get current valueraterunner config list             # List all settingsraterunner config path             # Show config file path

Global Flags

Flag	Description
`--quiet`, `-q`	Suppress non-essential output (errors still shown)
`--help`, `-h`	Show help
`--version`, `-v`	Show version

Environment Variables

Variable	Description
`STRIPE_SANDBOX_KEY`	Stripe test API key (`sk_test_...`)
`STRIPE_PRODUCTION_KEY`	Stripe live API key (`sk_live_...`)

Set them in your shell:

bash

export STRIPE_SANDBOX_KEY=sk_test_...export STRIPE_PRODUCTION_KEY=sk_live_...

Or use a .env file (the CLI does not automatically load .env — use source or a tool like direnv):

bash

# .envSTRIPE_SANDBOX_KEY=sk_test_...STRIPE_PRODUCTION_KEY=sk_live_...

File Structure

A typical Raterunner setup:

text

your-project/├── raterunner/│   ├── billing.yaml           # Source of truth: plans, prices, entitlements│   ├── stripe_sandbox.yaml    # Auto-generated: Stripe IDs for sandbox│   └── stripe_production.yaml # Auto-generated: Stripe IDs for production└── ... your app code

File	Purpose	Committed to Git?
`billing.yaml`	Your billing configuration (plans, prices, entitlements)	Yes
`stripe_sandbox.yaml`	Stripe IDs for test environment	Yes
`stripe_production.yaml`	Stripe IDs for live environment	Yes

All files should be committed to Git — this gives you: - Full history of what plans existed at any point - Which Stripe objects were created for each environment - When syncs happened (synced_at timestamp)

CI/CD Integration

GitHub Actions: Validate on PR

yaml

name: Validate Pricingon:  pull_request:    paths:      - 'raterunner/billing.yaml'jobs:  validate:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - name: Install Raterunner        run: |          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/      - name: Validate configuration        run: raterunner validate raterunner/billing.yaml      - name: Preview changes        run: raterunner apply --env sandbox --dry-run raterunner/billing.yaml        env:          STRIPE_SANDBOX_KEY: ${{ secrets.STRIPE_SANDBOX_KEY }}

GitHub Actions: Sync on Merge

yaml

name: Sync Pricingon:  push:    branches: [main]    paths:      - 'raterunner/billing.yaml'jobs:  sync:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v4      - name: Install Raterunner        run: |          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/      - name: Sync to sandbox        run: raterunner apply --env sandbox raterunner/billing.yaml        env:          STRIPE_SANDBOX_KEY: ${{ secrets.STRIPE_SANDBOX_KEY }}      - name: Commit provider file        run: |          git config user.name github-actions          git config user.email github-actions@github.com          git add raterunner/stripe_sandbox.yaml          git diff --staged --quiet || git commit -m "Update Stripe sandbox IDs"          git push

Sync to Production (Manual Trigger)

yaml

name: Deploy to Productionon:  workflow_dispatch:    inputs:      confirm:        description: 'Type "production" to confirm'        required: truejobs:  deploy:    runs-on: ubuntu-latest    if: github.event.inputs.confirm == 'production'    steps:      - uses: actions/checkout@v4      - name: Install Raterunner        run: |          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/      - name: Sync to production        run: raterunner apply --env production raterunner/billing.yaml        env:          STRIPE_PRODUCTION_KEY: ${{ secrets.STRIPE_PRODUCTION_KEY }}      - name: Commit provider file        run: |          git config user.name github-actions          git config user.email github-actions@github.com          git add raterunner/stripe_production.yaml          git diff --staged --quiet || git commit -m "Update Stripe production IDs"          git push

Workflow Example

Here's a typical workflow for managing pricing changes:

1. Make changes locally

Edit raterunner/billing.yaml to add a new plan or change prices.

2. Validate

bash

raterunner validate raterunner/billing.yaml

3. Preview changes

bash

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

4. Test in sandbox

bash

raterunner apply --env sandbox raterunner/billing.yaml

Test the changes in your Stripe test environment.

5. Create a PR

bash

git checkout -b update-pricinggit add raterunner/git commit -m "Update Pro plan pricing"git push origin update-pricing

6. Review and merge

The PR review ensures pricing changes are intentional. After merge, CI automatically syncs to sandbox.

7. Deploy to production

After testing in sandbox, manually trigger the production deployment (or set up automatic deployment).

Current Status

Note: Raterunner currently supports Stripe only. Support for Paddle and Chargebee is planned. Contact raterunner@akorchak.software for other provider needs.