Usage Guide
ChainLink provides a suite of commands to manage your project's dependencies and environment.
Project Lifecycle
Initializing a Project
To start a new project with ChainLink:
chainlink init
This creates a chain.toml file and sets up a basic project structure: - client/: Client-side scripts. - server/: Server-side scripts. - shared/: Shared modules. - prefab/: Models (.rbxm/.rbxmx) synced to ServerStorage. Starts with Office.rbxmx, a Sawblade Entertainment office in dark glass, charcoal and wood: a three-floor building with a lobby, reception and lounge, stairs, office floors with desks and a glass meeting room, a branded entrance canopy and roof logo, and a front plaza with lamps, trees and the spawn. - assets/: Images, audio, models and videos for chainlink assets to upload. Starts with spawn.png, the ChainLink logo.
The starter server/ExampleService.luau puts a copy of the Office in Workspace. After chainlink assets has uploaded spawn.png, it shows the logo on every Decal named Logo in the office with asset "spawn.png"; until then the spawn keeps Roblox's default decal and the other logo panels stay plain black. It also initializes a Git repository if one doesn't already exist.
Installing Dependencies
To install all tools and packages listed in your chain.toml:
chainlink install
Before downloading anything that isn't already in your global cache (~/.chainlink), ChainLink lists it and asks for confirmation. Pass -y (or --yes) to skip the prompt, e.g. in CI or scripts. Without a terminal to answer, install stops and asks you to re-run with -y:
chainlink install -y
Output is colored when writing to a terminal. Set NO_COLOR=1 to turn colors off, or FORCE_COLOR=1 to force them on.
Managing Dependencies
Adding Tools and Packages
You can add dependencies using the add command.
Adding a Tool:
chainlink add owner/repo@tag --tool
# Example: chainlink add Kampfkarren/selene@0.32.0 --tool
Adding a Package:
chainlink add scope/name@version --package
# Example: chainlink add vibeonline/razorinput@0.1.0 --package
Removing Dependencies
To remove a tool or package:
chainlink remove name
Advanced Commands
The Roblox Studio Plugin
The ChainLink plugin for Roblox Studio is installed by chainlink self-install.
Syncing Assets
Put images, audio, models and videos in an assets/ directory, then upload them to Roblox:
chainlink assets
Supported files: .png, .jpg/.jpeg, .bmp, .tga (uploaded as Images), .mp3, .ogg, .wav, .flac (Audio), .fbx, .gltf, .glb, .rbxm, .rbxmx (Models) and .mp4, .mov (Videos). Other files are skipped with a warning, and hidden files are ignored.
Only new or changed files are uploaded; IDs are kept in assets.lock.json. A changed file becomes a new asset with a new ID. Use --dry-run to see what would be uploaded. Use the asset macro to reference uploads from code.
Assets are owned by the UserId or GroupId in the [Roblox] section of chain.toml. Save an Open Cloud API key first with chainlink login-cloud; see Configuration for the permissions it needs.
Publishing a Place
Publish a place file to the place set by PlaceId under [Roblox] in chain.toml:
chainlink publish-place game.rbxl # or game.rbxlx
chainlink publish-place # build this project as .rbxl and publish it
chainlink publish-place --place 123 # override PlaceId
chainlink publish-place --draft # save a new version without publishing it
Serving
Start the ChainLink server for integrated development:
chainlink serve
Dashboard
Open a dashboard of your setup and the current project in your browser:
chainlink ui
It shows whether ChainLink, your PATH and the Studio plugin are set up, whether an Open Cloud key is saved, and, from a project folder, the tools and packages in chain.toml, whether live sync is running, and which files in assets/ still need uploading. The page refreshes itself while it is open.
Where something is missing, a button runs the command that fixes it, and its output streams into a panel at the bottom of the page:
| Button | Runs |
|---|---|
| Install / Add to PATH / Install plugin | chainlink self-install |
| Save (Open Cloud API key) | chainlink login-cloud, with the key passed on stdin |
| Start / Stop (live sync) | chainlink serve |
| Install (dependencies) | chainlink install -y |
| Upload (assets) | chainlink assets, after asking you to confirm |
| Create a project here | chainlink init, after asking you to confirm |
| Update | chainlink update |
One command runs at a time, except live sync, which keeps running alongside the others until you stop it. Press Ctrl+C in the terminal to stop the dashboard; it also stops anything it started.
The dashboard only listens on 127.0.0.1, refuses requests from other websites, and the link it opens carries a token that changes every run. Use --no-open to print the link instead of opening a browser, and --port <n> to pick the port.