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.