🔱 RBXProducts

RBXProducts is a high-performance CLI tool for Roblox developers to manage Gamepasses and Developer Products using a JSON-based "Source of Truth" workflow. Stop clicking through the dashboard; start syncing.

✨ Key Features

• ⚡ Atomic Syncing: Only updates changed fields. If you only change a price, it won't re-upload your icon.
• 🖼️ Smart Hashing: Uses MD5 file hashing to skip redundant image uploads, saving you time and moderation headaches.
• 📜 Dual-Mapped Lua: Generates a professional Products.lua module allowing instant lookup by Name or ID.
• 🛡️ Open Cloud Native: Built on official Roblox API Keys—no sensitive cookies or browser sessions required.
• 📁 Workspace Management: Keeps your icons and configs organized in a dedicated .products folder.

🛠️ Installation

npm install -g rbxproducts

🚀 Quick Start

1. Initialize your credentials Run this in your project root to link your Roblox Universe:

rbxproducts setup

2. Scaffold your workspace Automatically creates the a .products working folder, template JSON, and fallback assets:

rbxproducts batch-setup

3. Configure your assets

Open (WORKING DIRECTORY).products/products.json and add your items. This is the configuration for which products are in your game.

It will look like:

[
    {
        "name": "New gamepass Example", // gamepass name
        "type": "Gamepass",
        "price": 150, // gamepass price
        "image": "images/example.png", // icon link, leave as a blank string ("") to ignore updates/prevent overwriting existing icon
        "desc": "Edit this description, set ignore = false and add your image!", // your gamepass description
        "ignore": true // this is skipped during syncing. Use for template/outdated gamepasses
    },
    {
        "name": "Automated Demo Pass (10 Robux)",
        "type": "Gamepass",
        "price": 15,
        "image": "images/sword.png",
        "desc": "Proof of Concept Gamepass!",
        "ignore": false
    },
    {
        "name": "DevProduct #1",
        "type": "DevProduct",
        "price": 50,
        "image": "images/shutdown.png", // empty image, won't update.
        "desc": "Dev Product #1 Description!",
        "ignore": false // will update when "batch-update" is called.
    },
]

Leave image as "" to use the default template when creating new products / won't update for existing products.

Set ignore: true to skip an item during sync.

5. Push to Roblox Sync your local JSON to the cloud/Roblox:

rbxproducts batch-update

Your gamepasses / dev products are now updated!

Dev product

Gamepass

5. Generate Lua Module Create your Luau source-of-truth:

rbxproducts output-lua

📝 The Lua Module

Running output-lua generates a module that looks like this:

--[[ 
    AUTO-GENERATED BY RBXPRODUCTS CLI
    Generated on: 12/17/2025
]]

local Products = {
    Gamepasses = {
        ["Poseidon's Spear"] = {
            Name = "Poseidon's Spear",
            Id = 1632057515,
            ImageId = "rbxassetid://76785761257396",
        },
    },
    DevProducts = {
        ["DevProduct #1"] = {
            Name = "DevProduct #1",
            Id = 3482009549,
            ImageId = "rbxassetid://125714459379496" 
        },
    },
    GamepassById = {},
    DevProductById = {},
}

-- Setup ID-based references for O(1) lookups
for _, item in pairs(Products.Gamepasses) do
    Products.GamepassById[item.Id] = item
end
for _, item in pairs(Products.DevProducts) do
    Products.DevProductById[item.Id] = item
end

return Products

🤝 Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.

⚖️ License

MIT © Fred Otieno

If there's a specific feature you want (e.g. Badges support, automated price calculation), let me know in the comments!