Package Format

Rebind code ships in two tiers, and one file decides which you’re in:

Script tier: a bare .lua/.luau file, no rebind.toml anywhere above it. The modeline comment at the top of the file owns all configuration.
Package tier: a directory (or any ancestor of the script) containing rebind.toml. The toml is package truth: it owns identity and can set every runtime option, overriding the entry’s modeline.

Promotion is additive: start with a single script, and when it outgrows one file, rebind init a package and move it in. Nothing about the code changes.

Layout

hello/
  rebind.toml          # the package manifest
  main.luau            # the entry (or set [package].entry)
  lib/util.luau        # optional modules: require("lib/util")
  scripts/wiggle.luau  # optional standalone tools: rebind run scripts/wiggle.luau
  assets/icon.png      # listing media; uploaded at publish, never packed
  README.md            # ships in the package, and is the listing's overview

The entry defaults to main.luau, then main.lua. requires resolve inside the package root: <mod>.luau, <mod>.lua, <mod>/init.luau, <mod>/init.lua.

rebind.toml

[package]
name = "hello"          # the identifier: public identity is @yourhandle/hello
version = "0.0.1"
min_sdk = "3.4.1"       # oldest Rebind version the package runs on
# entry = "main.luau"   # optional, this is the default

[runtime]               # optional: every runtime modeline key works here
# tick_rate = 1000
# window = ["chrome"]   # activate only when a matching window is focused
# process = ["chrome.exe"]
# process_regex = ["^(chrome|firefox)\\.exe$"]
# exclude_window = ["Private"]
# exclude_process_regex = ["^(obs64|discord)\\.exe$"]
# permissions = ["net"] # gate Net.* / System.Exec ("exec") use
# memory_limit_mb = 64  # raise the Luau heap (MB) for image-heavy scripts
# instance = "replace"  # replace | single | multiple
# hardware_only = false
# key_block = true
# mouse_block = false
# platforms = ["windows", "macos"]  # refuse to load elsewhere; omit for all

[runtime] values are checked by the same rules as modeline values, so an unknown instance or a tick_rate above 8000 is an error, not a silent default. name, version, and min_sdk belong under [package] and are refused under [runtime]. The toml key is permissions (a list). In a modeline, permission= and permissions= behave identically: either takes one value or a comma-separated list, and every line adds to the set. An empty set means “declared, needs nothing”: permissions = [] in the toml, or permissions=none (or a bare permissions=) in a modeline. Omitting the key entirely is the opposite, and grants every permission. See Permissions. A package you intend to publish must declare the key. The registry refuses a version that leaves it undeclared, since “undeclared” reads as every permission, and rebind check fails it offline once [marketplace] is present. Declaring the empty set is always available for a script that needs nothing. Publishing adds a third section, [marketplace]. It is only read by rebind check and rebind publish, never by the runtime: see the marketplace listing.

Precedence: toml over modeline

Inside a package, the entry’s modeline still works (an entry can run standalone during development), but any key also set in rebind.toml wins, and the collision is surfaced as a warning on the script’s log channel. A bare script outside any package declares min_sdk in its modeline.

-- script tier: the modeline is the manifest
-- rebind: name=wiggle version=0.1.0 min_sdk=3.0.0
-- rebind: permission=net

Scripts inside a package

Any script under a package root (for example scripts/wiggle.luau) runs in that package’s context, with deliberate limits:

Inherited	Not inherited
`[package]` `min_sdk` and `version` (as defaults; its own modeline still wins)	`name`: the script keeps its file name (own log channel)
`require` resolution from the package root	`[runtime]` keys: a tool script declares its own permissions

So a one-shot helper needs zero boilerplate:

function OnStart()
  HID.MoveTo(500, 500)
  exit()
end

exit() (alias for Script.Exit()) ends the script cleanly when it’s done.

Importing from GitHub

A package in a public GitHub repository installs from the app. In the Scripts tab, open More file actions above the file list and choose Import from a link, then paste the repository link. The rebind.toml must sit at the top of the repository. A /tree/<ref> link takes a branch or a tag, and the ref may contain slashes. Packages inside a folder are not supported.

The import dialog over the script editor, with a link field and Cancel and Check buttons — Import from a link: paste a public repository link, then Check before anything installs.

