rbx-cli

Unified Roblox Open Cloud CLI. One binary, one install, every tool as a subcommand. The command is rbx, short because you type it all day.

This site is a rendering of the docs/ directory of the rbx-forge/rbx-cli repository. Every page is the file the repository already serves, built by CI on every push to main, so the site and the repository cannot disagree. The “Suggest an edit” link at the top right of each page opens the exact file it came from.

Two tools, one backbone

The command surface looks broad because it is two products that happen to share a spine. The spine is the environment model: one rbxplace.toml maps env names to universes and places, and every command resolves --env through it.

Declarative, Terraform for Roblox. init, env, apikey, place, meta, config, shop. You write the desired state into a TOML file you commit, and the tool reconciles Roblox to match it. Diffable, reviewable, safe to run on every push, idempotent by construction.

Operational, kubectl for Roblox. servers, analytics, ban, restart, data, memorystore, message. These act on state that only exists while the game is running, and no TOML file can describe it. Banning a player is a consequence of what happened in your game last night, not a checked-in intention.

Comparable tools have the first pillar. Mantle never had the second, and nothing else does either: you are otherwise clicking through the Creator Hub or writing your own Open Cloud scripts. The second pillar is the difference between deploying a game and running one, and it is why the surface is wide on purpose rather than by accretion.

Every command

Everything marked Live acts on a running game and shares one safety model: dry run by default, --apply to write, --env all refused. That model, and the keys it wants, are on Live operations.

Install

Add it to your project’s rokit.toml, then run rokit install. Pin the version you want from the releases page:

[tools]
rbx = "rbx-forge/rbx-cli"

Or let Rokit write that entry for you. Pass the alias explicitly, or you get an rbx-cli command instead of rbx:

rokit add rbx-forge/rbx-cli --alias rbx

The precompiled binaries attached to every release need no Rust toolchain. Building from source does, at the MSRV declared in the workspace manifest.

Where to start

Two ways in, depending on whether the experience exists yet:

• Nothing on Roblox yet. rbx init creates the group, universe and places, and writes the rbxplace.toml that everything else reads.
• A universe that already exists. rbx import adopts it: every config and lockfile written from what is live, in one command.

Both paths converge on the same three pages. rbx env explains the rbxplace.toml they produce and how --env resolves through it, rbx apikey manages the Open Cloud keys declaratively, and rbx doctor proves those keys work with one real read rather than a syntax check.

From there:

• Putting it in CI. rbx check runs every configured tool’s check in one pass with one aggregated exit code. That page is also where rbx status, the same engine for a human rather than a pipeline, is documented.
• Shipping a build. rbx place uploads, downloads, promotes between envs and rolls back to a past version.
• Everything that is not the place file. rbx meta for universe and place metadata, rbx config for in-experience live configs, rbx shop for passes, badges and developer products with typed Luau codegen.
• Acting on a running game. Live operations is the entry point and the safety model: dry run by default, --apply to write, --env all refused.
• More than one person on the repository. Working in a team is the lockfile conflict procedure. Worth reading before you need it, because a badly resolved rbxshop.lock.toml creates a second paid game pass that this tool cannot delete.

Not on this site

Documentation about the repository rather than the tool stays in the repository: README for the full command table and the stability policy, ARCHITECTURE.md for the crate layout, CONTRIBUTING.md for setup and what makes a PR mergeable, CHANGELOG.md for what changed in a release, and SECURITY.md for where vulnerability reports go, which is never the public tracker.

rbx-cli is a community tool under MPL-2.0. It is not affiliated with, endorsed by, or sponsored by Roblox Corporation.

rbx init

Bootstrap Roblox resources from the command line: create groups, universes, and places, then list IDs to plug into the other rbx subcommands.

rbx init covers the missing first step in a Roblox project bootstrap. You start with nothing and you need a group, a universe, and a few places before rbx place, rbx meta, rbx config, or rbx shop have anything to point at. It hits Roblox’s authenticated creation endpoints (cookie-based, since Open Cloud doesn’t expose these yet) and the listing endpoints so you can pipe fresh IDs straight into your other configs.

Features

• Create a group: rbx init create-group --name ... --icon icon.png
• Create a universe: rbx init create-universe [--group <id>], returns the universe ID and the root place ID in one call
• Create a place inside an existing universe: rbx init create-place --universe-id <id>
• Auto-record into rbxplace.toml: both creates append their new ids to the shared env map, prompting for the env/place name — comments and formatting in the file are preserved
• Rename a place / universe by id: rbx init rename-place / rbx init rename-universe
• List your groups: rbx init list-groups (cookie required)
• List a group’s universes: rbx init list-universes --group <id> (no credential needed; see what these listings expose)
• List a universe’s places: rbx init list-places --universe-id <id> (no credential needed)
• Cookie auto-detect: offers to use the .ROBLOSECURITY of a local Roblox Studio install when no cookie was supplied. Opt-in: an interactive run is asked once, a run with nowhere to ask declines and says so. --auto-cookie is the standing yes. See docs/cookie.md
• Friendly errors: common cases (name already taken, moderation rejection) are surfaced with a clear message instead of raw HTTP

Quick start

Bootstrap a brand-new project with a group, a universe, and an extra lobby place:

# 1. Create the group (returns id 123456789)
rbx init create-group --name "My Studio" --icon assets/group-icon.png --public

# 2. Create a universe under that group (returns universe_id + root_place_id)
rbx init create-universe --group 123456789 --name "[TEST] My Game" --env test

# 3. Add a second place inside the universe
rbx init create-place --universe-id 987654321 --name "Lobby" --place lobby

Steps 2 and 3 record their ids in rbxplace.toml as they go, so there’s nothing to copy by hand. Omit --env/--place/--name and you’ll be asked for them instead.

Starting from an existing group with universes already created? rbx init list-universes --group <id> prints their ids; write the [<env>] sections yourself, then check the result with rbx env list. See the field reference for what goes where.

Commands

