spearmint

A CLI tool that syncs Roblox developer products and game passes from a local TOML config to the Roblox Open Cloud API.

Define your products in spearmint.toml, run spearmint sync, and spearmint handles creating/updating them on Roblox while generating Lua and TypeScript files for your game.

Install

cargo install --path .

Setup

1. Create a Roblox Open Cloud API key at create.roblox.com/dashboard/credentials with Developer Product and Game Pass write permissions for your experience.

2. In your project directory, create a .env file:

ROBLOX_PRODUCTS_API_KEY=your_api_key_here

3. Initialize the config:

spearmint init

4. Edit the generated spearmint.toml with your universe ID and products.

Config

universe_id = 123456789

[output]
path = "src/shared/modules/Products.luau"
typescript = true

[products.coins_100]
type = "dev_product"
name = "100 Coins"
price = 99
description = "Get 100 coins"
image = "assets/products/coins.png"

[products.vip]
type = "gamepass"
name = "VIP"
price = 499
description = "VIP access"
image = "assets/products/vip.png"

Each product entry supports:

Commands

spearmint sync

Syncs all products to Roblox. Creates new products and updates existing ones when the config has changed. Generates Lua/TypeScript output after syncing.

spearmint sync
spearmint sync --no-generate    # skip code generation
spearmint sync -c custom.toml   # custom config path

spearmint generate

Generates Lua and TypeScript output files from the current mapping without making any API calls.

spearmint generate

spearmint list

Lists all products and their sync status.

spearmint list

spearmint init

Creates a default spearmint.toml template.

spearmint init
spearmint init --force   # overwrite existing config

How It Works

spearmint uses a lock file (spearmint.lock.toml) to track the mapping between local product keys and Roblox IDs, along with cached metadata. On each sync, it compares the current config against the lock file to determine what's changed:

• New products (no lock file entry) are created via the API
• Changed products (name, price, description, or image contents differ) are updated
• Unchanged products are skipped

Image changes are detected by SHA-256 hashing the file contents, so replacing an image file without renaming it will trigger an update.

Generated Output

After syncing, spearmint generates a Lua module and optionally a TypeScript declaration file:

Products.luau

-- This file is auto-generated by spearmint. Do not edit manually.

local Products = {
	DevProducts = {
		["coins_100"] = 123456,
	},
	Gamepasses = {
		["vip"] = 789012,
	},
}

return Products

Products.d.ts

// This file is auto-generated by spearmint. Do not edit manually.

interface Products {
	DevProducts: {
		readonly "coins_100": 123456;
	};
	Gamepasses: {
		readonly "vip": 789012;
	};
}

declare const Products: Products;
export = Products;

License

MIT