Check shows what GitHub says about the repository: description, stars, last push, the size of the whole repository with its history, and whether a rebind.toml exists. Nothing is downloaded yet. Download and check fetches it and shows the package name, version, file count, commit, and requested permissions before anything is written. Import installs that exact commit under repos/<repo> in your scripts folder. Rebind has not reviewed this code, so import only from authors you trust. To pull a newer commit later, right-click the folder, choose Fetch update, and confirm with Replace. Local edits in that folder are replaced too. A folder imported by an earlier version still fetches updates.

A single script from a gist or a paste

The same dialog takes a gist.github.com or pastebin.com link to one standalone script. The gist must hold exactly one .luau or .lua file. The script must declare -- rebind: name= and compile, otherwise it is not importable. Check fetches the whole file and shows its name, version, size, and requested permissions. Import fetches it again, refuses it if it changed since the check, and writes it under imports/ in your scripts folder. There is no Fetch update for these: import the link again to replace the file.

Add an import button to your README

GitHub removes rebind:// links from a README, so the button points at a rebind.gg page that hands the link to the desktop app. Replace OWNER/REPO:

[![Import to Rebind](https://www.rebind.gg/import-badge.svg)](https://www.rebind.gg/import?url=https://github.com/OWNER/REPO)

The url can also be a gist or a paste link. The button only opens the import dialog with the link filled in. Nothing is fetched or installed until the user presses Check, then Import.

Link reference

Link	Opens
`rebind://import?url=<link>`	The import dialog with a GitHub, gist, or paste link filled in. `source=github`, `gist`, or `pastebin` is optional and must match the link.
`rebind://import?source=export&code=<code>`	The share code dialog with the code filled in.
`rebind://marketplace/<id>`	A marketplace listing.
`rebind://marketplace/<id>/install`	The same listing, with its install button focused. Nothing installs until you press it.
`rebind://settings/diagnostics`	Settings, with the Send logs for review dialog open.
`rebind://<view>`	`dashboard`, `scripts`, `marketplace`, `devices`, `peripherals`, or `settings`.

Every link brings Rebind to the front. None of them installs, sends, or buys anything on its own.

The .rbp artifact

rebind pack produces the registry artifact: a gzipped tarball of the package’s source, rebind.toml, and README.md, with hidden files and folders (names starting with a dot), build output, and any .rbp excluded. Listing media under assets/ is uploaded separately at publish and is not packed. A DRM listing ships no archive at all: see DRM packages. For validation and repacking after extraction, see Installed and extracted packages.

The marketplace listing

[marketplace] is publish-time configuration. A package without it is a valid dev package; rebind publish refuses without it. rebind init scaffolds the block commented out. Unknown keys inside [marketplace] or [marketplace.price] are errors.

[marketplace]
summary = "One line, shown in the grid."
title = "Hello"                # optional storefront name, defaults to the slug
category = "utility"          # see Categories below
tags = ["remap", "productivity"]
icon = "assets/icon.png"      # optional, see Listing media
media = ["assets/shot-1.png", "assets/demo.mp4"]
private = false               # true: reachable by direct link only
drm = false                   # requires a price

# absent = free · one_time AND an interval key together = hybrid
[marketplace.price]
one_time = 15.00              # usd, two decimals max
monthly = 5.00                # or weekly / daily, one interval key at most

Field	Required	Notes
`summary`	to publish	the one-line shelf label (grid card, search)
`title`	no	the storefront name; defaults to the package slug
`category`	yes	one slug from Categories
`[marketplace.price]`	for paid listings	absent = free. The key is the model: `one_time` sells a lifetime purchase; `monthly`/`weekly`/`daily` sells a subscription; both together sell both
`drm`	no	defaults `false`; needs a price and ships the package as one sealed file, see DRM packages
`private`	no	defaults `false`; absent from browse, search, and profiles, reachable by direct link. Flipping it applies immediately, without review
`tags`	no	free-form strings
`icon`	no	optional 128x128 png shown beside the name on cards and the listing page, separate from gallery media
`media`	to publish	ordered cover and gallery media; the first png is the cover

Prices are USD with at most two decimals. Subscription prices are locked in at subscribe time: an approved price change applies to new subscribers only. Existing subscribers keep their price until they cancel. rebind check validates the shape and caps of whatever the block declares, offline, against the limits below. Presence is rebind publish’s job: it refuses a listing without a summary or without at least one PNG image in media. rebind preview renders the listing as a local HTML page before anything is uploaded. The server re-validates everything at publish.

Slug	Files here
`gaming`	game-specific input: rapid fire, movement helpers, opposing-key resolution, chat macros, per-game profiles
`mouse`	movement transforms: acceleration curves, inversion, sensitivity, output rate, keyboard-driven mouse
`remapping`	key remaps, layers, chords, modifier hold, layouts
`macro`	recording, replay, sequences, auto-clickers, timed input
`text`	expansion, hotstrings, unicode and emoji, clipboard transforms, autocorrect
`apps`	launching and switching apps, window tiling and moving, always-on-top, virtual desktops
`audio`	volume, mute, device switching, media keys, voice chat mute, players
`streaming`	OBS, Streamer.bot, Twitch, counters and timers written for overlays
`productivity`	timers, reminders, meeting controls, per-app shortcut sets
`accessibility`	dwell click, tremor smoothing, sticky keys, one-handed layouts, key repeat
`utility`	shell and webhook runners, smart home, system tweaks, monitoring, remote control, anything that fits nowhere above

Listing media

Both icon and media are file paths inside the package, under assets/. You never supply a URL; publish uploads the files and the marketplace stores its own keys. Media is not packed into the .rbp. The first PNG image in media becomes the cover used by the grid and product page. Publish removes it from the remaining gallery so it does not appear twice. At least one PNG image is required, even when icon is set. The optional icon is a separate listing asset and never becomes a gallery slide. Remaining media entries keep their declaration order. A cover can illustrate the package’s behavior or show a screenshot. Label generated illustrations clearly; they are not evidence of runtime behavior. Screenshots and demo video must come from the running script or its real UI. Keep editable artwork source outside the packed package directory and declare the exported listing images under assets/.

README.md

A README.md at the package root is the listing’s long description. It ships inside the .rbp as well, so an installed copy reads offline.

Rendered as markdown in the product page overview card.
Packages only. A bare script never picks one up.
Without one, the product page falls back to summary.

DRM packages

drm = true needs a price and changes how the package ships. rebind publish resolves the require graph and bundles every module into one file, so the buyer receives a single sealed script instead of a directory of source. No .rbp is uploaded for a DRM listing. The sealed file opens with the merged [package] and [runtime] declarations written as modelines, so the buyer’s relay applies the same permissions and targeting the manifest declared. Two things cannot survive the flattening, and rebind check refuses them once drm is set:

require() with a non-literal argument. A sealed file resolves its modules before it runs, so every module name must be a string literal.
Data files a module reads at runtime (File.Read, Config.ReadTOML, Audio.Play). They would not reach the buyer. Inline the data into a .luau module, or publish without DRM.

Paid is independent of DRM. Entitlement gates on price, so a paid package with drm = false is still gated at download and arrives as plaintext. A sealed script runs only with an activated Rebind Link.

Limits

The one home for every cap. rebind check enforces the ones it can see offline; the server enforces all of them at publish.

Item	Limit
`[package].name` (the slug)	1 to 60 lowercase letters, digits, and hyphens; starts and ends with a letter or digit
`title`	60 characters
`summary`	140 characters
`tags`	8, each 24 characters
`README.md`	64 KiB, no images. Over the cap is an error, not a truncation
`media`	8 entries, at most 2 videos
Media paths	under `assets/`, relative, no `..` segments; `.png` and `.mp4` only
Icon	exactly 128x128 png, 512 KiB
Cover or gallery image	exactly 1280x800 or 640x400 png, 2 MiB
Video	mp4, 16 MiB
`.rbp`	200 entries, 10 MiB unpacked, 10 MiB compressed
Sealed DRM file	512 KiB of bundled source

Getting Started

Concepts

Cookbook

Marketplace

Reference

Remote Control

Help

Package Format

Layout

rebind.toml

Precedence: toml over modeline

Scripts inside a package

Importing from GitHub

A single script from a gist or a paste

Add an import button to your README

Link reference

The .rbp artifact

The marketplace listing

Categories

Listing media

README.md

DRM packages

Limits

​Layout

​rebind.toml

​Precedence: toml over modeline

​Scripts inside a package

​Importing from GitHub

​A single script from a gist or a paste

​Add an import button to your README

​Link reference

​The .rbp artifact

​The marketplace listing

​Categories

​Listing media

​README.md

​DRM packages

​Limits

Layout

rebind.toml

Precedence: toml over modeline

Scripts inside a package

Importing from GitHub

A single script from a gist or a paste

Add an import button to your README

Link reference

The .rbp artifact

The marketplace listing

Categories

Listing media

README.md

DRM packages

Limits