$ rbx init create-universe
  Universe name (empty to keep the template's): My Test Game
  Env name in rbxplace.toml: (my_test_game) test
⚠ Create universe 'My Test Game' under group 1234567 and record it as [test]? [y/N] y
Creating universe under group 1234567 ...
Renaming root place 111222333 to My Test Game ...
Created universe (id 9876543299) with root place (id 111222333)
  name: My Test Game
Added [test] to rbxplace.toml

rbx init create-universe --name "[TEST] My Game" --env test -y

$ rbx init create-place --universe-id 9876543299
  Place name (empty to keep the template's): Lobby
  Place name under [test.places]: (lobby) 
⚠ Create place 'Lobby' under universe 9876543299 and record it as [test].places.lobby? [y/N] y
Created place (id 444555666) in universe 9876543299
  name: Lobby
Added places.lobby to [test] in rbxplace.toml

Authentication

rbx init only uses cookie auth. Roblox does not expose group, universe, or place creation through Open Cloud, so there’s no API key option. The cookie is supplied via the global --cookie flag, the RBX_COOKIE env var, or a local Roblox Studio install.

That last one is opt-in: finding a signed-in Studio is not the same as being allowed to send its session. --auto-cookie is the standing yes, an interactive run is asked once, and a run with nowhere to ask — CI, a pipe, a cron job — declines and says so. --no-auto-cookie is the standing no.

This is the command with the least choice about it, so it is worth knowing what you are handing over: see docs/cookie.md for the resolution order in full, the stderr notice on auto-detection, and why the cookie never reaches disk.

The listings need no credential

list-universes and list-places are the two read commands here, and neither one is gated. Measured against a private universe that has never had a player, with no cookie, no API key and no session:

GET develop.roblox.com/v1/universes/{id}/places  → 200, every place, with names
GET games.roblox.com/v2/groups/{id}/gamesV2      → 200, every game

The second one is worth being precise about, because the query parameter looks like a permission and is not. Measured on one group, anonymously:

accessFilter=2 is the public filter. 1, and omitting it, are the unfiltered form, and unfiltered means unfiltered for anybody. rbx init sends 1, so it sees a group’s staging copies and unreleased projects, and so does anyone else who asks.

Roblox treats the existence, id and name of a universe or place as public. What stays behind a session is the content: develop.roblox.com/v1/places/{id} answers 404 anonymously, and whether a place is playable is not in these listings at all.

Two practical consequences. Do not rely on a universe being unlisted to keep a project quiet before announcing it. And rename test places before creating them under a real account: Roblox’s default place names embed the owner’s username, and those names come back to an anonymous caller.

How it works

• Group creation hits groups.roblox.com/v1/groups/create (multipart upload with the icon).
• Universe creation hits apis.roblox.com/universes/v1/universes/create with a templatePlaceId.
• Place creation hits apis.roblox.com/universes/v1/user/universes/{id}/places.
• Listing a group’s universes uses games.roblox.com/v2/groups/{id}/gamesV2?accessFilter=1. accessFilter=2 is the public-only filter; 1 is unfiltered, for any caller (see above).
• Listing a universe’s places uses develop.roblox.com/v1/universes/{id}/places.

All write endpoints transparently handle CSRF: a 403 response with an x-csrf-token header caches the token and retries once. Listing endpoints retry on 429 / 5xx with exponential backoff (max 3 attempts).

rbx import

Adopt an existing universe in one command. rbx import resolves a universe you already have on Roblox, writes the env into rbxplace.toml, and brings its passes, badges, products, metadata and live config into the TOML files each tool manages — with the lockfiles that make the immediately-following check green.

It is the command for a game that predates this toolkit, which is nearly every game. Without it, adoption means copying ids out of the Creator Hub by hand: the class of transcription where one wrong digit points a sync at somebody else’s universe.

Features

• One gesture - Universe, places, owner, monetization, metadata and live config, in one pass
• Composition, not a second implementation - Each domain is imported by the command that already owns it, so nothing here can disagree with what sync and check expect
• Safe on an existing file - Other envs, [owner], [codegen] and every comment in rbxplace.toml survive an import verbatim
• Repeatable - A second --env layers a second universe onto the same files, in the differential overlay layout the tools already use
• Nothing hidden - What could not be imported is named at the end, with the reason and the fix

Usage

rbx import --universe-id 123456789 --env prod       # Adopt a universe as "prod"
rbx import --universe-id 987654321 --env staging    # Add a second, beside the first
rbx import --universe-id 123456789 --env prod --dry-run    # Resolve and report, write nothing
rbx import --universe-id 123456789 --env prod --only shop  # One domain
rbx import --universe-id 123456789 --env prod --dir ./game # Write somewhere other than .
rbx import --universe-id 123456789 --env prod --strict     # Fail instead of skipping a domain

What it writes

import computes none of those lockfile entries. It runs each tool’s own import path, which is what makes the zero-drift guarantee reachable at all — the lockfile is written by the same code that later reads it.

The acceptance criterion

import then check is green, with nothing in between.

rbx import --universe-id 123456789 --env prod
rbx check --env prod

rbx check discovers the tools from the files the import just wrote and returns one exit code for all of them: 0 clean, 2 drift, 1 a check that could not answer. See docs/check.md.

If there is drift straight after an import, the import is wrong. import prints that exact command line when it finishes, --dir included when it was passed.

Running it twice

The second import is what decides whether the command is usable, and it is the case the implementation is shaped around.

rbx import --universe-id 111 --env prod
rbx import --universe-id 222 --env staging

The second run:

• appends [staging] to rbxplace.toml; [prod], [owner], [codegen] and every comment are untouched, byte for byte;
• pulls rather than re-initialises each domain, so rbxshop.toml gains an [envs.staging.*] overlay for the fields that differ from base rather than being overwritten.

Which of init --from-remote and pull runs is decided by whether the config file exists, not by whether this is your first import — a directory can already be under management for reasons that have nothing to do with this command.

Those pulls run with --accept-remote --yes, because the live game is what an import is adopting. The consequence is worth knowing before you run it a second time: a local edit you have not synced is resolved to the remote value without a prompt. import names the files it is about to layer onto, on the real run and under --dry-run alike:

! rbxshop.toml, rbxmeta.toml already exist — this env is layered onto them, and a
  local edit that disagrees with Roblox is resolved to the remote value without
  asking. Commit or sync local edits first if you have any.

Commit first, or run the domain’s own sync, if you have edits you meant to keep.

An env that is already in rbxplace.toml is left exactly as it is. If its universe_id disagrees with the one you passed, import says so and keeps the file’s:

! [prod] already points at universe 999 — kept. Nothing was retargeted; use a
  different --env if you meant to add this universe.

What it cannot import

Reported at the end of every run, because a directory that looks adopted but quietly omits something is worse than one that failed.

! 1 thing could not be imported:
  meta server fill, copying permission, beta mode: these live only on legacy
      endpoints that need a Roblox session cookie
    -> re-run with --cookie, or set them by hand in rbxmeta.toml

Two categories:

• Cookie-only metadata. server_fill, allow_copying and beta_mode have no Open Cloud endpoint. rbx meta models them and sync can write them, but nothing can read them back without a session cookie — so an import that resolves no cookie at all leaves them unset and says so. The test is what the meta step resolves, not what you typed: it auto-detects like any other rbx meta run, so on a machine with Studio signed in these fields are read and this line does not appear. Without that line, the first meta sync after an import looks like it is inventing changes.
• A domain that failed. By default a domain that errors — usually a key missing one scope — is skipped and reported rather than aborting the run, because a half-written directory with no explanation is the worse outcome. --strict inverts that, which is what you want in CI.

Flags

--places <path> (global) points at a shared rbxplace.toml outside --dir; otherwise the file is written next to everything else. rbx check --dir resolves the same default the same way, so rbx check --dir <path> reads back exactly what rbx import --dir <path> wrote.

Required API scopes

The import calls each tool’s own read paths, so it needs the read half of what those tools need:

rbx doctor --universe-id <id> answers whether the loaded key carries them, before you run this.

Where the place list comes from

Open Cloud can read one place (/cloud/v2/universes/{id}/places/{p}) but cannot enumerate them, so the place list is fetched from develop.roblox.com, the same host rbx init list-places uses.

That listing needs no credential, and a private universe is no exception: it answers in full to an anonymous caller. So this step never fails for want of a cookie, and passing one widens nothing. See the listings need no credential for what was measured.

The call does not auto-detect a Studio cookie, and now that the listing is known to be open there is nothing for auto-detection to buy here. The meta step that runs afterwards is an ordinary rbx meta invocation and resolves the cookie the usual way, which is where a cookie genuinely changes the outcome. docs/cookie.md has the full order.

The root place is always written as places.main, whatever Roblox calls it, because main is the key the rest of the toolkit resolves to when --place is omitted. Other places take a slugified form of their display name, suffixed if two collide.

Related

• docs/place.md — the rbxplace.toml this writes, and what reads it
• docs/shop.md — what lands in rbxshop.toml, and the overlay layout a second import produces
• docs/meta.md — the metadata fields, including the cookie-only ones
• docs/cookie.md, the trust model: what the cookie is for, how it is resolved, and why it never reaches disk
• docs/config.md — live config, where live is authoritative
• docs/doctor.md — check the key before importing with it

rbx env

Read rbxplace.toml — the shared file that maps env names to universe and place ids.

Every other subcommand resolves --env against this file. rbx env is the read side of it: it answers “what id will --env prod actually target?” without opening the TOML by hand, and without calling Roblox. It is fully offline — no API key, no cookie.

Features

• List - See every env, its universe id, and its places, rendered in the file’s own TOML shape
• Get - Print one bare value to stdout, ready for $(...) capture in scripts and CI
• Gen-module - Export the whole map as a Luau/Lua/JSON/TypeScript module for your game code, with --check to prove the committed copy was never hand-edited
• JSON - --json on list and get writes one document to stdout and nothing else, with documented field names, for jq and CI
• Completions - The env and place names in this file are what --env <TAB> and --place <TAB> offer, in bash, zsh, fish and PowerShell
• Same resolution as everything else - Delegates to the shared resolver, so rbx env get place-id --env prod prints the exact id rbx place upload --env prod would write to
• Offline - Reads the local file only

Quick start

rbx env list                            # everything in rbxplace.toml
rbx env get universe-id --env prod      # 9876543211

Commands

rbx env list
rbx env list --env prod       # just this env
rbx env list --names          # env names only, one per line
rbx env list --place-names    # place names only, one per line
rbx env list --json           # one JSON document on stdout

rbxplace.toml
owner = group 1234567

[dev]
universe_id  = 9876543210
places.lobby = 987654321
places.main  = 123456789012345

[prod]  confirm
universe_id = 9876543211
owner       = user 42
places.main = 234567890123456

{
  "schema_version": 1,
  "places_file": "rbxplace.toml",
  "owner": { "type": "group", "id": 1234567 },
  "envs": [
    {
      "name": "dev",
      "universe_id": 9876543210,
      "confirm": false,
      "codegen": true,
      "places": { "lobby": 987654321, "main": 123456789012345 }
    },
    {
      "name": "prod",
      "universe_id": 9876543211,
      "env": "production",
      "owner": { "type": "user", "id": 42 },
      "confirm": true,
      "codegen": true,
      "places": { "main": 234567890123456 }
    }
  ]
}

rbx env list --json | jq -r '.envs[] | select(.confirm) | .name'   # envs that prompt
rbx env list --json | jq -r '.envs[].places | keys[]' | sort -u    # every place name

rbx env list --names          # dev
                              # prod
rbx env list --place-names    # lobby
                              # main

rbx env list --place-names --env prod

UNIVERSE=$(rbx env get universe-id --env prod)
PLACE=$(rbx env get place-id --env prod --place lobby)

rbx env get owner-id                       # top-level [owner], no --env needed
rbx env get universe-id --env all          # one "<env><TAB><value>" line per env

rbx env get universe-id --env all | cut -f2

rbx env get universe-id --env prod --json

{
  "schema_version": 1,
  "field": "universe-id",
  "value": "9876543211",
  "results": [{ "env": "prod", "value": "9876543211" }]
}

rbx env get universe-id --env all --json

{
  "schema_version": 1,
  "field": "universe-id",
  "results": [
    { "env": "dev", "value": "9876543210" },
    { "env": "prod", "value": "9876543211" }
  ]
}

UNIVERSE=$(rbx env get universe-id --env prod --json | jq -r .value)
rbx env get place-id --env all --json | jq -r '.results[] | "\(.env)=\(.value)"'

rbx env gen-module --out src/types/EnvironmentInfo.luau
rbx env gen-module --out src/environments.lua
rbx env gen-module --out config/environments.json
rbx env gen-module --out src/types/EnvironmentInfo.ts

[codegen]
output = "src/shared/Envs.luau"   # relative to rbxplace.toml

[dev]
universe_id = 9876543210

rbx env gen-module           # writes src/shared/Envs.luau
rbx env gen-module --check   # verifies the same file

export type EnvironmentType = "dev" | "prod"

export type EnvironmentInfo = {
  env: EnvironmentType,
  universeId: number,
  placeIds: { { name: string, id: number } },
}

local envs: { EnvironmentInfo } = { ... }
return envs

[dev]
universe_id = 1234567890
env = "Dev"        # what EnvironmentType will contain
[dev.places]
main = 111111111

rbx env rm staging --dry-run   # list what would go
rbx env rm staging             # asks before writing
rbx env rm staging --yes       # for scripts

Every field, and where it goes

rbxplace.toml has exactly two reserved top-level tables. Every other top-level table is an env, named by its key.

# ── reserved ────────────────────────────────────────────────
[owner]                              # who owns this project
type = "group"                       # "user" or "group"
id = 1234567

[codegen]                            # where `rbx env gen-module` writes
output = "src/shared/Envs.luau"      # relative to this file

# ── everything below is an env ──────────────────────────────
[prod]
universe_id = 9876543211
confirm = true                       # prompt before writes to this env
env = "Production"                   # what game code matches on
owner = { type = "user", id = 42 }   # overrides the top-level [owner]
[prod.places]
main = 234567890123456
lobby = 234567890999999

[ci]
universe_id = 555
codegen = false                      # tooling env: keep it out of the module

Reserved tables

Env fields

Where a field carries a (X.Y.Z+) tag, it needs at least that release. This page describes main, which is where a feature lands before it ships — and /blob/main/docs/env.md is the URL links and search results hand you — so a tagged field is newer than whatever rokit.toml pins until you check rbx --version. Nothing in the table above is tagged today: every field here is in the latest release.

codegen = false

For an env that exists for tooling and never ships: a universe you upload to from CI, for instance. It stays a normal env everywhere else — --env resolves it, --env all includes it, list and get report it. It is only kept out of the generated modules, so adding one does not widen EnvironmentType and force game code to acknowledge an env it never runs in.

The trade is real and worth stating: nothing then maps that universe back to an env at runtime. If the game boots there and your code resolves its env from game.GameId, it will not find one — and rbx shop’s dispatcher errors outright rather than guessing. Correct for a universe that only ever receives uploads; wrong for one that runs gameplay.

Marking every env codegen = false is refused rather than emitting a module whose type union has nothing in it.

Unrecognised keys

A key no table in the list above claims is ignored, and named on stderr:

warning: rbxplace.toml: 1 unrecognised key, ignored by rbx 0.2.0:

  [assets] codgen
    known keys: universe_id, env, places, owner, confirm, codegen

An ignored key changes nothing. Either it is misspelled, or it comes from a
release newer than the one you are running — check the changelog for the
version that introduces it before assuming it took effect.

It stays a warning rather than an error on purpose. Every tool in the suite reads this one file into its own narrower struct, and a key must survive an rbx older than the release that introduced it — otherwise adopting a new field would mean upgrading every machine in the same instant. What it must not do is pass for applied: from the outside, an ignored key and an honoured one produced the same silent exit 0.

gen-module --check carries the same fact into its failure. Its normal advice — regenerate and commit — assumes the committed module is the stale side. When a key was ignored, the check itself is reading the inputs wrong, the committed file may be the correct one, and regenerating would bake the misreading in. So the check names that possibility instead of stating the fix unconditionally:

1 generated file no longer matches rbxplace.toml. Run `rbx env gen-module`
and commit the result, unless one of the following applies.

1 key in rbxplace.toml was ignored (listed above). If one of them was meant
to change what is generated, this check is reading the wrong inputs and the
committed file may be the correct one — regenerating would bake the
misreading in. Upgrade rbx, or fix the spelling, before running the fix.

Place names under [<env>.places] are data, not keys, and are never reported.

Shell completions for --env and --place

rbx completions <shell> writes a script that completes both with the names in the rbxplace.toml of the directory you are standing in. It calls rbx env list --names and --place-names at TAB time rather than baking the values in, which is why those two listings are a supported surface rather than debug output.

The install paths, the four shells, and what happens outside a project are on its own page.

Where the file comes from

rbx env only reads it. One command writes it:

• rbx place fetch --env <name> --write — refresh one env’s places from the live universe

Otherwise it is yours to write. A minimal file is one [<env>] section with a universe_id; rbx init list-universes prints the ids to put in it, and rbx init create-universe appends a section for a universe it creates.

Nothing generates this file wholesale, and that is deliberate. Every writer here only inserts lines. Reserializing the document through serde would drop comments, reorder keys, and silently delete any field it does not model, env overrides included.

See also

• rbx init — create the universes and places this file points at
• rbx place — upload, download, and promote place files across these envs
• rbx open — launch Studio at one of these places

rbx apikey

Manage Roblox Open Cloud API keys declaratively from rbxapikey.toml. Supports multiple secret backends (lockfile, custom file) and automatic scope validation against Roblox’s live API.

Features

• Declarative configuration - Define all keys in rbxapikey.toml with explicit scopes
• Multi-backend secrets - Store API key secrets in lockfile (default) or custom file
• Scope validation - Embedded catalog with warnings (not errors) for unknown scopes, enabling durability as Roblox adds new scopes
• State reconciliation - status command detects drift between config, lockfile, and Roblox
• Auto-introspection - Verify key creation succeeded and detect configuration drift
• Datastore granularity - Restrict universe-datastore scopes to specific datastore names

Usage

Create a key

rbx apikey create <key>              # Create one key from rbxapikey.toml
rbx apikey create --all              # Create all keys
rbx apikey create <key> --no-ip      # Allow all IPs (no CIDR restriction)
rbx apikey create <key> --force      # Overwrite existing lockfile entry
rbx apikey create <key> --no-verify  # Skip post-create introspection

Manage keys

# List and inspect
rbx apikey list                      # Overview of all keys and expiry
rbx apikey list --expiry-only        # Compact view: just name and expiration dates
rbx apikey list --sort expiry        # Sort keys by expiration date (nearest first)
rbx apikey list --remote             # Every key on the account, tracked or not
rbx apikey list --remote --group-id 445566778   # A group's keys instead of yours
rbx apikey list --json               # One JSON document on stdout, never a secret

# Clean up the account
rbx apikey prune --dry-run           # Show what would be offered, delete nothing
rbx apikey prune --untracked-only    # Only offer keys this project does not track
rbx apikey prune --expired-only      # Only offer keys past their expiry

# Status and reconciliation
rbx apikey status                    # Compare config vs lockfile vs Roblox
rbx apikey status --remote           # Also query live Roblox API for drift detection
rbx apikey status --json             # One verdict per key, as a JSON document

# Update and regenerate
rbx apikey update <key>|--all        # Apply TOML configuration to Roblox
rbx apikey update <key> --no-ip      # Update without CIDR restriction
rbx apikey regenerate <key>|--all    # Rotate the API key secret

# Delete and introspect
rbx apikey delete <key>|--all        # Delete key from Roblox and lockfile
rbx apikey delete <key> --yes        # Skip confirmation prompts
rbx apikey delete <key> --clean-files  # Also delete secret_file without asking
rbx apikey introspect <key>          # Show what Roblox has stored (key < 1h old)
rbx apikey resolve <key>             # Print the raw secret (for scripts)

# Scope catalog
rbx apikey scopes list               # All known scopes grouped by target type
rbx apikey scopes show <scopeType>   # Details for one scope type
rbx apikey scopes show universe --json          # The same, as a JSON document
rbx apikey catalog regenerate [url]  # Regenerate scope catalog from openapi.json

Commands explained

list command:

• rbx apikey list - Show all keys with full details (alphabetical order)
• rbx apikey list --expiry-only - Compact view: just key names and expiration dates
• rbx apikey list --sort expiry - Sort by expiration date (nearest first)
• rbx apikey list --expiry-only --sort expiry - Compact + sorted by expiry

Expiration colors:

• Green - Expires in >30 days (healthy)
• Yellow - Expires in <7 days (rotate soon)
• Red - Already expired or missing secret

update vs status:

• rbx apikey update <key>|--all - One-way sync: apply your TOML configuration to Roblox. Updates metadata (enabled, expiry, IP restrictions) and scopes on existing keys.
• rbx apikey status - Compare: shows differences between TOML (desired), lockfile (tracked), and Roblox (actual). Does not modify anything.
• rbx apikey status --remote - Same as above, but also queries the live Roblox API to detect drift.

Key creation workflow:

1. Define keys in rbxapikey.toml
2. Run rbx apikey create <key> to generate the key on Roblox and save the secret
3. Later, edit rbxapikey.toml and run rbx apikey update <key> to re-apply the config

Configuration

Create rbxapikey.toml in your project root. Keys target Roblox universes by env name (declared in rbxplace.toml), not raw universe ids — the same source of truth used by rbxmeta, rbxconfig, and the rest of the suite.

[settings]
default_enabled = true                       # optional
default_expiration_months = 3                # optional (omit for no default expiry)
default_allowed_cidrs = []                   # optional
default_envs = ["prod"]                      # optional; fallback for keys that omit `envs`
name_prefix = "mygame_"                      # optional; prepended verbatim (e.g. "mygame_deploy")
default_secret_file = ".secrets/{name}.env"  # optional; {name} is the key name, {env_group} its group

[keys.mykey]
envs = ["dev", "prod"]                       # resolves to universe_ids via rbxplace.toml
scopes = ["asset:read,write", "universe:read"]
expiration_months = 3                        # 3 months from now
# or: expiration_days = 90                   # 90 days from now (more precise)
# or: expires_at = "2025-12-31T00:00:00Z"    # exact date (ISO 8601)

One key per environment

envs = ["dev", "staging", "prod"] declares one key that can reach all three universes. That is right for a read-only observability key and wrong for everything else: the safety model this tool is built on is that scopes and universes are bound at creation, so the blast radius of a key is whatever you gave it on the day you made it.

Writing envs as a table of named groups instead declares one key per group:

[keys.deploy]
scopes = ["universe-places:write"]

[keys.deploy.envs]
ci   = ["dev", "staging"]   # → key deploy_ci, scoped to the dev + staging universes
prod = ["prod"]             # → key deploy_prod, scoped to the prod universe only

Two keys, one declaration. Everything except the envs — scopes above all — is written once, so a scope added for production cannot be forgotten for CI. That is the whole point: the alternative is three near-identical [keys.*] blocks, and a scope added to one and not the others compiles fine, syncs fine, and desyncs your environments silently.

TOML distinguishes an array from a table on its own, so there is no flag to set and the array form means exactly what it always meant.

The group name is identity, not decoration. It names four things at once:

So rbx apikey create deploy_ci, status, regenerate, delete and the rest all work on a generated key exactly as they do on a hand-written one. Naming the declaration (rbx apikey create deploy) matches no key, and says so, listing the keys it did produce.

• Adding an env to a group extends that key. ci = ["dev", "staging", "qa"] widens deploy_ci on the next update, which is an ordinary change surfaced by drift detection.
• Renaming a group renames a key. ci → build makes deploy_ci disappear from the config and deploy_build appear. status reports the first as ORPHAN_LOCK and the second as PENDING, which is what renaming a hand-written key already does. Roblox does not learn the new name until you create it; delete the old key rather than leaving it live.
• {env_group} is available in secret_file and default_secret_file for layouts that want the group as a path segment of its own: .secrets/{env_group}/{name}.env. It expands to nothing for a key that does not fan out. You rarely need it, because {name} already carries the group.

Two shapes are refused at load rather than at create time, both because they produce keys that cannot be told apart:

• a group whose generated name collides with another key in the file;
• a fan-out whose keys would all write their secret to one path, because secret_file was given a literal path with no placeholder in it. The last create would overwrite the previous key’s secret, leaving a live key on Roblox that nothing local can authenticate as.

An empty group (ci = []) is refused too. A key targeting no universe is scoped to all of them, which is the opposite of what the syntax is for.

Duplicate scopes

A scope written twice is collapsed on the way in, at both levels — ["asset:read", "asset:read"] and ["asset:read,read"] alike — and the collapse is reported on stderr, naming the table and the entry. First-seen order survives, so what you read back from apikey introspect is in the order your file wrote.

Collapsing is safe: a duplicate grants nothing extra, it only makes the payload Roblox is asked to store redundant. It is reported rather than dropped in silence because it is almost always a merge artefact, and the line it was meant to be is worth a look.

Two entries sharing a scope type but listing different operations (asset:read next to asset:write) are not duplicates and are left alone. Folding them into their union is a normalisation, not a deduplication.

Drift validation

Each create/update/regenerate operation writes the resolved universe_ids into the lockfile as a snapshot of what’s actually deployed. On the next run, the tool re-resolves the envs and compares against the snapshot. When they differ, the tool refuses to proceed and prints the discrepancy. This catches accidental retargeting (e.g. someone edited rbxplace.toml to point env dev at a fresh universe) before the change is silently pushed to Roblox.

To acknowledge an intentional change, delete that key’s entry from rbxapikey.lock.toml and re-run the operation. The next run will re-resolve, re-create owner cache, and write a fresh snapshot.

Global settings

• default_enabled - (optional) Whether keys are enabled by default (defaults to true)
• default_expiration_months - (optional) Default months until key expiry; omit to allow keys without expiry
• default_allowed_cidrs - Default IP CIDR blocks for keys that set no allowed_cidrs of their own. Not optional in practice: with no allowlist from either place, create and update refuse and name the three ways out — set it here, set allowed_cidrs on the key, or pass --no-ip to allow every address. Nothing is inferred; neither this tool nor Roblox fills in your address for you
• default_envs - (optional) Default env list used when a key has no envs field of its own. Each name must exist in rbxplace.toml.
• name_prefix - (optional) Prepended verbatim to every key’s display name on Roblox. You control the separator: use mygame_ for underscore, mygame- for dash, etc. Useful when the same rbxapikey.toml is reused across games so the Creator Hub distinguishes same-named keys (e.g. mygame_deploy, othergame_deploy). Does not change the local TOML key.
• readonly - (optional) Refuse to load this file if any key in it asks for an operation other than read or list. See Read-only by declaration
• default_secret_file - (optional) Path template used when a key has no explicit secret_file. The literal {name} is replaced with the TOML key and {env_group} with the key’s env group, if it has one. Example: .secrets/{name}.env makes [keys.deploy] write to .secrets/deploy.env by default, and a fan-out of deploy write to .secrets/deploy_ci.env and .secrets/deploy_prod.env. Explicit secret_file on a key always wins.

Key attributes

• name - (optional) Display name on Roblox Creator Hub (defaults to key ID)
• description - (optional) Description on Roblox Creator Hub; auto-generated if omitted
• envs - Either a list of env names from rbxplace.toml (one key, targeting every one of them), or a table of named groups (one key per group — see One key per environment). The list form falls back to settings.default_envs when omitted or empty; the table form always names its envs.
• group_ids - (optional) List of group IDs for group-target scopes
• user_ids - (optional) List of user IDs for user-target scopes
• scopes - List of scope strings in format "scopeType:operation1,operation2". A scope listed twice is collapsed and reported, at both levels — see Duplicate scopes.
• enabled - (optional) true/false to enable/disable the key (defaults to settings.default_enabled)
• expiration_months - (optional) Months until key expires
• expiration_days - (optional) Days until key expires (more precise than months)
• expires_at - (optional) Exact expiration date in ISO 8601 format (e.g., "2025-12-31T00:00:00Z"); all three expiration fields are mutually exclusive (priority: expires_at > expiration_days > expiration_months > global default); omit all for keys that never expire
• allowed_cidrs - (optional) List of IP CIDR blocks allowed to use this key (defaults to settings.default_allowed_cidrs)
• secret_file - (optional) Custom file path to store the secret (defaults to lockfile). Templated like default_secret_file: {name} is the key name, {env_group} its env group. A fan-out declaration needs one of the two in the path, or its keys would share one file.
• datastores - (optional) Array of datastore restrictions (fine-grained datastore scopes by universe and name)

Read-only by declaration

[settings]
readonly = true          # nothing in this file may ask for more than read or list

[keys.viewer]
readonly = true          # or just this one, in a file that is not

Loading fails, naming the key and the scope, if either is set and a scope asks for anything else:

[keys.viewer] is readonly and asks for `universe:write`. A readonly key may only use
read and list. Drop the operation, or drop `readonly` — but if this file is the one
that is not supposed to hold write scopes, dropping `readonly` is the change to think
twice about.

Why this is a check rather than a comment. Roblox binds a key to its scopes when it is created, and it is tempting to conclude that a key declared read-only cannot be made to write. Half of that is true: nothing widens a key at runtime, so whatever holds the secret cannot escalate it. The other half is false, and was disproved by running rbx apikey update on an already-created key and watching Roblox accept a write scope. update is a verb this tool ships, and the file that declares the rule is the same file somebody would edit to break it.

So the guard sits at config load, which is the one place that sees the declaration before anything reaches Roblox.

It is an allow-list — read and list, nothing else — rather than a list of forbidden writes. Roblox adds operations whenever it likes, and a deny-list would quietly let each new one through, which is the failure this exists to close.

[settings] readonly and a per-key readonly add to each other; neither turns the other off. A key produced by fan-out is checked and named by its generated name, since that is the name it would be created under.

Datastore granularity

Restrict universe-datastore scopes to specific datastore names:

[keys.datastores_key]
envs = ["prod"]
scopes = ["universe-datastores.objects:read"]

[[keys.datastores_key.datastores]]
universe_id = 9876543210
name = "UserData"
operations = ["read"]

[[keys.datastores_key.datastores]]
universe_id = 9876543210
name = "GameState"
operations = ["read", "write"]

Secret storage

By default, secrets are stored in rbxapikey.lock.toml, which you have to gitignore: nothing in this tool writes into your .gitignore. rbx apikey create checks before it creates anything and refuses if git is not ignoring that file, naming the line to add.

Custom file backend

[keys.mykey]
secret_file = "/path/to/secret"

The secret will be stored in /path/to/secret instead of the lockfile.

Workflow

All permanent configuration lives in rbxapikey.toml. To make changes:

1. Edit the TOML - Add/remove/modify keys and their settings
2. Run rbx apikey update <key>|--all - Apply the TOML to Roblox

Example:

# Disable a key
vim rbxapikey.toml    # Set enabled = false
rbx apikey update mykey

# Rotate expiry
vim rbxapikey.toml    # Change expiration_months
rbx apikey update mykey

The TOML is the source of truth. The lockfile and Roblox are the applied state.

Authentication

rbx apikey uses cookie auth (the API key admin endpoints aren’t on Open Cloud yet). The .ROBLOSECURITY cookie is supplied via the global --cookie flag, the RBX_COOKIE env var, or a local Roblox Studio install.

Studio detection is opt-in: --auto-cookie is the standing yes, an interactive run is asked once, --no-auto-cookie is the standing no, and a run with nowhere to ask declines by itself.

In CI, that last rule means --auto-cookie is not the answer — there is no Studio on a runner, and a runner that happens to have one must not reach into it. Every write verb here (create, update, regenerate, delete, prune) requires a cookie, so a scheduled rbx apikey create --all needs RBX_COOKIE from a secret store. Prefer arranging the pipeline so none of these run there at all: the keys they mint are the credential CI should be using, not making.

A session cookie is a full-account credential, strictly more powerful than the scoped keys this command creates. docs/cookie.md is the trust model: the full resolution order (including RBXAPIKEY_COOKIE, the per-tool variable that survived the merge into one binary), what an auto-detected cookie prints on stderr, and why it is never written to disk.

rbx apikey can-manage

Can you create a key for this experience at all? For a group-owned universe the answer depends on your group role, which rbxapikey.toml knows nothing about.

rbx apikey can-manage --universe-id 5544332211
rbx apikey can-manage --place-id 55443322110099   # resolved to its universe
rbx apikey can-manage --env prod

place 55443322110099 is in universe 5544332211
universe 5544332211: can create keys yes

It authenticates with your Studio cookie, not with an API key, and that is the design. Asking with a key is circular: a key is bound to its universes at creation, so a key for universe A answers Forbidden about universe B.

--place-id is repeatable here, and this is the command it is repeatable for:

rbx apikey can-manage --place-id 55443322110099 --place-id 66778899001122

It is the global flag, the same one rbx open and rbx place download take. Everywhere else acts on one place and refuses a repeated flag by name rather than taking the first.

There is no positional id. A place id and a universe id are both plain integers and the two spaces overlap: 5544332211 is one game’s universe id and a valid place id belonging to a different universe. Say which you mean.

Why it is worth running

Because create tells you nothing. Measured against a universe belonging to somebody else:

• can-manage said no
• rbx apikey create succeeded, and introspection confirmed the scopes. Roblox does not check ownership when a key is made.
• the key then failed at first use: The authorized user does not have sufficient permissions

So a created key proves nothing. This is the only place the answer exists beforehand.

How far to trust it

A no was verified end to end, through to the failed call. A yes was right twice, but it says nothing about the scopes you will request or about your IP allowlist, the two other ways a created key ends up unusable.

Two caveats. canManage means “can administer this experience”, and that it also means “can use API keys here” is an inference from three observations, not something Roblox documents. And the endpoint is develop.roblox.com, legacy rather than Open Cloud, with no Open Cloud equivalent: if Roblox retires it, this command goes with it.

rbx apikey list --remote and rbx apikey prune

Three commands answer three different questions, and only the last one can see a key this project never made:

The gap the third one fills is the one nobody expects to be wide. An account used for any length of time accumulates keys from other checkouts, from other tools, and from clicking through the Creator Hub, and the project you are standing in tracks none of them. Nothing else in the CLI can see them.

API keys on Roblox for user 1234567890 (12 total):
  ✓ myproject_viewer         AAAAAAAAAA…  created 2026-08-03  in 90d           tracked → viewer
  ✓ otherproject_rbxshop     BBBBBBBBBB…  created 2026-06-18  in 44d           untracked
  ✗ oldgame_rbxshop          CCCCCCCCCC…  created 2026-05-18  EXPIRED 17d ago  untracked

1 tracked by this project, 11 untracked (3 expired, 1 disabled).

The fourth column is Roblox’s own secret preview, the same one the Creator Hub shows — the first characters of the secret and nothing more. It is enough to recognise a key you already hold without the tool ever storing the secret. The values above are placeholders: real previews are fragments of live credentials and do not belong in documentation.

Names are not identity

The join between the account and your lockfile is on cloud_auth_id, never on the name, for two measured reasons:

• your lockfile calls a key viewer while Roblox calls it myproject_viewer (name_prefix does this on purpose);
• two different accounts can each hold a key called deploy.

Matching on names would report your own key as untracked and offer it for deletion, or worse, tie your lockfile entry to a stranger’s key.

prune is deliberately awkward

prune lists the account, you select with space, and it deletes what you picked.

• Nothing is ever preselected. A prune where the safe answer is “press enter” eventually deletes a production key.
• There is no --all. delete --all is bounded by your lockfile; a prune --all would not be.
• Selecting a tracked key routes through the ordinary delete path, so the lockfile entry and stored secret go with it. An untracked key is deleted on Roblox only — the tool never had its secret.
• --dry-run prints the candidates and exits, which is the only non-interactive mode. Deleting other people’s keys from a script is not a workflow this supports.

The listing is scoped to the active cookie

Output starts with the account id for a reason: switching the signed-in Studio account changes which account answers, and the same key names recur across accounts. If the header says a user id you did not expect, stop before selecting anything.

Group-owned keys are not included by default. Pass --group-id. An empty result for a group you belong to means the listing was not asked for that group, not that the group has no keys.

The endpoint

Undocumented, and worth recording because nothing about it is guessable:

POST https://apis.roblox.com/cloud-authentication/v1/apiKeys
{"cursor": "", "limit": 100, "reverse": false, "groupId": <optional>}
→ {"cloudAuthInfo": [...], "nextCursor": "id_…", "previousCursor": "id_…"}

It is a POST that reads, and the resource is plural. Every GET spelling returns 404, and GET /v1/apiKey/list answers Malformed CloudAuthId because list lands in the by-id route. Cookie auth plus CSRF, like the rest of this crate. Found in the Creator Hub’s own bundle (getApiKeys → v1ApiKeysPost) and confirmed against the live API and the browser’s network log.

Machine-readable output

--json on the three reads — list, status and scopes show — writes one JSON document to stdout and nothing else. Everything that is not the result (the “N item(s) need attention” line, the status summary and its tip, the auto-detected-cookie notice, the unknown-key warning from rbxplace.toml) goes to stderr, so jq reads the pipe and a human still reads the terminal.

Nothing that writes takes it. create, update, regenerate, delete and prune all stop and ask before they act, and a format that owns stdout cannot stop and ask. resolve is excluded for a harder reason: it prints the raw secret, so there is no document that could carry its answer.

No secret, and no piece of one

This is the command that holds live Open Cloud credentials, and a document goes into a pipe, a CI log, an artifact upload. So the rule is absolute rather than careful: no field in any of these documents carries a secret or any part of one. Two consequences are worth stating, because both are things the human form does print:

• list --remote --json has no secret preview. The fourth column of the human listing is Roblox’s own preview, the first characters of a live secret, and it is there so a person can recognise a key on their own screen. A prefix is still credential material and a document is not a screen.
• list --json carries no path to the secret file. The human form prints set (file: .secrets/deploy.env) because the person reading it is standing in that directory. The document says secret_backend (lockfile or file) and secret_present, which is what a script needs; where on disk a credential lives is not something to publish next to a report about it.

Two more omissions, for the same reason applied one step further out:

• status --json carries no free-text detail. The human form’s trailing sentence is advice for a person, and one of its branches names the secret file. The status word says the same thing, so the document keeps the word and drops the sentence.
• list --remote --json carries no cloud_auth_id. The account listing prints a name, a preview, dates and a tracked tag, never the id, and most of the keys it returns belong to other checkouts and other tools. The local listing does print id: for the keys this project created, so the local document carries id.

rbx apikey list --json

What this project declares, joined to what it created: rbxapikey.toml and the lockfile, and nothing from Roblox.

{
  "schema_version": 1,
  "sort": "name",
  "count": 2,
  "keys": [
    {
      "name": "deploy",
      "declared": true,
      "created": true,
      "id": "f58b4055-cafe-4e2f-9c2a-000000000001",
      "creator_id": "1234567890",
      "universe_ids": ["5544332211"],
      "expires_at": "2027-08-01T10:00:00.000Z",
      "days_until_expiry": 351,
      "secret_present": true,
      "secret_backend": "file"
    },
    { "name": "newkey", "declared": true, "created": false, "universe_ids": [] }
  ]
}

declared and created are the two tags the human listing prints, kept as separate booleans rather than folded into one word: a declared key with no lockfile entry is pending, a lockfile entry with no declaration is an orphan, and they are fixed in opposite directions. Everything the lockfile would have said — id, creator_id, expires_at, both secret fields — is absent for a key that was never created.

days_until_expiry is negative once it has passed, and absent both when there is no expiry and when the timestamp could not be parsed, which is the (unparseable) the human listing marks. expires_at stays at full precision where the listing shortens it to the date.

sort says which order keys is in, because the order of an array is meaningful and a stored document should say which one it got. --expiry-only is refused alongside --json: it is a narrower rendering of the same rows, and a document has no narrower rendering. --sort is fine.

rbx apikey list --remote --json

What the account holds, which is mostly not this project’s doing. Same call as the human listing, so it costs no extra round trip: the users/authenticated request it already makes for the account line is the one that proves the session is live.

{
  "schema_version": 1,
  "owner": { "kind": "user", "id": "1234567890" },
  "totals": { "total": 12, "tracked": 1, "untracked": 11, "expired": 3, "disabled": 1 },
  "keys": [
    {
      "name": "myproject_viewer",
      "state": "active",
      "tracked": true,
      "tracked_as": "viewer",
      "created_time": "2026-08-03T09:15:00.123Z",
      "expiration_time": "2026-11-01T09:15:00.123Z",
      "days_until_expiry": 90
    },
    { "name": "otherproject_rbxshop", "state": "active", "tracked": false }
  ],
  "missing_on_account": []
}

owner is there for the same reason the human listing starts with the account id: switching the signed-in Studio account changes which account answers and the same key names recur across accounts. tracked_as is the lockfile’s name for a key, which is not the name Roblox has for it — name_prefix makes viewer into myproject_viewer on purpose — and it is absent when tracked is false. state is active, expired or disabled. missing_on_account lists lockfile names Roblox no longer has, the same warning the human form prints.

rbx apikey status --json

{
  "schema_version": 1,
  "remote": false,
  "count": 3,
  "issues": 1,
  "keys": [
    { "name": "deploy", "status": "HEALTHY", "healthy": true, "days_until_expiry": 351 },
    { "name": "newkey", "status": "PENDING", "healthy": false }
  ]
}

status is one of HEALTHY, PENDING, EXPIRED, EXPIRING_SOON, ORPHAN_LOCK, ORPHAN_REMOTE, SECRET_MISSING, DISABLED, CHECK_FAILED — the word the human form prints beside the glyph. healthy is true only for the first, so a gate reads one field instead of enumerating eight spellings of “no”. remote says whether Roblox was asked: ORPHAN_REMOTE cannot be reported without it, so a consumer that sees no orphan needs to know which of the two runs it is reading. issues is the count the human form prints as “N key(s) need attention”.

A drift between the lockfile and rbxplace.toml still fails the command outright, before any document is written. Empty stdout next to a non-zero exit says nothing was read.

rbx apikey status --json | jq -r '.keys[] | select(.healthy | not) | "\(.name): \(.status)"'

rbx apikey scopes show --json

{
  "schema_version": 1,
  "scope_type": "universe",
  "known": true,
  "catalog_version": "2026-05-13",
  "target_type": "universe",
  "operations": ["read", "write"]
}

The catalog is advisory: an unknown scope is a warning and never an error, and rbxapikey.toml forwards any string Roblox will take. So an unknown scope is a document with "known": false and exit 0, not a failure — and target_type and operations are absent there, because the catalog has no answer rather than an empty one. catalog_version is what tells “Roblox does not have this scope” from “this catalog is older than that scope”.

rbx doctor

Answer “why doesn’t it work” in one command. rbx doctor reads the credential that is actually loaded, asks Roblox what it holds for that key, compares it against the tools this directory configures, and makes one real authenticated call. Every check is read-only: doctor never creates, updates or deletes anything. Nothing it does contacts anyone but Roblox, unless you pass --check-ip — see the IP allowlist check.

Features

• Credential provenance - Which API key is live and where it came from. RBX_API_KEY is one variable shared by every tool, so the loaded key is often not the one you think
• Session validity - Whether Roblox still accepts the Studio cookie, and which account it signs in as
• Key validity - Enabled, expired, expiring soon, with the date and the time left
• IP allowlist - The CIDRs Roblox stores for the key, which fail as an opaque 401 when stale. With --check-ip, compared against this machine’s public address
• Scope coverage - For each config file present, which of that tool’s operations the key can and cannot run
• Read probe - One GET against a universe, to prove the whole chain works end to end
• Actionable failures - Every failing line carries what to do about it. A check that could not run says so, and is never reported as a pass

Usage

rbx doctor                          # Diagnose whatever RBX_API_KEY holds
rbx doctor --env prod               # Resolve the probe target from rbxplace.toml
rbx doctor --universe-id 123        # Name the probe target directly
rbx doctor --key deploy             # Diagnose a key declared in rbxapikey.toml
rbx doctor --no-probe               # Skip the authenticated read
rbx doctor --check-ip               # Also compare the IP allowlist (asks an echo service)

Output

rbx doctor

Credentials
  ✓ API key         RBX_API_KEY (environment)
  ! Studio cookie   auto-detected from a local Studio install
      → A session cookie is a full-account credential, more powerful than any scoped key. Pass
        --no-auto-cookie or set RBX_COOKIE= if you did not intend it.
  · rbxapikey.toml  3 key(s) declared, 3 created
  ✓ session         live — signed in as builderman (156)

Key validity
  · identified as  "deploy" (this project) — opsdev_deploy on Roblox
  ✓ enabled        yes
  ✓ expiry         2026-11-12T09:00:00Z (in 90d)

IP allowlist
  · allowed CIDRs  203.0.113.7/32
      → Not compared against this machine's public IP. Doing that means asking a third-party
        echo service (https://api.ipify.org) for an address this machine cannot read off its
        own interfaces, so it is opt-in: re-run with `--check-ip`. A stale entry here fails as
        an opaque 401 that looks exactly like a wrong key, so check it first when a call that
        should work does not. See docs/doctor.md.

Scope coverage
  · rbx place                        rbxplace.toml is here
  ✓ rbx place places                 covered
  ✗ rbx place upload / promote       missing universe-places:write
      → rbxplace.toml is here, so this is a call you can expect to make. Add
        universe-places:write to the key's `scopes` in rbxapikey.toml and run
        `rbx apikey update <key>`.

Read probe
  · target              universe 5544332211 (--env prod_readonly)
  ✓ authenticated read  200 — read "My Game"

1 problem(s) found.

Symbols

Exit status

0 when nothing is broken, 1 when a check failed. A check that could not run does not change the exit status, but the summary line says how many there were — the difference between “your scopes are fine” and “your scopes were never looked at” is the point of the command.

The checks

1. Which credential is active

The API key comes from --api-key, from RBX_API_KEY, or — with --key <name> — from the secret backend of a key declared in rbxapikey.toml. doctor says which, because RBX_API_KEY is a single variable shared by every tool in this suite and by anything else in your shell, so a key left over from another project is a routine cause of a refusal that looks like a scope problem.

The Studio cookie is reported separately: explicit (--cookie / RBX_COOKIE), auto-detected, or absent. An auto-detected cookie is a ! rather than a ✓ on purpose — a session cookie is a full-account credential, strictly more powerful than any scoped API key.

Its session is then checked, with one call to users.roblox.com/v1/users/authenticated: where the cookie came from is not the same question as whether Roblox still accepts it, and a cookie that has expired refuses every command that needs one. A live session passes and names the account it signs in as. A refused one fails, with both ways to renew it. No cookie is skipped rather than failed — most commands never need one — and so is a check that could not run at all, because a service that did not answer is not a session that was refused. See docs/cookie.md for which commands make the same check before writing.

2. Key validity

doctor identifies the loaded secret against the keys the signed-in account holds, matching on the secret preview Roblox publishes with each key — the same string the Creator Hub shows in its “Key” column. That is what makes the check work for a key you have been using for a month; rbx apikey introspect is authoritative but only while the JWT inside the secret is valid, roughly an hour after create or regenerate.

It then reports enabled, and expiry with the time remaining. A key inside two weeks of lapsing warns without failing.

This check needs the cookie, since Roblox’s key-administration endpoints are not on Open Cloud. Without one it is skipped, with the reason given, rather than passed.

3. IP allowlist

doctor always prints the CIDRs Roblox stores for the key. A stale entry fails as an opaque 401 that looks exactly like a wrong key, so seeing the allowed addresses next to the probe’s result is often enough to spot it.

Comparing them against this machine’s address is opt-in, behind --check-ip.

Why it is opt-in

A machine behind NAT cannot read its own public address off its interfaces. The only way to learn it is to ask something on the outside, which means telling a third party where you are — in a tool whose whole pitch is least privilege. So rbx doctor does not do it on its own initiative:

• Without --check-ip, no packet leaves for anyone but Roblox. The allowlist is printed with a line saying the comparison was not made, and the flag that would make it.
• With --check-ip, exactly one request goes out, to https://api.ipify.org. That service is named on the line that reports your address, not only here, so nobody finds out afterwards that a third party saw it.
• No request is made when the answer is already known. An empty allowlist, an allowlist containing 0.0.0.0/0, and a key whose configuration could not be read all answer the question without asking anyone, flag or no flag.

https://api.ipify.org was chosen for what it does not do: it answers GET / with the caller’s address as bare text and nothing else. No API key, no registration, no query string carrying anything about this machine beyond the connection itself.

What it reports

IP allowlist
  · allowed CIDRs  203.0.113.0/24, 198.51.100.7/32
  · public IP      203.0.113.9 — asked https://api.ipify.org, which therefore saw it
  ✓ this machine   203.0.113.9 is inside 203.0.113.0/24

and when it is not:

  ✗ this machine   198.51.100.42 is in none of the allowed CIDRs
      → Every call with this key is refused as an opaque 401 until the allowlist covers this
        address. Add 198.51.100.42/32 to the key's `allowed_cidrs` in rbxapikey.toml and run
        `rbx apikey update <key>`, or pass `--no-ip` to that command to drop the restriction.
        A home connection's address usually changes, so a host route written today is next
        month's 401.

What it never does

An unresolved address is never reported as a mismatch. Offline, service down, timed out, a captive portal answering with a login page — every one of those is a check that could not run (-), with the reason given, and none of them changes the exit status. A false “you are locked out” is expensive: it sends you to edit a key that is fine.

Three things produce a - rather than a ✓ or a ✗:

The lookup times out in 3 seconds, far below the 60s the rest of the suite allows. rbx doctor is what you run when the network is already misbehaving, so it stays usable offline: a caller with no connectivity gets their report back rather than a spinner.

4. Scope coverage

For each of rbxplace.toml, rbxmeta.toml, rbxconfig.toml and rbxshop.toml that is present, doctor lists that tool’s operations and whether the key carries the scopes each one needs. The requirements are the “Required API scopes” tables from each tool’s own doc.

Two limits worth knowing:

• Presence, not parsing. The unit of detection is the config file existing. doctor does not read rbxshop.toml to find out whether you actually declare badges, so a repo that only uses game passes is still told it cannot manage badges. Each line names the operation and the missing scope, so an operation you never run is visibly not your problem. The alternative — parsing every tool’s config properly — means depending on every domain crate in the workspace.
• Scope type and operation, not target. A scope’s targetParts name universes, datastores or creators, and deciding whether a given target covers a given call means resolving your env, which doctor would have to guess at. It answers the narrower question honestly: a key that lacks the scope outright is the failure people actually hit.

5. Read probe

One GET /cloud/v2/universes/{id} with the key. It needs universe:read, changes nothing, costs nothing, and is the same request rbx meta opens with — so a failure here is a failure you were going to hit anyway.

The target comes from --universe-id, from --env <name> against rbxplace.toml, or, when rbxplace.toml defines exactly one env, from that one. Which was used is printed before the result. With no target the probe is skipped rather than guessed at, and --no-probe skips it outright.

A refusal is read for you:

Related

• docs/apikey.md — declaring and creating the keys doctor reports on
• docs/ops.md — the safety model behind least-privilege keys

rbx check and rbx status

One command that runs every configured tool’s check and returns a single exit code. It is the CI contract: nothing to configure, nothing interactive, and the exit code is the whole answer.

rbx check                 # the standalone config blocks
rbx check --env all       # every env in rbxplace.toml
rbx check --offline       # skip anything that needs the network

rbx status is the same engine with the opposite contract: the human overview, grouped by environment, that always exits 0. See rbx status below.

Exit codes

This is the part scripts depend on, so it is the part to read carefully.

Aggregation is error beats drift beats clean. A run that both fails one check and finds drift in another exits 1, because “something is broken” and “something is stale” ask different things of whoever reads the log, and the broken one is the one that has to be read first.

Skipped checks never raise the exit code. A repo without rbxshop.toml is not a repo with a broken shop, and --offline is a deliberate narrowing, not a failure.

In GitHub Actions:

- run: rbx check --env all
  # fails the job on 1 and on 2 alike; use `continue-on-error` plus a
  # conditional on the outcome if drift should be a warning rather than a stop.

What it runs

A tool is checked when its config file is present in the working directory. There is no [check] block to maintain: the list of tools a repo uses is already on disk.

--dir moves that lookup, rbxplace.toml included, and an explicit --places overrides it for that one file. It is the same rule rbx import --dir writes by, so rbx import --dir game followed by rbx check --dir game reads the files the import just wrote:

Only config/live needs credentials, so --offline is a small cut: everything else compares committed files against committed files. That makes the offline mode usable from a pre-commit hook, which is the point of having it.

The key is only demanded once config/live has something to compare. With no --env, or with an env rbxconfig.toml never declares, the row is skipped and a keyless run still exits 0 without --offline.

Rows are named tool/check [env]. Per-env checks produce one row per env; with no --env, each tool falls back to its standalone block and the row is labelled [default], matching the [envs.default] section those tools already write.

Why this is not a wrapper around the per-tool checks

All five per-tool checks now agree on the contract — 0 clean, 2 drift, 1 error — so rbx check and rbx shop check no longer disagree on exit code for the same repo. Either can be trusted in CI; rbx check runs all of them at once, which is the only difference.

It still does not call the per-tool commands, for a reason that is about stdout rather than exit codes: those commands print as they decide, and under --json stdout belongs to the document — a probe that shelled into them would emit something jq cannot read. So each check rebuilds the comparison from the same public pieces the command itself uses — the renderers and plan builders, not a re-description of them — without touching any check body.

apikey is discovered but not checked

rbx apikey status classifies key health — expiry, orphan lockfile entries, missing secrets — and returns success whatever it finds, which the other per-tool checks no longer do. Reaching that classification from here would mean either widening rbx-apikey internals or writing a second copy of the rules, and a second copy of a rule that drifts from the first is the exact failure mode this command exists to catch.

So the row is reported as skipped, by name, with the command to run by hand:

- apikey/status    not yet wired — run `rbx apikey status`

Wiring it up properly means giving apikey status a structured result to return. That is worth doing and is not this change.

Flags

rbx check is non-interactive by construction: it never prompts, so it is safe to run with no TTY.

--json

rbx check --env all --json

One JSON document on stdout, nothing else. Diagnostics stay on stderr and the exit code is unchanged, so a consumer can read the document, the stream, or the status — whichever suits — and get the same answer.

{
  "schema_version": 1,
  "outcome": "drift",
  "exit_code": 2,
  "totals": { "total": 4, "clean": 0, "drift": 2, "error": 0, "skipped": 2 },
  "checks": [
    {
      "tool": "env",
      "check": "gen-module",
      "outcome": "skipped",
      "summary": "no [codegen].output in rbxplace.toml"
    },
    {
      "tool": "meta",
      "check": "lockfile",
      "env": "prod",
      "outcome": "drift",
      "summary": "2 pending changes — run `rbx meta sync`",
      "details": ["name: (unset) → My Game (Live)", "server size: (unset) → 50"]
    }
  ]
}

Fields

These names are the contract. Adding a field is not a breaking change — consumers are expected to ignore what they do not recognise — but a field changing meaning or disappearing bumps schema_version.

Optional fields are omitted rather than emitted as null, so has("env") is a usable test. Every row is an object keyed by name, never a positional array: a consumer survives a field being added, and does not survive a column shifting.

In GitHub Actions

rbx check --env all --json > check.json || true
jq -r '.checks[] | select(.outcome == "drift")
       | "::warning title=rbx drift::\(.tool)/\(.check) \(.env // "") — \(.summary)"' check.json
exit "$(jq -r '.exit_code' check.json)"

Scope

--json covers every read in the JSON issue, not just the check family: check and status, env list/get, servers list/versions/logs, analytics query/metrics, ads list/get/status, place versions/places and the receipts from place upload/promote/rollback, data get/list/revisions/diff, memorystore get/list, shop list/show, config list/get/versions, ban list/status, apikey list/status and apikey scopes show, plus the receipt from publish. Per-command field names are documented alongside each command.

What every one of them shares is the helper — rbx_core::output is the only place in the tree that serializes to stdout, which is what keeps --json meaning the same thing everywhere: one document, notes and warnings on stderr, optional fields omitted rather than null, and no prompt, ever. Commands that stop and ask do not carry the flag at all.

Example

$ rbx check --env all --offline
rbx check
  - env/gen-module        no [codegen].output in rbxplace.toml
  ✓ shop/lockfile [dev]   everything in sync
  ! shop/lockfile [prod]  1 to create, 0 to update — run `rbx shop sync`
  ✓ shop/codegen          generated modules match rbxshop.toml
  ! meta/lockfile [prod]  2 pending changes — run `rbx meta sync`
      name: (unset) → My Game (Live)
      server size: (unset) → 50
  - config/live           --offline: comparing against Roblox needs an API key
  - apikey/status         not yet wired — run `rbx apikey status`

! 2 checks found drift (2 clean, 3 skipped). Exit code 2.

The checks that compose an existing command (env/gen-module, shop/codegen) print their own per-file detail above this summary, since that detail is what tells you which generated file went stale.

rbx status

The human half. Same discovery, same checks, same rows — regrouped by environment and stripped of the exit-code contract.

rbx status                  # the standalone config blocks
rbx status --env all        # every env in rbxplace.toml
rbx status --offline        # the overview you can get with no key and no network
rbx status --json           # the document below, identical in shape to check's

$ rbx status --env all --offline
rbx status

  - repository
      - env/gen-module  no [codegen].output in rbxplace.toml

  ! dev
      ! meta/lockfile   1 pending change — run `rbx meta sync`
          name: (unset) → My Game (dev)

  ✓ prod
      ✓ meta/lockfile   everything in sync

! 1 check out of sync. Re-run the tool's own sync, or `rbx check` for the CI verdict.
rbx status always exits 0; rbx check here would exit 2.

Always exit 0 is the point. A status command that fails a script is a check command with worse output — so rbx status is safe under set -e, in a shell prompt, in a watch, and in the first line of a Makefile target that then does something else. When you want the verdict, that is what rbx check is for, and the last line says which one it would be. A repository it cannot read at all is no exception: an unreadable or env-less rbxplace.toml prints as an env/discovery error row, and the command still exits 0.

The repository block holds the checks that are not per-env (env/gen-module compares a generated file, apikey/status answers for the credential). Environments follow it in alphabetical order, which is the order --env all expands them in.

It reads nothing it does not read for check, writes nothing, and is useful with no API key — --offline renders the local half and marks the live rows skipped rather than refusing to run.

rbx status --json

The same document rbx check --json emits, field for field, so a consumer can read either. One value is worth naming: exit_code is what rbx check would return for this repository, since rbx status itself always exits 0. It is the field to branch on if you want the verdict without the check’s exit code:

rbx status --env all --json > status.json   # always exits 0
jq -r '.checks[] | select(.outcome != "clean") | "\(.env // "repo") \(.tool)/\(.check): \(.summary)"' status.json

Related

• docs/env.md — rbx env gen-module --check and the ignored-key policy
• docs/ops.md — which commands touch live state

rbx place

Upload, download, and rollback Roblox place files via the Open Cloud API.

rbx place manages .rbxl files across multiple environments (prod, staging, dev) defined in a shared rbxplace.toml. It handles Team Create locks gracefully and can require confirmation before writing to sensitive environments.

Features

• Multi-environment - Define prod, staging, dev (and any others) in a single rbxplace.toml
• Upload - Push a .rbxl to one place or all places in an environment at once
• Download - Fetch the latest or a specific version of a place file
• Promote - Copy a place from one environment to another, optionally broadcasting to all target places
• Rollback - Revert a place to a previous version with an interactive selector
• Version history - List recent versions with published status and timestamps
• Team Create detection - Clear error when a place is locked by an active Studio session
• Confirmation guard - Per-environment confirm = true prompts before write operations
• Fetch - Auto-populate rbxplace.toml from live Roblox universe
• JSON - --json on versions, places, upload, promote and rollback writes one document to stdout and nothing else, with documented field names, for jq and CI

Generating the env module lives in rbx env gen-module, the command that owns rbxplace.toml.

Quick start

Create a rbxplace.toml at the root of your project:

[prod]
universe_id = 9876543210
confirm = true
places.main = 123456789012345

[staging]
universe_id = 9876543211
places.main = 234567890123456

[dev]
universe_id = 9876543212
places.main = 345678901234567

Then upload a build:

rbx place upload --env staging --file build.rbxl
rbx place upload --env prod --file build.rbxl   # prompts for confirmation

Commands

rbx place upload --env staging --file build.rbxl           # save as draft
rbx place upload --env prod --place lobby --file build.rbxl --published  # publish live
rbx place upload --env prod --all-places --file build.rbxl

rbx place upload --env staging --file build.rbxl --json

{
  "schema_version": 1,
  "command": "upload",
  "ok": true,
  "env": "staging",
  "universe_id": "9876543211",
  "published": false,
  "place_id": "234567890123456",
  "version": "173",
  "results": [{ "place": "main", "place_id": "234567890123456", "version": "173" }]
}

VERSION=$(rbx place upload --env staging --file build.rbxl --json | jq -r .version)

rbx place download --env prod
rbx place download --env prod --version 42 --out backup.rbxl
rbx place download --env staging --published
rbx place download --env staging --saved

rbx place promote --from staging --to prod                         # latest → matching place
rbx place promote --from staging --to prod --all-places            # latest → every place in prod
rbx place promote --from staging --to prod --from-published        # latest published version
rbx place promote --from dev --to staging --version 42 --published # specific version, publish live
rbx place promote --from staging --to prod --log deploy.json       # write traceability log

# prod's main, lobby and arena all become copies of staging's main
rbx place promote --from staging --to prod --all-places

⚠ Promote staging/main v172 → prod (arena, lobby, main)? This will save as draft.
  Every one of them is overwritten with staging/main, not with its own counterpart.

{
  "main": {
    "deployedAt": "2026-05-14T15:30:00+01:00",
    "staging": { "universeId": 9876543210, "placeId": 123456789012345, "version": 172 },
    "production": { "universeId": 9876543211, "placeId": 234567890123456, "version": 27 }
  }
}

rbx place promote --from staging --to prod --from-published --published --yes --json

{
  "schema_version": 1,
  "command": "promote",
  "ok": true,
  "env": "prod",
  "from_env": "staging",
  "universe_id": "9876543211",
  "published": true,
  "source_place": "main",
  "source_place_id": "123456789012345",
  "source_version": "172",
  "place_id": "234567890123456",
  "version": "27",
  "results": [{ "place": "main", "place_id": "234567890123456", "version": "27" }]
}

rbx place rollback --env prod               # interactive selector
rbx place rollback --env prod --version 42  # direct rollback
rbx place rollback --env prod --count 20    # show 20 versions in selector

rbx place rollback --env prod --version 37 --yes --json

{
  "schema_version": 1,
  "command": "rollback",
  "ok": true,
  "env": "prod",
  "universe_id": "9876543210",
  "published": true,
  "source_version": "37",
  "place_id": "123456789012345",
  "version": "44",
  "results": [{ "place": "main", "place_id": "123456789012345", "version": "44" }]
}

rbx place versions --env prod
rbx place versions --env staging --count 50
rbx place versions --env prod --filter published
rbx place versions --env prod --filter saved

{
  "schema_version": 1,
  "env": "prod",
  "place": "main",
  "place_id": "123456789012345",
  "filter": "all",
  "count": 20,
  "count_reached": false,
  "versions": [
    { "version": "173", "published": true, "create_time": "2024-01-15T14:30:00Z" },
    { "version": "172", "published": false, "create_time": "2024-01-14T09:02:00Z" }
  ]
}

rbx place versions --env prod --json | jq -r '.versions[] | select(.published) | .version' | head -1

rbx place places --env prod                    # list places, show which are in toml
rbx place places --universe-id 9876543210     # list places without config

{
  "schema_version": 1,
  "env": "prod",
  "universe_id": "9876543210",
  "places": [
    {
      "place_id": "123456789012345",
      "display_name": "Main Place",
      "max_player_count": 50,
      "place": "main",
      "configured": true
    },
    { "place_id": "987654321", "display_name": "Test Arena", "configured": false }
  ]
}

rbx place places --env prod --json | jq -r '.places[] | select(.configured | not) | .place_id'

rbx place fetch --env prod              # dry-run: shows what would be written
rbx place fetch --env prod --write      # writes to rbxplace.toml
rbx place fetch --env prod --universe-id 9876543210 --write  # override universe

Write documents

upload, promote, and rollback share one --json envelope. It is a receipt: it reports what was written, in the order it was written, with the version number Roblox assigned to each place.

Three rules are worth stating outright, because scripts depend on them:

A run that fails partway still emits a document. place upload --all-places can write two places and then hit a Team Create lock on the third. Those two versions exist and cannot be taken back, so results reports them, ok is false, error says what stopped it, and the process still exits non-zero. A deploy log that loses a write that happened is worse than no log.

A failure before the first write, on the other hand, writes nothing to stdout at all: an unknown environment, a refused confirmation, a source version that does not exist. Nothing happened, and an empty stdout next to a non-zero exit says so without ambiguity.

The shape follows the invocation, never the data. A single-target run fills the place_id and version shortcuts next to results; an --all-places run fills results only, even against an environment with exactly one place. This is the rule rbx env get --json uses for value, and it exists so a filter cannot start working by accident and break when a second place is added.

Ids and version numbers are strings. They identify an asset rather than count anything, a place id exceeds 2^53, and a consumer that parses them as JSON numbers would round them. Keeping versions in the same form means the output of one command feeds the input of the next without a conversion:

VERSION=$(rbx place upload --env prod --file build.rbxl --published --yes --json | jq -r .version)
rbx servers list --env prod --version "$VERSION" --json

--json never prompts. Every write here has a point where it would stop and ask, and under --json that question fails instead, with a message on stderr naming the flag that answers it: --yes for a confirm = true environment, --version for the rollback selector.

Configuration

rbx place reads rbxplace.toml in the working directory (override with the global --places <path>). You can configure place IDs manually or use rbx place fetch to auto-populate them from a Roblox universe.

[prod]
universe_id = 9876543210
confirm = true                  # prompt before upload or rollback
places.main   = 123456789012345
places.lobby  = 987654321

[staging]
universe_id = 9876543211
places.main = 234567890123456

[dev]
universe_id = 9876543212
places.main = 345678901234567

The rbxplace.toml file is shared with every other subcommand: they all resolve environment names to universe IDs from it.

Working without rbxplace.toml

The global --place-id names a place directly, the way --universe-id names a universe, and skips the config file. It reaches the reads:

rbx place versions --place-id 123456789012345
rbx place download --place-id 123456789012345 --out backup.rbxl

The writes refuse it, with a message saying why:

`--place-id` names a place but no env, and `rbx place upload` needs one: the confirm
guard and the --json receipt are both env-scoped. Pass --env <name> ...

Two things are genuinely env-scoped and neither survives an id on its own. confirm = true is declared on an env, so an env-less write would walk past a guard somebody set on purpose. And the --json receipt carries env as a documented field, so an env-less write would emit a document missing something consumers were told to expect. Refusing beats either, and beats accepting the flag and ignoring it.

Required API scopes

rbx meta

Declaratively manage Roblox game/universe metadata from a single TOML config: name, description, icon, thumbnails, devices, social links, private servers, server fill mode, copying permission, visibility, Studio API access, and Beta mode. Multi-env aware via a shared rbxplace.toml.

rbx meta syncs your local metadata to Roblox, tracks remote state in a per-env lockfile, detects media changes with BLAKE3 hashing, and uses the Open Cloud API by default with an optional .ROBLOSECURITY cookie fallback for fields Open Cloud doesn’t expose.

Features

• Declarative config - Define every metadata field in a single rbxmeta.toml
• Multi-environment - Manage dev / staging / prod from one toml, with [envs.<name>] overlays merged on top of base
• Differential pull - Writes only what diverges from your base config so the toml stays minimal
• Two-way sync - Push local config to Roblox or pull remote state back into your toml + lockfile (comments preserved via toml_edit)
• Open Cloud first - Runs in CI with just an API key; cookie only needed for the handful of cookie-only fields
• Cookie fallback - Auto-detects .ROBLOSECURITY from a local Roblox Studio install for server_fill, allow_copying, visibility, studio_access_to_apis_allowed, and beta_mode
• Smart visibility ordering - When toggling private→public, rbx meta activates the experience first so dependent patches (e.g. paid private servers) don’t 500
• Preflight validations - Refuses obviously-invalid combinations (e.g. private_server.price 1-9 Robux, or paid private servers on a private experience) before sending a request
• Per-env media namespacing - pull --accept-remote --env dev saves to <media.dir>/dev/icon.png so envs never overwrite each other on disk
• Crash-safe lockfile - Saved after every successful API call so a mid-sync crash never leaves remote and lockfile in disagreement
• Smart media diff - Icons and thumbnails are hashed with BLAKE3 so re-uploads only happen when bytes actually change
• Thumbnail ordering - Preserves the order from your TOML, auto-reorders on Roblox as needed
• Alpha bleed - Applies alpha bleeding to icons and thumbnails before uploading (enabled by default)
• CSRF handled - Cookie requests transparently retry on 403 with a fresh token

Quick start

Multi-env (recommended): point at a shared rbxplace.toml

If you already use rbx place / rbx config, you have a rbxplace.toml like:

[dev]
universe_id = 9876543210
[dev.places]
main = 123456789012345

[prod]
universe_id = 9876543211
[prod.places]
main = 234567890123456

Pull each env once to populate rbxmeta.toml:

rbx meta init                                          # commented template
rbx meta pull --env dev --accept-remote --api-key KEY  # fills [game], [media] + [envs.dev] deltas
rbx meta pull --env prod --accept-remote --api-key KEY # adds only diverging fields to [envs.prod]
rbx meta sync --env dev                                # apply changes back to dev

Standalone (no rbxplace.toml)

rbx meta init --from-remote --universe-id 123456789 --place-id 987654321 --api-key KEY
rbx meta sync --api-key KEY

This embeds [experience] in rbxmeta.toml and uses it as the implicit “default” env (lockfile section: [envs.default]).

Hybrid: –from-remote with –env

rbx meta init --from-remote --env dev --api-key KEY

Resolves universe_id / place_id from rbxplace.toml and writes the lockfile under [envs.dev]. Useful for starting fresh on an existing experience without copy-pasting IDs.

Multi-environment

Three concepts:

1. Base ([game] + [media]): the values shared across every env.
2. Overlay ([envs.<name>], [envs.<name>.devices], [envs.<name>.media], etc.): per-env diffs layered on top of base.
3. Resolution: --env <name> resolves (universe_id, place_id) from rbxplace.toml and merges base + overlay for that env.

sync --env dev applies [game] + [envs.dev] to dev. sync --env prod applies [game] + [envs.prod] to prod. Same rbxmeta.toml, different effective state.

Pull behavior (differential)

For each field, when you pull --env <name>:

Concrete example: starting from an empty config, pull --env prod (visibility=public) writes [game] visibility = "public". Then pull --env dev (visibility=private) only writes [envs.dev] visibility = "private". Subsequent pulls are idempotent.

Pull never auto-promotes overlays back into base. To DRY, edit the toml manually to move a shared value into [game]; the next pull will detect the match and remove the now-redundant overlay.

Place selection

When the env in rbxplace.toml has multiple places ([prod.places.lobby], [prod.places.world]), pass --place <name>. Defaults to main if present, otherwise the only entry.

One place per env, and the tool enforces it. rbxmeta.lock.toml keys its sections by env and holds a single place_id in each, while name, description and server_size are place-level fields written to that place. So syncing --place lobby and then --place main under one env would leave [envs.prod] recording one place’s metadata under the other’s id — and every later diff, which is what decides whether a field gets sent at all, would be computed against the wrong baseline.

sync and pull therefore refuse a place that disagrees with the one the section already tracks:

Lockfile env 'prod' tracks place_id 234567890123456 but the resolved target is 234567890999999.
This env has more than one place and the lockfile holds one, so writing the second would record
its metadata under the first one's id. Use one place per env, or delete the [envs.prod] section
if you meant to move it.

If you genuinely manage metadata on two places, give them an env each in rbxplace.toml pointing at the same universe_id. Universe-level fields (voice_chat, devices, private_server, social_links, visibility) apply to the whole experience either way, so declare those in [game] and keep the per-env overlays to the place-level ones.

Commands

Per-tool flags

Configuration

rbx meta requires a rbxmeta.toml file in the working directory (or specify with --config).

[experience] is optional and only used in standalone mode (no --env). When you pass --env <name>, universe_id / place_id come from rbxplace.toml. Per-env overrides go under [envs.<name>] and are layered on top of [game] / [media].

[experience]                 # optional, omit if you always pass --env
universe_id = 123456789
place_id = 987654321         # root place, name/description/server_size go here

[game]
name = "My Awesome Game"
description = "A really fun multiplayer game."
server_size = 50             # max concurrent players per server
voice_chat = false
genre = "adventure"          # cookie-only, legacy genre list
engine_avatar_settings = "avatar-settings.toml"   # cookie-only, opaque passthrough

# The fields below have no Open Cloud endpoint, so a `sync` whose plan touches
# one needs a session cookie. Leave them out and the rest of this file syncs
# with an API key alone. See "Cookie-only fields" further down.
visibility = "public"                   # "public" | "private", write requires cookie
studio_access_to_apis_allowed = true    # cookie-only, Studio can call DataStore/Open Cloud
beta_mode = false                       # cookie-only, true = hides from Home Recommendations

[game.private_server]
price = 100                  # Robux. 0 = free, >= 10 = paid. Omit table to disable private servers.

[game.devices]
desktop = true
mobile = true
tablet = true
console = false
vr = false

[game.server_fill]
mode = "custom"              # cookie-only
reserved_slots = 5           # only with mode = "custom"

[game.social_links.discord]
title = "Join our Discord"
url = "https://discord.gg/example"

# All four keys or none — Roblox takes this object whole. Cookie-only, and
# write-only: no Roblox endpoint returns it, so `pull` cannot adopt it.
[game.permissions]
third_party_teleport = false
third_party_asset = false
third_party_purchase = false
client_teleport = true

[game.avatar]
type = "player_choice"               # "r6" | "r15" | "player_choice"
animation = "player_choice"          # "standard" | "player_choice"
collision = "outer_box"              # "inner_box" | "outer_box"
joint_positioning = "artist_intent"  # "standard" | "artist_intent"

# Both scale tables need all five keys. Write-only, like [game.permissions].
[game.avatar.min_scale]
height = 0.9
width = 0.7
head = 0.95
body_type = 0.0
proportion = 0.0

# All ten slots or none, for the same reason as [game.permissions]: Roblox
# replaces the array rather than merging into it. Write-only.
[game.avatar.asset_overrides]
face = "player_choice"
head = "player_choice"
torso = "player_choice"
left_arm = "player_choice"
right_arm = "player_choice"
left_leg = "player_choice"
right_leg = "player_choice"
t_shirt = "player_choice"
shirt = "player_choice"
pants = 12345678            # an asset id forces that slot

# Omit this table to leave paid access unmanaged. `mode = "free"` is an
# instruction to turn it off, which is not the same thing.
[game.paid_access]
mode = "paid"                # "free" | "paid"
price = 25                   # Robux, only with mode = "paid"

[media]
icon = "assets/icon.png"
thumbnails = ["assets/thumb1.png", "assets/thumb2.png"]
dir = "assets"               # destination for `pull --accept-remote` downloads
bleed = true
language_code = "en_us"

# Per-env overrides (optional). Layered on top of [game] / [media] when
# --env <name> is passed.
[envs.dev]
visibility = "private"

[game.avatar.asset_overrides]
face = "player_choice"
head = "player_choice"
torso = "player_choice"
left_arm = "player_choice"
right_arm = "player_choice"
left_leg = "player_choice"
right_leg = "player_choice"
t_shirt = "player_choice"
shirt = 987654321
pants = 12345678

Error: `engine_avatar_settings` describes the same settings as these fields,
and this sync would send both:

  game.avatar.min_scale  ·  also set by AvatarBodyRules in the document

Keep whichever one you maintain and remove the other from rbxmeta.toml.

  ✓ legacy universe config patched
  ! Roblox did not keep 1 avatar key — it was not applied:
      AvatarRules.AvatarTpye
    A misspelling is the usual cause. The rest of the document applied.

[game]
engine_avatar_settings = "avatar-settings.toml"

# avatar-settings.toml — the same document the JSON form would carry
version = 1

[AvatarRules]
AvatarType = 1

[AvatarCollisionRules]
CollisionMode = 1
SingleColliderSize = [2, 3, 1]

Field coverage

Not supported

Open Cloud does not expose these fields and rbx meta does not (yet) handle them via cookie:

• Friends-only visibility (only public / private supported; the API field is isFriendsOnly)
• Age rating (write)
• optInRegions / optOutRegions. Declined rather than pending; the reasoning is in TODO.md. In short: the enum has one real value (China), it is write-only like the fields above, and whether an experience is actually available there is decided by a Roblox moderation status that no config file can set. A key that looked like a switch would be a request
• Badges, game passes, developer products - use rbx shop instead

Write-only fields

A field being cookie-only means the API key alone cannot write it. A field being write-only means something stronger: Roblox exposes no request that returns it, so nothing can read it back.

• game.permissions.*
• game.avatar.min_scale, game.avatar.max_scale
• game.avatar.asset_overrides
• game.engine_avatar_settings

The read used by pull and init is GET /v1/universes/{id}/configuration, and it carries neither. The endpoint that does — /v2/universes/{id}/configuration — answers to PATCH only.

The consequence, in one sentence: pull never touches these, and check compares them against the lockfile rather than against Roblox. A pull keeps whatever the previous lockfile recorded for them rather than adopting what the config asks for — taking the config’s word would make the lockfile assert that Roblox holds a value nobody checked, and the next sync would then send nothing while check reported agreement. Setting one in the Creator Dashboard will not show up as drift; the next sync that touches the field will simply overwrite it.

Cookie-only fields

The Open Cloud API doesn’t expose every metadata field. These fields require a cookie:

• game.server_fill
• game.allow_copying
• game.visibility (write only; read is via Open Cloud)
• game.studio_access_to_apis_allowed
• game.beta_mode
• game.genre
• game.avatar.*
• game.engine_avatar_settings
• game.paid_access
• game.permissions.*

The cookie is provided via the global --cookie flag, the RBX_COOKIE env var, or a local Roblox Studio install (Windows registry, macOS plist) — that last one opt-in, asked once or declined where there is nobody to ask. --auto-cookie is the standing yes and --no-auto-cookie the standing no. pull and init skip these fields and say so when no cookie is available; sync stops before applying anything if the plan touches one.

A cookie that exists is not a cookie that still works, so when the plan touches one of these fields sync also asks Roblox once, before the confirmation prompt and before the first write, whether the session is still valid. An expired one refuses the whole run rather than applying the Open Cloud half and failing on the legacy half. See what is checked.

The credential itself is documented once, in docs/cookie.md: the full resolution order, what an auto-detected cookie prints on stderr, and why it is never written to disk.

Tip: pipe the cookie from Lune without touching Studio’s local files yourself:

# helper script (Lune)
echo 'local roblox = require("@lune/roblox"); io.write(roblox.getAuthCookie(true) or "")' > get-cookie.luau

# bash
export RBX_COOKIE=$(lune run get-cookie)
# PowerShell
$env:RBX_COOKIE = (lune run get-cookie)

Required API scopes

Lockfile

rbx meta generates a rbxmeta.lock.toml next to the config that tracks the last-applied state per env:

version = 1

[envs.dev]
universe_id = ...
place_id = ...
[envs.dev.game]
# ... mirror of [game] + [envs.dev] resolved state
[envs.dev.media.icon]
hash = "..."
image_id = ...

[envs.prod]
# ...

Standalone mode (no --env) writes under [envs.default]. Commit the lockfile to version control.

sync --env <name> is idempotent: only fields differing between the resolved (base + overlay) config and [envs.<name>] in the lockfile are sent. Media re-uploads happen only when the local file hash differs from the lockfile hash.

How it works

sync --env <name> resolves (Game, MediaConfig) for that env (base + overlay), builds a SyncPlan against [envs.<name>] in the lockfile, and applies it in this order:

0. Check the session (cookie), only when the plan contains a cookie-only field. One call, before anything is sent, so a dead session changes nothing at all.
1. Activate (legacy / cookie) if visibility is going from private to public. Must be first so dependent patches (like paid private servers) don’t 500.
2. PATCH universe (Open Cloud): voice chat, private server price, devices, social links
3. PATCH place (Open Cloud): name, description, server size
4. PATCH place legacy (cookie): server_fill, allow_copying
5. PATCH universe configuration legacy (cookie): studio_access_to_apis_allowed
6. POST experience-releases (cookie): beta_mode toggle
7. Deactivate (legacy / cookie) if visibility is going from public to private. Last so the universe stays in its permissive state until everything else is patched.
8. Upload icon if its BLAKE3 hash differs from the lockfile
9. Delete thumbnails removed from config, upload new ones, reorder to match the toml order

The lockfile is saved after every successful API call (including each individual thumbnail delete and upload) so a crash mid-sync never leaves remote and lockfile in disagreement.

Preflight validations

Before sending any request, rbx meta validates locally:

• private_server.price is 0 or >= 10 (Roblox rejects 1-9 Robux)
• visibility = "private" with private_server.price > 0 is invalid (Roblox requires public)
• Referenced media.icon and media.thumbnails[] paths exist on disk

When a Roblox call still fails for a known reason rbx meta couldn’t detect locally (e.g. the 60-day cooldown on private server price changes), the error message includes a hint pointing to Creator Hub for the real diagnostic.

Retries

429 and 5xx responses are retried with exponential backoff (max 3 attempts). 403 responses carrying x-csrf-token (cookie flow) are retried transparently after caching the new token.

Attributions

The alpha bleeding implementation, used through rbx shop, is adapted from Asphalt (MIT), which itself adapted it from Tarmac (MIT). Thank you to both. The license notices are in THIRD-PARTY-NOTICES.md.

rbx config

Manage Roblox in-experience live configs via the Open Cloud Configs API.

rbx config keeps a local rbxconfig.toml as the canonical source of truth for your in-experience tunables and syncs it to Roblox. It targets environments defined in a shared rbxplace.toml, shows diffs before publishing, and supports gradual rollout.

Features

• Declarative config - All tunables in a single rbxconfig.toml, organized per environment
• Diff preview - check and sync --dry-run show exactly what changes before any publish
• Full sync - rbxconfig.toml is the canonical state: missing keys are removed from live
• Pull - Mirror the live config back into rbxconfig.toml, preserving local descriptions
• Revision history - versions and rollback to inspect and revert past publishes
• Gradual rollout - Optional GradualRollout deployment strategy (~15 min propagation)
• Multi-environment - Targets environments defined in rbxplace.toml (shared with rbx place)
• JSON - --json on get, list and versions writes one document to stdout and nothing else, with documented field names, for jq and CI

Quick start

# Bootstrap a template
rbx config init

# Or pull the existing live config into a local file
rbx config pull --env dev --api-key YOUR_API_KEY

# Edit rbxconfig.toml, then preview + publish
rbx config check --env dev --api-key YOUR_API_KEY
rbx config sync  --env dev --api-key YOUR_API_KEY

--env is required on all commands except init. It is resolved against rbxplace.toml (override with the global --places).

Commands

rbx config init
rbx config --config configs/rbxconfig.toml init

rbx config get --env dev
rbx config get "features.new_xp_popup" --env dev

rbx config get "ops.teleport_place_id" --env dev --json

{
  "schema_version": 1,
  "env": "dev",
  "universe_id": 9876543210,
  "config_version": 14,
  "key": "ops.teleport_place_id",
  "value": 12345,
  "entries": {
    "ops.teleport_place_id": { "type": "number", "value": 12345 }
  }
}

PLACE=$(rbx config get "ops.teleport_place_id" --env dev --json | jq -r .value)
rbx config get --env dev --json | jq -r '.entries | to_entries[] | select(.value.type == "bool") | .key'

rbx config list --env dev

Live config keys - env: dev (configVersion 14)
  balance.speed_multipliers  [object]  {"tier_1":1.5,"tier_2":2}
  features.new_xp_popup      [bool]    true
  ops.teleport_place_id      [number]  12345

rbx config list --env dev --json

{
  "schema_version": 1,
  "env": "dev",
  "universe_id": 9876543210,
  "config_version": 14,
  "entries": {
    "balance.speed_multipliers": { "type": "object", "value": { "tier_1": 1.5, "tier_2": 2 } },
    "features.new_xp_popup": { "type": "bool", "value": true },
    "ops.teleport_place_id": { "type": "number", "value": 12345 }
  }
}

rbx config list --env dev --json | jq -r '.entries | keys[]'
rbx config list --env prod --json | jq -r .config_version

rbx config check --env dev

rbx config sync --env dev --dry-run    # preview only
rbx config sync --env dev              # prompts for confirmation
rbx config sync --env dev --yes        # skip confirmation
rbx config sync --env dev --strategy gradual-rollout

rbx config pull --env dev
rbx config pull --env dev --yes       # overwrite without confirmation
rbx config --config staging.toml pull --env dev   # write to a different file

rbx config versions --env dev
rbx config versions --env dev --count 50

rbx config versions --env dev --json

{
  "schema_version": 1,
  "env": "dev",
  "universe_id": 9876543210,
  "count": 20,
  "count_reached": false,
  "revisions": [
    {
      "revision_id": "aaaaaaaa-1111-4000-8000-000000000001",
      "version": 14,
      "time": "2026-08-15T09:30:00Z",
      "message": "raise the cap",
      "changed_keys": ["balance.speed_multipliers", "ops.teleport_place_id"],
      "published": true
    },
    {
      "revision_id": "bbbbbbbb-2222-4000-8000-000000000002",
      "version": 13,
      "time": "2026-08-14T09:30:00Z",
      "changed_keys": [],
      "published": false
    }
  ]
}

rbx config versions --env prod --json | jq -r '.revisions[] | select(.published) | .revision_id'
rbx config versions --env prod --count 50 --json | jq -r '.revisions[].changed_keys[]' | sort | uniq -c

rbx config rollback --env dev                   # interactive picker
rbx config rollback --env dev <revision_id>     # direct
rbx config rollback --env dev --count 30        # picker with more entries

Per-tool flags

Configuration

rbxplace.toml

rbx config resolves environment names to universe IDs from rbxplace.toml (shared with rbx place):

[prod]
universe_id = 9876543210
places.main = 123456789012345

[staging]
universe_id = 9876543211
places.main = 234567890123456

Pass a different path via the global --places, or skip the lookup entirely with --universe-id <id>. Each env section may set confirm = true to force interactive confirmation before any write to that env.

rbxconfig.toml

The local source of truth for your tunables, organized per environment. Every entry under [<env>.entries."key"] is synced as a config key. Scalars become scalar values; tables become JSON objects. Each entry has a required value and an optional description (local-only - not sent to Roblox).

[prod.entries."features.new_xp_popup"]
value = false
description = "Disabled in prod until stable"

[prod.entries."ops.teleport_place_id"]
value = 12345

[prod.entries."balance.speed_multipliers"]
value = { tier_1 = 1.5, tier_2 = 2.0 }

[staging.entries."features.new_xp_popup"]
value = true
description = "Testing new popup - remove in v2"

Dotted key names (e.g. "features.new_xp_popup") are preserved verbatim as the Roblox config key. In-game, read them with:

ConfigService:GetConfigAsync():GetValue("features.new_xp_popup")

rbxconfig.lock.toml

Written automatically by pull and sync, next to rbxconfig.toml. Records, per environment, the last published revision_id (the v{N} configVersion), the synced_at timestamp, and a snapshot of the entries that were pushed or pulled. Informational only - not sent to Roblox. Commit it if you want to track sync history alongside your config.

version = 1

[envs.prod]
revision_id = "v14"
synced_at = "2024-01-15T14:30:00Z"

[envs.prod.entries]
"features.new_xp_popup" = false
"ops.teleport_place_id" = 12345
"balance.speed_multipliers" = { tier_1 = 1.5, tier_2 = 2.0 }

Required API scopes

Deployment strategies

Gradual rollout incrementally applies the config across servers, reducing the blast radius of a bad config push.

rbx shop

Declaratively manage Roblox game passes, badges, and developer products from a single TOML config file - with first-class multi-environment support (dev/staging/prod universes from one source).

rbx shop syncs your local configuration to Roblox, tracks remote state in a per-env lockfile, detects icon changes with BLAKE3 hashing, and generates a typed Luau module folder that resolves the right asset IDs at runtime via game.GameId.

Features

• Declarative config: define all your passes, badges, and products in a single rbxshop.toml
• Multi-env overlays: [envs.<name>] overlays layered on top of base; one config drives every universe
• Two-way sync: push local changes to Roblox or pull remote state into config + lockfile
• --env all: operate on every env defined in rbxplace.toml in one command
• Auto overlay writes: pull writes diverging fields to [envs.<name>], clears them when remote matches base
• Typed codegen: generates a folder with an init.luau dispatcher (exported GameIds type) and one module per env, dispatching on game.GameId at runtime
• Offline regeneration + drift guard: rbx shop codegen rebuilds that folder without credentials, and --check proves the committed copy still matches its inputs (see Guarding generated files)
• Icon management: upload icons, detect changes via BLAKE3 hashing, download remote icons
• Conflict detection: detects when remote icons differ from local and asks which to keep
• TypeScript output: optional init.d.ts for roblox-ts consumers
• Alpha bleed: applied to icons before upload (enabled by default)
• Duplicate detection: when two remote resources share a name, asks which key the second should take (see Duplicate names)
• Gift products: create_gift = true on a pass or product derives a matching “GiftX” developer product automatically (see Gift products)
• JSON: --json on show and list writes one document to stdout and nothing else, with documented field names, for jq and CI. show is the declared side, list the remote one, and neither claims they agree — that is rbx check --json

Quick start

Multi-env (recommended): point at a shared rbxplace.toml

If you already use rbx place / rbx config, you have a rbxplace.toml like:

[dev]
universe_id = 9876543210

[prod]
universe_id = 9876543211

Initialize from one of the envs, then layer the other:

rbx shop init --from-remote --env dev --api-key KEY      # populates base from dev
rbx shop pull --env prod --api-key KEY                    # writes [envs.prod] overlay for diverging fields
rbx shop sync --env dev --api-key KEY                     # apply config back to dev
rbx shop sync --env all --api-key KEY                     # apply to every env in one shot

Standalone (no rbxplace.toml)

rbx shop init --from-remote --universe-id 123456789 --api-key KEY
rbx shop sync --api-key KEY

This embeds [experience].universe_id in rbxshop.toml and treats it as the implicit default env.

Multi-environment

Three concepts:

1. Base ([passes.X], [badges.X], [products.X]): the logical schema shared across every env.
2. Overlay ([envs.<name>.passes.X], etc.): per-env diffs layered on top of base.
3. Resolution: --env <name> resolves universe_id from rbxplace.toml, merges base + overlay, and uses the result as the effective config.

sync --env dev applies (base + envs.dev) to dev. sync --env prod applies (base + envs.prod) to prod. Same rbxshop.toml, different effective state per env.

Pull behavior (differential)

For each field on each resource, when you pull --env <name>:

Pull never auto-promotes overlays back into base. If you notice a field is the same across every env, edit the toml manually to lift it into base - the next pull will detect the match and remove the now-redundant overlay entries.

What a write-back preserves

pull and rename edit rbxshop.toml in place rather than regenerating it, so a write-back keeps:

• your comments, including the ones attached to a resource that was edited, and to one that was renamed;
• your key order, so the diff of a pull is the fields that actually changed;
• keys rbx does not model, whether a whole top-level table or a stray field inside a [passes.*] entry.

Only the fields rbx owns are touched. A default value is written out only where you already wrote it, or where the value diverges from the default - a pull does not sprinkle for_sale = true through a file that never mentioned it.

Both commands only insert and update lines, never reserialize the document. Round-tripping it through serde would drop comments, reorder keys, and silently delete any field it does not model — the same rule rbxplace.toml follows, see rbx env.

Unrecognised keys

A top-level key rbx does not read is kept, not deleted - but it is named on stderr at load, because from the outside an ignored key looks exactly like an honoured one:

warning: rbxshop.toml: 1 unrecognised top-level key, ignored by rbx 0.2.0:

  pases
    known keys: experience, owner, codegen, icons, gifts, include, passes, badges, products, envs

An ignored key changes nothing. Either it is misspelled, or it comes from a release newer than the one you are running.

Env-exclusive resources

A resource defined only in [envs.<name>.passes.X] is treated as exclusive to that env. In the codegen output, missing entries are stubbed to 0 in every other env’s module (a 0 asset ID is silently a no-op when passed to MarketplaceService / BadgeService, so the same code can run safely across envs).

Gift products

Roblox has no built-in way to gift a game pass or developer product to another player. The common workaround is a second developer product whose purchase, once handled server-side, grants the original item to a friend instead of the buyer. Setting create_gift = true on a [passes.X] or [products.X] entry provisions that twin product for you:

[gifts]
label = "[GIFT] "   # prefixed to the source's display name

[passes.VIP]
name = "VIP Pass"
price = 499
description = "VIP access to exclusive areas"
icon = "icons/vip.png"
create_gift = true

sync will create (and keep in sync) a developer product named "[GIFT] VIP Pass" with the same price, description, and icon, resolved under the key GiftVIP (source key prefixed with Gift - a prefix, not a suffix, so every gift twin autocompletes together when a Luau dev types Gift...). You’ll find it in the generated module at GameIds.products.GiftVIP alongside your other products.

The gift twin is entirely derived - it is never written into rbxshop.toml as its own [products.GiftVIP] entry. This is the key property: you only ever edit the source ([passes.VIP]), and the twin’s price/description/icon/name follow automatically on the next sync. There is no second entry to remember to keep in sync.

A few consequences worth knowing:

• Icons are re-uploaded, not shared. Roblox’s product/pass APIs only accept raw image bytes on create/update, not a reference to an existing asset ID, so the gift’s icon costs a separate upload each time the source icon changes.
• Renaming the source renames the twin. rbx shop rename passes VIP vip_pass also renames the twin’s lockfile entry (GiftVIP -> Giftvip_pass) so the next sync updates the existing remote product instead of creating a duplicate.
• Turning create_gift off doesn’t delete anything remotely (Roblox products can’t be deleted via the API). The twin just stops appearing in the resolved config; check/sync will warn that it “exists in lockfile but not in resolved config” - the same warning any other removed resource gets.
• create_gift can be overlaid per env just like any other field ([envs.dev.passes.VIP] create_gift = false), including on env-exclusive resources.
• Collisions are rejected. If the derived key (Gift<key>) collides with a real [products.*] entry, or two gift-enabled sources derive the same key, sync/check fail with a clear error rather than silently merging them.
• pull won’t re-import the twin. It recognizes the remote gift product by its derived key and skips writing it back into rbxshop.toml.

Adopting create_gift on an existing game

Roblox has no relationship between a pass/product and its gift twin - that link only exists in rbxshop.toml, once you declare it. So if a game already has manually-created gift products (built before ever using rbx shop, or by a different tool), plain init --from-remote or pull cannot know that “GIFT - VIP Pass” is meant to be the twin of “VIP Pass” - they import it as its own independent, literal entry.

rbx shop init --from-remote --gift-label "<label>" closes that gap by scanning the freshly-imported resources for the pattern once, at import time:

rbx shop init --from-remote --env dev --gift-label "[GIFT] " --dry-run   # preview first
rbx shop init --from-remote --env dev --gift-label "[GIFT] "             # then for real

For every pass/product, it looks for a developer product named exactly label + <source's name>. A match is only folded into the create_gift convention automatically when the price also matches - a name that happens to fit the pattern with a different price is left untouched and reported instead of merged, since that’s a much weaker signal of an actual twin:

✓ Detected gift twin: pass 'VIP' <- product '[GIFT] VIP Pass' (now `create_gift = true`, tracked as 'GiftVIP')
! Product '[GIFT] Coins100' looks like a gift twin of 'Coins100' but its price differs (149 vs 99) — left as a separate entry, review manually.

On a merge, create_gift = true is set on the source, the twin’s literal config entry is dropped, and its lockfile entry is rekeyed to the derived Gift<key> - so the very first sync afterward recognizes the existing remote product and updates it instead of creating a duplicate. --gift-label requires --from-remote; without it, nothing about existing gift products is touched.

--dry-run (also --from-remote-only) previews the whole import - counts, and every detected merge/mismatch - without downloading icons or writing rbxshop.toml/the lockfile, so you can review the plan before committing to it.

If you’d rather do it by hand for a single item instead of scanning everything, or --gift-label didn’t pick something up (e.g. the price genuinely diverges and you want to force it anyway), the manual recipe is:

1. rbx shop rename products "GIFT - VIP Pass" GiftVIP - aligns the existing product’s key with what create_gift would derive, keeping its remote ID in the lockfile.
2. Delete the now-redundant [products.GiftVIP] block from rbxshop.toml by hand (keep the lockfile entry).
3. Add create_gift = true to [passes.VIP].

The next sync will then update the existing remote product rather than create a new one.

Duplicate names

Roblox does not require game pass, badge or developer product names to be unique. init --from-remote and pull key a newly discovered resource by its display name, because that is the only human-meaningful handle the API offers — so two passes both called “VIP” want the same key.

On a terminal, you are asked which key the second should take:

! Two passes are named 'VIP': id 111 already has the key, and id 222 does not
  Give this one its own key, or leave it empty to skip it.
  Key for pass 222: VIP_2

The default is a suggestion, not a decision — type vip_premium if that is what it is. Leaving it empty skips the resource, which is the old behaviour kept as a deliberate choice rather than a default.

Off a terminal — CI, a pipe, a cron job — nothing prompts. A command that stops on a question nobody will answer is worse than one that skips loudly. Instead you get the ids and the entry that fixes it permanently:

! Duplicate pass name 'VIP' — skipping id 222 (id 111 keeps the key).
  To manage it, add an entry naming its id, then re-run:

      [passes.<your_key>]
      id = 222

A resource filed under a key that is not its name keeps its real name in the config. name is normally omitted, meaning “the key is the display name”. When you file id 222 under vip_premium, name = "VIP" is written alongside it — without that, the next sync would read the key as the name you wanted and rename the live pass.

The tool never invents the key itself. A generated VIP_2 is an identifier you would live with for as long as the resource exists, chosen by something that has no idea which “VIP” is the premium one.

Only newly discovered resources can collide. Anything already tracked is keyed by its id, so pull never displaces a resource the config is already managing.

The other direction: a lockfile that went missing

Everything above is about reading duplicates. The costlier mistake is creating one, and it has a single ordinary cause: rbxshop.lock.toml was never committed.

sync decides to create a resource from one fact — the key is absent from the lockfile. On a clean checkout with no lockfile, that is every resource in the config, and they all already exist. The duplicates that run would mint cannot be undone: Roblox has no delete for a game pass or a developer product, and the best available repair is setting the accidental twin to for_sale = false, which leaves it in the experience forever, visible to everyone who already owns it.

So before creating anything, sync lists the experience’s existing passes, badges and products and stops if a name it is about to create is already taken:

Error: 2 resources would be created under a name that already exists on Roblox:

  pass 'VIP' (key 'VIP') — already id 111
  product '100 Coins' (key 'Coins') — already id 333

The usual cause is a rbxshop.lock.toml that was never committed, which makes every
resource look new.

Adopt what already exists, then sync:
    rbx shop pull --env prod

If these really are meant to be new resources with the same names, re-run with
--allow-duplicate-names. Passes and products cannot be deleted once created.

Details worth knowing:

• It only runs when the plan contains a create. A sync that only updates resources asks Roblox nothing, so a write-only API key that worked yesterday still works.
• It stops the whole run, not just the colliding resource. A partial sync would leave the lockfile describing an env that was half applied.
• Matching is case-insensitive, on the resolved display name rather than the config key. A name differing only in case is far more likely to be the resource the lockfile lost track of than a deliberate second one, and the two mistakes do not cost the same: a false stop is a flag away, a false create is permanent.
• --allow-duplicate-names is the escape hatch for a duplicate you mean. It does not skip the listing, so the run still prints what it matched.

Commands

rbx shop codegen           # write the folder
rbx shop codegen --check   # compare instead; exits 2 on a difference

rbx shop rename passes VIP vip_pass

rbx shop list passes --env prod --json

{
  "schema_version": 1,
  "env": "prod",
  "universe_id": "9876543211",
  "resource": "passes",
  "resources": [
    {
      "id": "987654321",
      "name": "VIP Pass",
      "description": "the good one",
      "price": 199,
      "for_sale": true,
      "icon_asset_id": 123456789
    },
    { "id": "987654322", "name": "Starter Pack", "for_sale": false }
  ]
}

rbx shop list passes --env prod --json | jq -r '.resources[] | "\(.id)\t\(.name)"'
rbx shop list badges --env prod --json | jq '[.resources[] | select(.enabled | not)] | length'

rbx shop show
rbx shop show --sort price     # name (default), price, or key
rbx shop show --flat           # one global list with a type column

rbx shop show --json
rbx shop show --env prod --json

{
  "schema_version": 1,
  "config_file": "rbxshop.toml",
  "env": "prod",
  "experience": { "universe_id": "9876543210" },
  "passes": {
    "VIP": {
      "name": "VIP Pass",
      "price": 299,
      "for_sale": true,
      "regional_pricing": false,
      "create_gift": true,
      "description": "the good one",
      "icon": "icons/vip.png"
    },
    "starter": { "for_sale": false, "regional_pricing": false, "create_gift": false }
  },
  "badges": {
    "first_win": { "name": "First Win", "enabled": true }
  },
  "products": {
    "coins_100": {
      "price": 50,
      "for_sale": true,
      "regional_pricing": false,
      "store_page": true,
      "create_gift": false
    }
  }
}

rbx shop show --json | jq -r '.passes | to_entries[] | select(.value.for_sale) | .key'
rbx shop show --env prod --json | jq '[.products[].price] | add'   # full-price basket

Per-tool flags

Configuration

# Standalone fallback. Optional - omit if you always use --env.
[experience]
universe_id = 123456789

# Who owns this project. Global to the config (same for every env), and only
# consulted when a badge is created: ownership is what decides which balance
# Roblox charges. Omit it and [owner] in rbxplace.toml answers instead.
[owner]
type = "group"         # "user" or "group"
id = 123456

[codegen]
output = "src/shared/GameIds"   # FOLDER path - will contain init.luau + per-env modules
# typescript = false           # Also generate init.d.ts inside the folder
# style = "flat"               # "flat" (default) or "nested"

[icons]
bleed = true           # Apply alpha bleed before uploading (default: true)
dir = "icons"          # Directory for downloaded icons (default: "icons")

[gifts]
label = "[GIFT] "      # prefixed to the source's display name for derived gift products
key_prefix = "Gift"    # prefixed to the source's TOML key for the codegen/lockfile key (default)
# capitalize_key = false  # true: "gift" + "vipPass" -> "giftVipPass" instead of "giftvipPass"

# Split passes/badges/products across extra files if this one gets unwieldy (optional)
# [include]
# files = ["rbxshop.badges.toml"]

[passes.VIP]
name = "VIP Pass"      # explicit display name on Roblox (defaults to key)
price = 499
description = "VIP access to exclusive areas"
icon = "icons/vip.png"
create_gift = true     # also provisions a "[GIFT] VIP Pass" developer product - see below

[badges.Welcome]
description = "Welcome to the game!"
icon = "icons/welcome.png"
enabled = true

[products.Coins100]
price = 99
description = "100 coins"
icon = "icons/coins.png"

# Per-env overrides. Layered on top of base when --env <name> is passed.
[envs.prod.passes.VIP]
price = 999                    # VIP costs more in prod

[envs.dev.passes.BetaPass]     # pass exclusive to dev (0-stubbed in prod's module)
price = 0
description = "Beta tester pass"
icon = "icons/beta.png"

[codegen.extra]
"passes.legacy_vip" = 1234567
"products.starter_pack" = 9876543

# rbxshop.toml
[include]
files = ["rbxshop.badges.toml", "rbxshop.subscriptions.toml"]

Required API scopes

Code generation

When codegen.output is set, rbx shop writes a folder at that path after every sync. The folder follows Rojo’s init.luau convention and uses two patterns for compile-time safety: an identity wrapper function (validates each env’s shape at definition site) and an exhaustive match (fails to compile if a new env is added without an accompanying branch in the dispatcher).

src/shared/GameIds/
├─ init.luau          -- dispatcher with if/elseif + exhaustiveMatch
├─ GameIdsType.luau   -- type GameIds + gameIds(x) identity wrapper
├─ dev.luau           -- Types.gameIds({...})
└─ prod.luau          -- Types.gameIds({...})

The variable name (GameIds), the wrapper function (gameIds), and the type module file (GameIdsType.luau) are derived from the folder name in codegen.output. Point it at src/shared/Assets and you get Assets / assets(x) / AssetsType.luau.

Example output (nested style)

GameIdsType.luau holds the shape contract and the wrapper :

-- This file is automatically @generated by rbx shop.
-- It is not intended for manual editing.

export type GameIds = {
    passes: {
        VIP: number,
        BetaPass: number,
    },
    badges: {
        Welcome: number,
    },
    products: {
        Coins100: number,
    },
}

local function gameIds(x: GameIds): GameIds
    return x
end

return {
    gameIds = gameIds,
}

dev.luau wraps its data through the identity function so Luau strict mode validates the literal at this exact spot. A missing badge, an extra key, a wrong type, anything off: error here, not somewhere downstream.

local Types = require(script.Parent.GameIdsType)

return Types.gameIds({
    passes = {
        VIP = 67890,
        BetaPass = 11111,
    },
    badges = {
        Welcome = 98765,
    },
    products = {
        Coins100 = 22222,
    },
})

prod.luau (BetaPass stubbed to 0 since it only exists in dev) :

local Types = require(script.Parent.GameIdsType)

return Types.gameIds({
    passes = {
        VIP = 99999,
        BetaPass = 0,
    },
    badges = {
        Welcome = 88888,
    },
    products = {
        Coins100 = 77777,
    },
})

init.luau is the dispatcher. It uses a string-literal union for env names and an exhaustiveMatch(value: never): never helper so adding a new env to the union without a matching elseif branch fails at compile time, not at runtime.

-- This file is automatically @generated by rbx shop.
-- It is not intended for manual editing.

local Types = require(script.GameIdsType)
export type GameIds = Types.GameIds
export type EnvName = "dev" | "prod"

local UNIVERSE_TO_ENV: { [number]: EnvName } = {
    [9876543210] = "dev",
    [9876543211] = "prod",
}

local function exhaustiveMatch(value: never): never
    error(`rbx shop: unhandled env in dispatcher: {value :: any}`)
end

local env = UNIVERSE_TO_ENV[game.GameId]
if not env then
    error(`rbx shop: unknown universe {game.GameId}`)
end

if env == "dev" then
    return require(script.dev)
elseif env == "prod" then
    return require(script.prod)
else
    exhaustiveMatch(env)
    error("luau")
end

Consumer:

local GameIds = require(ReplicatedStorage.shared.GameIds)
MarketplaceService:PromptGamePassPurchase(player, GameIds.passes.VIP)

Autocomplete and strict typing work because the dispatcher returns GameIds for every branch (inferred from the wrapper, no :: cast needed).

Styles

Switched-off resources

A pass taken off sale, or a badge that was disabled, still appears in the generated module with its real id — and carries a comment saying so:

return Types.gameIds({
    passes = {
        VIP = 67890,
        LegacyFounder = 11111, -- not for sale
    },
    badges = {
        Welcome = 98765, -- disabled
    },
})

Keeping the id is deliberate. A pass that is off sale still has owners, so game code needs the id to answer “does this player own it”. Filtering those out would break ownership checks on exactly the passes somebody retired.

What was missing was any way to tell. VIP = 67890 reads identically whether the pass is on sale or was retired six months ago, so a prompt that silently never opens looks like a bug in the prompt. The annotation carries the answer as far as the module.

The state comes from the lockfile — for_sale for passes and products, enabled for badges — so it describes what Roblox has as of the last sync, not what the config would like. Ids under [codegen.extra] are never annotated: they belong to resources this tool does not manage, so there is nothing to know about them.

Stubbing semantics

When a resource exists in one env but not another, the missing env’s module gets a 0 stub. MarketplaceService:PromptGamePassPurchase(player, 0) is silently a no-op, so the same code runs safely across envs - but prompting purchase of a 0-stubbed ID will silently do nothing. Generated files include a comment header to flag this.

TypeScript

With typescript = true, an init.d.ts file lives alongside init.luau:

// This file is automatically @generated by rbx shop.
// It is not intended for manual editing.

declare const GameIds: {
    passes: { VIP: number; BetaPass: number }
    badges: { Welcome: number }
    products: { Coins100: number }
}

export = GameIds

Guarding generated files

The generated modules carry an It is not intended for manual editing header, but a header is a request, not a guarantee. --check is the enforcement: it re-renders the files in memory and asserts the committed copies still match their inputs.

rbx shop codegen --check                        # rbxshop.toml + rbxshop.lock.toml
rbx env gen-module --out src/Envs.luau --check  # rbxplace.toml

Both are offline — no API key, no network — which is what makes them usable from a git hook and from CD.

Exit codes: 0 clean, 2 drift, 1 the command itself failed. Drift sits on its own code so a pipeline can tell “regenerate and commit” from “something broke”.

In lefthook

pre-commit:
  parallel: true
  commands:
    codegen:
      glob: "{rbxshop.toml,rbxshop.lock.toml,rbxplace.toml,src/shared/GameIds/*}"
      run: rbx shop codegen --check
      fail_text: "Generated ids are stale or hand-edited. Run `rbx shop codegen` and re-stage."

In CI

- name: Generated files match their inputs
  run: |
    rbx shop codegen --check
    rbx env gen-module --out src/shared/Envs.luau --check

What it does and does not prove

It proves the committed files equal f(config, lockfile). It does not prove the lockfile matches Roblox. Neither does rbx shop check, which compares the config against the lockfile and is offline too. The command that asks Roblox is rbx shop pull --dry-run, which needs credentials and a network. The three answer different questions and are worth running in different places; see docs/teams.md.

It also only helps if the generated files are committed. If yours are gitignored, this belongs in CD before the build, not in a pre-commit hook.

Keep formatters off the generated path

The comparison is byte for byte (modulo CRLF, which is normalized — a Windows checkout and a Linux CI runner agree). That only holds while the generator is the single producer of those files. Point stylua or prettier at them and every check fails forever, because two tools are writing the same bytes differently and regenerating cannot settle it.

So exclude the generated folder from your formatters:

# .styluaignore
src/shared/GameIds/

The same goes for an editor set to trim trailing whitespace on save. When every difference turns out to be whitespace, the check says so explicitly instead of printing a diff that regenerating would not fix.

Collapsing the diffs on GitHub

The generated files carry an @generated header, which several review tools recognize. GitHub’s own mechanism is .gitattributes:

src/shared/GameIds/** linguist-generated=true

That folds the folder in pull request diffs and excludes it from language stats. rbx shop does not write this for you — how your repo is configured is your call.

Lockfile

rbx shop generates a rbxshop.lock.toml (sectioned by env) tracking remote state - asset IDs, icon hashes, and metadata per env:

version = 2

[envs.dev]
universe_id = 9876543210
[envs.dev.passes.VIP]
id = 67890
name = "VIP"
icon_asset_id = ...
icon_hash = "..."

[envs.prod]
universe_id = 9876543211
[envs.prod.passes.VIP]
id = 22222
# ...

Standalone mode (no --env) writes under [envs.default]. Commit the lockfile to version control.

Icon conflict resolution

When you run pull and a remote icon differs from what’s in the lockfile:

! [prod] pass 'VIP': icon differs from remote
  Local:  icons/vip.png (blake3: a1b2c3d4e5f6...)
  Remote: asset 987654321012345

Resolve with:

• --accept-remote: downloads the remote icon to your local path
• --accept-local: keeps your local icon and re-uploads it on next sync

Attributions

The alpha bleeding implementation is adapted from Asphalt (MIT), which itself adapted it from Tarmac (MIT). Thank you to both. The license notices are in THIRD-PARTY-NOTICES.md.

Live operations

Acting on a running Roblox experience: what its servers are doing, how the ones that stopped ended, what its analytics say, and who is allowed in.

These are subcommands of rbx, listed last in rbx --help and prefixed Live: in their descriptions. They share the rbxplace.toml, the --env model and the HTTP layer with everything else.

Why they are marked out

They do a different kind of work from the rest of rbx, and mixing them up is how accidents happen.

Banning a player has no desired state in a TOML file: it is a consequence of what happened in your game last night. So it is not something a tool reconciling your repo against Roblox should be doing on a push.

A second binary would make the boundary visible in the command name, and it is not on offer. Rokit resolves one artifact per repository, so of two published binaries only one could ever be installed through it. Dispatching on the name the binary was invoked by does not rescue it either: Rokit’s shim passes the stored binary’s own path as argv[0], identically for every alias. Measured 2026-08-13 by replacing the stored binary with a probe.

It would not be the boundary that holds in any case. Roblox binds an API key to its scopes and universes when you create it, so a deploy key cannot ban anybody whichever binary calls it.

Keep read and write in separate keys. That is the boundary that holds, and it is the one worth arranging your rbxapikey.toml around. The same argument splits a key per environment, and envs written as a table of named groups does that from one declaration rather than three copied blocks — see One key per environment.

Install

Nothing separate to install. rbx carries these commands:

# rokit.toml
[tools]
rbx = "rbx-forge/rbx-cli@0.2.0"

rokit install
rbx servers list --env prod

One binary, one archive per platform, which is what makes it installable at all — see why they are marked out for what the old second binary cost.

Getting a key

These commands authenticate with an Open Cloud API key, exactly like the rest of rbx. Declare it with rbx apikey rather than clicking through the Creator Hub, so the scopes are written down and reviewable.

# rbxapikey.toml
[settings]
default_envs = ["prod"]
default_secret_file = ".secrets/{name}.env"
name_prefix = "myproject_"

[keys.viewer]
description = "Read-only key for server history and analytics."
scopes = [
    "universe:read",             # servers, server logs, restart status
    "universe.analytics:read",   # analytics queries
]

rbx apikey create viewer
export RBX_API_KEY="$(rbx apikey resolve viewer)"

Scopes by subcommand:

Keep read and write in separate keys. The read key is the one that ends up in a shell history during a debugging session, and it should be the one that cannot ban anybody.

Safety model

Three rules, all structural rather than conventions to remember.

Writes are dry-run by default. Any operation that changes something describes what it would do and stops. --apply performs it, and prompts. The safe outcome is what happens when you forget a flag.

--env all is refused. For rbx shop sync it makes sense to fan out over every environment. For anything touching live players it does not: each env is a different experience, and a command that quietly acted on production because it matched a glob is a command nobody can trust.

Scopes are the real boundary. Roblox binds a key to its scopes and universes at creation. A read-only key is read-only no matter what calls it.

The Studio cookie

The .ROBLOSECURITY cookie is the one credential in this tool that the section above does not cover, and no live-ops command accepts it. servers, analytics, ban, restart, data, memorystore, publish, ads and probe take an API key and nothing else, with no cookie path to fall back to. That is on purpose: these are the operations that act on players, so they stay behind scoped keys where the scope list is the audit trail.

A session cookie is a complete account identity. It is not scoped to a universe, not scoped to an operation, and not revocable per tool, so it is strictly more powerful than any key rbx will ever ask you for. A handful of commands outside this page do need one, because Open Cloud publishes no equivalent endpoint.

The trust model lives in one place: docs/cookie.md. What the cookie is used for and never used for, the resolution order behind --cookie, RBX_COOKIE, RBXAPIKEY_COOKIE and --no-auto-cookie, the stderr notice when it is auto-detected, and why it is never written to disk.

The development configs, and why they are not in git

Two directories in this repository hold configs for real Roblox universes: testenv/ for the throwaway experience the ops subcommands are developed against, and prodread/ for read-only access to the live one.

Their rbxapikey.toml and rbxplace.toml are gitignored. What is committed is a .example next to each:

testenv/rbxapikey.example.toml    prodread/rbxapikey.example.toml
testenv/rbxplace.example.toml     prodread/rbxplace.example.toml

To work against real Open Cloud, copy each one and fill it in:

cd testenv
cp rbxapikey.example.toml rbxapikey.toml
cp rbxplace.example.toml rbxplace.toml

The values to fill in are in .local/real-ids.toml, which is gitignored too: the public IP for the key allowlists, and the live universe and place ids.

Why not just commit them with placeholders. They were, and it worked, but only by discipline. These files are useless without real values, so the first thing anyone does is paste their own IP into default_allowed_cidrs to get a call to stop returning 401 — and now a tracked file holds personal data, one git commit -a away from being published. A public IP in an allowlist is personal data and an operational disclosure: it announces which address is authorised on the Open Cloud keys. Untracked paths remove the accident instead of asking people not to have it.

Edit the .example only for changes worth sharing: a new key, a scope decision, a comment. Those comments are the valuable part — they record why each scope was chosen, and the rule that nothing in prodread/ may ever hold a write scope.

A local overlay file the tools read directly (rbxapikey.local.toml layered over the committed one) would remove the copy step rather than only making it safe. That is a change in how the tools load config, so it is not done here.

Testing and fixtures

Every client here is tested against recorded production responses, in crates/rbx-*/tests/fixtures/. Everything is byte for byte what Roblox sent, except four things replaced with synthetic values: playerIds, jobId, pagination tokens and analytics operation paths.

The last two are not obvious and were missed on the first pass. A pagination token is an opaque base64 blob, but decoding one shows Roblox packs real data inside it, including a LastGameId that is a live server’s job id. Replacing only the jobId field left a copy of it in the cursor. The tests only ever ask whether a token exists, never what is in it, so an opaque placeholder costs nothing.

Place versions are kept as recorded, and that is a decision rather than an oversight. A version number is a publish counter, so on its own it says how often some experience shipped — but the universe and place ids in these files are placeholders, so it is attached to nothing. Replacing them would cost the property the recordings exist for, since the ordering and the numeric-versus-string sorting of real version numbers is exactly the kind of detail a hand-written fixture gets wrong. Documentation is the opposite case: every figure on these pages is invented, because a page is read far more often than a fixture and nothing there needs to be real to make its point.

Recordings rather than hand-written JSON, because the specification is wrong or silent about several fields, and a hand-written fixture would encode the specification and agree with the bug. Caught this way:

• nextPageToken is "" on cloud/v2 and null on server-management. Reading "" as a token requests the same page forever.
• uptime is a .NET TimeSpan, [d.]hh:mm:ss[.fffffff], not an ISO 8601 duration. All three forms occur.
• frameRate is null on a new server and 0 on a stopped one.
• dataPoints needs camelCase renaming; without it every analytics query returns an empty series and reports “no data”.

Re-record when Roblox changes something and a test starts failing:

python scripts/capture_fixtures.py

It only ever issues GET requests, and needs the read-only keys described above.

rbx servers

Live and terminated servers for an experience, and what one of them logged before it stopped.

Roblox keeps a rolling 30-day window of terminated servers, then discards them. That window is the whole argument for pulling this on a schedule rather than looking at it after something has already gone wrong.

See ops.md for install, keys and the safety model. Everything here needs only universe:read.

Finding a version first

ListGameServers takes a place version in its path and offers no “all versions” form, so you cannot query it without knowing a version number. versions is how you find one:

rbx servers versions --env prod

place versions with servers (newest first)
  * 412
    407

The * marks the default list uses when you do not pass --version.

--json

rbx servers versions --env prod --json

{
  "schema_version": 1,
  "default_place_version": "412",
  "place_versions": ["412", "407"]
}

The default is named rather than left as “element 0”, so a script does not have to know the ordering to pick the right one:

version=$(rbx servers versions --env prod --json | jq -r '.default_place_version // empty')
[ -n "$version" ] && rbx servers list --env prod --version "$version" --json

An experience that has run nothing in thirty days gives an empty place_versions and no default_place_version, with the sentence explaining it on stderr. Exit 0 either way: nothing has run is not a failure.

Listing servers

rbx servers list --env prod

STATUS      JOB                  UPTIME   MEMORY     FPS  PLAYERS
active      9680282c                16s   569 MB      60  2/7
active      9622e310                28s   574 MB      60  2/7
active      d093f1bf                42s   572 MB      60  1/7

3 rows for place version 412, 24610 exist (--limit 3 reached)

The default limit is small on purpose. A busy experience can have tens of thousands of rows for one place version, which at the maximum page size is hundreds of requests. A command that quietly does that is not one you can run casually.

Statuses: active, shut_down, restarted, roblox_restarted, crashed, out_of_memory, moderated.

crashed and out_of_memory mean something went wrong; they are highlighted and counted separately. The others are normal lifecycle.

--json

rbx servers list --env prod --version 412 --json

One JSON document on stdout, nothing else. Warnings — the partial-page one below in particular — stay on stderr, so a monitoring script’s input parses even on the run where something was wrong.

{
  "schema_version": 1,
  "place_version": "412",
  "partial": false,
  "limit": 50,
  "limit_reached": false,
  "totals": { "returned": 3, "failed": 1, "available": 24610 },
  "servers": [
    {
      "job_id": "aba9aeae-bc55-49c8-bb0e-6363ee6ba820",
      "status": "crashed",
      "failure": true,
      "place_id": "234567890123456",
      "place_version": "412",
      "engine_version": "0.700.0.7000000",
      "create_time": "2025-08-14T02:53:11Z",
      "termination_time": "2025-08-14T13:46:53Z",
      "uptime_seconds": 39222,
      "memory_bytes": 1165064601,
      "frame_rate": 60.0,
      "occupancy": 0,
      "max_occupancy": 7,
      "full": false,
      "shut_down": true,
      "type": 1,
      "player_count": 0,
      "player_ids": []
    }
  ]
}

Optional fields are omitted rather than emitted as null, so has("frame_rate") distinguishes “never measured” from “measured zero” — the same distinction the table draws with -. Every row is an object keyed by name, never a positional array.

A version with no servers is an empty servers array and exit 0, not an error and not silence: .servers | length answers either way.

# crashed servers in the last window, newest first
rbx servers list --env prod --limit 500 --json \
  | jq -r '.servers[] | select(.failure) | "\(.termination_time) \(.job_id)"' | sort -r

# refuse to compute a rate off a page Roblox admits is incomplete
rbx servers list --env prod --limit 500 --json > servers.json
jq -e '.partial | not' servers.json > /dev/null \
  && jq '.totals.failed / .totals.returned' servers.json

Investigating a crash

Two steps. Find the server, then read what it was doing.

rbx servers list --env prod --status crashed --limit 500 --full

STATUS      JOB                                     UPTIME   MEMORY     FPS  PLAYERS
crashed     aba9aeae-bc55-49c8-bb0e-6363ee6ba820   10h 53m  1111 MB      60  0/7
crashed     05c2e867-9226-4123-a30f-aa168ede611e   15h 20m  1353 MB      60  5/7

2 rows for place version 407, 1830 exist
2 ended in a crash or out-of-memory

--full because the next command needs the whole job id, and the truncated form only exists because a uuid per row makes the table unreadable.

rbx servers logs aba9aeae-bc55-49c8-bb0e-6363ee6ba820 --version 407 --env prod

13:46:53  error    ServerScriptService.Gameplay.RoundService:88: attempt to index nil with 'Name'
              Stack Begin
              Script 'ServerScriptService.Gameplay.RoundService', Line 88
              Stack End
13:59:21  error    ServerScriptService.Gameplay.RoundService:88: attempt to index nil with 'Name'

The version has to match the row the job id came from. A job id from version 407 queried against 412 returns nothing, with no error to say why, which is why an empty result says so explicitly.

Stack traces are never truncated. After a crash they are the entire reason for running this.

--json

One document per run, not one object per line. This is the only command here where you might reasonably expect the other thing, so it is worth being explicit: rbx servers logs --json emits a single JSON document, the same as every other --json in the tool.

That is a choice about what this command is. It reads a bounded slice of a log Roblox has already finished writing — there is no --follow, the server is usually one that stopped hours ago, and nothing can be printed until pagination has stopped at --limit. Streaming would therefore produce no output any earlier, and would cost the envelope: which job id, which place version, which severity filter, and whether --limit cut the answer short are facts about the run that a line has nowhere to carry. So jq reads it like every other document here, and jq -c '.lines[]' turns it into JSON Lines if that is what you are feeding:

rbx servers logs <jobId> --version 407 --env prod --json | jq -c '.lines[]' >> logs.ndjson

The day a --follow mode exists, JSON Lines is what it should emit. That would be a new mode, not a change to this one.

rbx servers logs aba9aeae-bc55-49c8-bb0e-6363ee6ba820 --version 407 --env prod --json

{
  "schema_version": 1,
  "job_id": "aba9aeae-bc55-49c8-bb0e-6363ee6ba820",
  "place_version": "407",
  "limit": 200,
  "limit_reached": false,
  "totals": { "returned": 2, "errors": 1 },
  "lines": [
    {
      "time": "2025-08-14T13:46:53.481Z",
      "severity": "error",
      "severity_code": 3,
      "error": true,
      "message": "ServerScriptService.Gameplay.RoundService:88: attempt to index nil with 'Name'",
      "stack_trace": "Stack Begin\nScript 'ServerScriptService.Gameplay.RoundService', Line 88\nStack End",
      "job_id": "aba9aeae-bc55-49c8-bb0e-6363ee6ba820",
      "place_version": "407"
    }
  ]
}

A server with no logs is an empty lines array and exit 0, with the “check the job id and the version” advice on stderr. The document still names the job id and version it answered about, which is what makes the empty answer readable.

# every stack trace from a crash, in order
rbx servers logs <jobId> --version 407 --env prod --severity error --json \
  | jq -r '.lines[] | select(has("stack_trace")) | .stack_trace'

# refuse to conclude anything from a slice cut short by --limit
rbx servers logs <jobId> --version 407 --env prod --json > logs.json
jq -e '.limit_reached | not' logs.json > /dev/null || echo "raise --limit"

Keeping the data

Roblox discards a terminated server after thirty days and nothing brings it back, so anything you want history for has to be exported before then.

rbx servers list --env prod --version 412 --limit 500 --csv > servers.csv
rbx servers logs <jobId> --version 412 --csv --env prod > logs.csv

CSV carries every field Roblox returns, not the six the table shows: engineVersion, createTime, terminationTime, type, full, playerCount and the rest. Two deliberate choices in the conversion:

• uptimeSeconds is a number, not the 00:05:02.0020000 text Roblox sends. A spreadsheet can total seconds and cannot total a .NET TimeSpan.
• frameRate is left empty when Roblox reported nothing, rather than 0, so the difference between “never measured” and “measured zero” survives the export too.

--json carries the same fields, plus the player ids CSV drops for width and the page-level facts a flat row cannot hold (partial, limit_reached, totals). Use CSV for a spreadsheet and JSON for anything that pipes.

The same holds for logs: --json is a superset of --csv there too, and a stack trace keeps real newlines inside a JSON string instead of the quoted multi-line cell CSV has to make of it.

rbx servers logs <jobId> --version 412 --json --env prod > logs.json

Reading the output honestly

Two columns mean less than they appear to.

FPS shows -, not 0, when Roblox reported nothing. A server too young to have measured a frame rate reports null; a stopped server reports a real 0. Those are different facts and the tool refuses to conflate them.

A warning above the table is not cosmetic. Roblox can answer 200 OK while telling you, in two fields of the response body, that it failed to fetch one of its two data sources. The page is then a partial slice, so any rate computed from it is wrong. The warning is printed before the numbers rather than after.

It goes to stderr in every format, --json included, where the same fact is also in the document as partial. A script that never reads stderr still has no excuse for computing a rate off half a page.

rbx analytics

Your own metrics: players, retention, revenue per payer.

See ops.md for install, keys and the safety model.

The Creator Dashboard already charts these. The reasons to pull them through an API are the three things it cannot do: keep history past Roblox’s window, join the numbers with data of your own, and alert on a change without a human looking at a page.

Which metrics exist

Roblox publishes no list anywhere. These were confirmed by querying a live experience:

rbx analytics metrics

Visits                       Sessions started
DailyActiveUsers             Distinct players per day
MonthlyActiveUsers           Distinct players over the trailing month
D1Retention                  Share of new players returning the next day
D7Retention                  Share of new players returning within seven days
D30Retention                 Share of new players returning within thirty days
AverageRevenuePerPayingUser  ARPPU, in Robux

--metric accepts any string, so a metric Roblox adds later works without waiting for a release. An unknown name comes back as a readable error naming it.

--json writes the same list as one document on stdout:

{
  "schema_version": 1,
  "exhaustive": false,
  "metrics": [
    { "name": "Visits", "description": "Sessions started" },
    { "name": "DailyActiveUsers", "description": "Distinct players per day" }
  ]
}

exhaustive is always false, and it is in the document rather than left to this page: the list is what was confirmed by probing, not what exists. Do not validate a metric name against it.

Querying

rbx analytics query --metric DailyActiveUsers --days 7 --env prod

DailyActiveUsers (total)
  2026-07-27       1200.00
  2026-07-28       1245.00
  2026-07-29       1310.00
  2026-07-31       1180.00
  2026-08-02       1402.00

A wide range comes back queued rather than answered — Roblox hands over an operation to poll. That is handled: the command says so and waits. It gives up after a minute and tells you to narrow --days.