rally command-line tool

The rally command-line tool publishes web games from your own computer: games you build with your own tools, which bring their own browser client and their own server. It builds your project, uploads only the files Rally doesn’t have yet, and publishes the next version.

Studio games aren’t in this release

The commands that sync Rally Studio games with files on your computer (rally init, dev, build, link, pull and push) are still coming. Until then, build, test and publish Studio games in Rally Studio.

Install

You need Node.js 20 or later, and tar on your PATH. macOS and Linux have tar, and so do Windows 10 and later.

npm install -g @rallyplace/cli
rally --version

Publishing web games also needs approval from Rally staff. You ask for it once, on rally.place: see Ask for access.

Sign in

The CLI signs in with a developer token, a key that starts with rgt_.

1. On Rally, open Settings > Your AI (rally.place/app/settings#ai).
2. Under Access tokens, name the token (for example rally CLI on my laptop), check Publish games, and choose Create token. Copy it: Rally shows it only once.
3. Run rally login and paste the token when it asks. What you paste stays hidden.

rally login checks the token with Rally, saves it on this computer and prints who you’re signed in as. If you can’t publish web games yet, or the token doesn’t have Publish games, it says so.

Commands

Command	What it does
rally login	Saves a developer token on this computer.
rally logout	Removes the saved token from this computer.
rally whoami	Shows who you’re signed in as, and whether you can publish web games.
rally create [dir]	Creates a web game on Rally for the project and writes its id into rally.json. Run it once per game.
rally publish [dir]	Builds the project, uploads what changed and publishes the next version.
rally help	Lists the commands. rally --help and rally -h do the same.
rally --version	Prints the CLI’s version. rally -v does the same.

dir is the project folder, the one with rally.json in it. It’s the current folder unless you give one.

Every command also takes --url <address>, to use another Rally address instead of https://rally.place. You’ll rarely need it: see Environment variables for how the CLI picks the address. A command refuses options it doesn’t know, so a typo doesn’t quietly do something else.

rally login

rally login [--url <address>]

Asks for a developer token, checks it with Rally and saves it for that Rally address. In a terminal, it asks with a hidden prompt. To sign in without the prompt, for example in a script, pipe the token in: rally login reads the first line.

rally login < my-token.txt

The CLI never takes a token as an option on the command line, where it would end up in your shell’s history.

After rally login --url <address>, later commands use that address until you sign in somewhere else. If RALLY_TOKEN is set, commands use it instead of the token you saved, and rally login warns you.

rally logout

rally logout [--url <address>]

Deletes the token saved for that Rally address from this computer. The token itself keeps working until you revoke it: to stop it everywhere, choose Revoke next to it in Settings > Your AI.

rally whoami

rally whoami [--url <address>]

Prints the Rally address and the account you’re signed in as, and says if the token came from RALLY_TOKEN. If you can’t publish web games, it says why: you haven’t asked yet, your request is waiting for Rally staff, staff denied it (with their note) or revoked your access, or the token doesn’t have Publish games.

rally create

rally create [dir]

Run it once, in a new web game project. It reads rally.json (which needs "runtime": "web", a name and the client and server folders), creates the game on Rally and writes two fields back into rally.json:

• game: the new game’s id. rally publish publishes to it.
• api: the Rally address the game is on.

The game belongs to you and starts unlisted: once it’s published, anyone with its link can play it, but it isn’t listed in Games. See Visibility, listing and guests.

rally create refuses a project whose rally.json already names a game: one project folder publishes one game.

rally publish

rally publish [dir] [--game <id>] [--skip-build] [--sourcemaps]

Publishes the project as the game’s next version:

1. Runs the build command from rally.json, if there is one, in the project folder. If it fails, nothing is published.
2. Collects every file in the client folder (client.dir) and packs the server folder (server.dir) into one archive.
3. Asks Rally which of those files it doesn’t have yet, and uploads only those. Files are matched by their contents, so a publish that changes three files uploads three files.
4. Publishes the version, then prints its number and the link to play it.

The new version is live right away. See Publishing and versions.

Option	What it does
--game <id>	Publishes to this game instead of the one in rally.json. You must own it.
--skip-build	Doesn’t run the build command: publishes the client and server folders as they are.
--sourcemaps	Includes source maps (.map files) from the client folder. They’re left out by default, so your source code isn’t published with the game.

Only the game’s owner can publish it.

Environment variables

Variable	What it does
RALLY_TOKEN	A developer token. When it’s set, every command uses it instead of the token rally login saved. Use it where nobody can type, such as a CI job.
RALLY_URL	Another Rally address. You’ll rarely need it.

The CLI talks to the first Rally address it finds, in this order:

1. the --url option;
2. RALLY_URL;
3. "api" in the project’s rally.json, which rally create writes (rally logout and rally whoami look at the rally.json in the current folder; rally login never does, so a folder someone else made can’t decide where your token goes);
4. the address you last signed in to with rally login;
5. https://rally.place.

Without RALLY_TOKEN, it uses the token you saved for that address.

To publish from CI, store a token with Publish games as one of the job’s secrets, make it available to the job as RALLY_TOKEN, and run the CLI in the project folder:

npm install -g @rallyplace/cli
rally publish

Where your token is stored

rally login saves the token in a file called credentials.json, in a rally folder in your user configuration folder. It keeps one token for each Rally address you sign in to.

System	File
macOS and Linux	~/.config/rally/credentials.json
Windows	%APPDATA%\rally\credentials.json

If you’ve set XDG_CONFIG_HOME to a full path, the file is $XDG_CONFIG_HOME/rally/credentials.json instead, on any system. On macOS and Linux, only your user account can read it.

Anyone who can read that file can act as you on Rally, with the token’s permissions. Don’t copy it into a project or commit it, and run rally logout on computers you stop using. See Keep tokens secret.

Errors you may see

Most errors start with error:. When Rally refuses something, the message says what failed and gives Rally’s reason, as in error: publish failed: Game not found (HTTP 404).

Access and sign-in

Message	What to do
Publishing web games needs approval from Rally staff. Ask for it here: …	Ask for access in Settings > Web games. See Ask for access.
Your request to publish web games is waiting for Rally staff …	Wait for staff to decide. You’ll get an email either way.
Rally staff turned down your request to publish web games …	The message includes staff’s note, if they wrote one. You can ask again a day later.
Your access to publish web games was revoked …	You can’t create web games or publish new versions. Games you already published keep running unless Rally staff take them down.
you’re not signed in to …	Run rally login, or set RALLY_TOKEN.
that isn’t a Rally developer token	Developer tokens start with rgt_. Copy the whole token.
… didn’t accept that token (mistyped, or revoked?)	Create a new token and run rally login again.
Invalid or revoked developer token	The token you signed in with, or RALLY_TOKEN, was revoked. Create a new one and sign in again.
This developer token can’t do that: it needs the ‘games:publish’ scope	The token doesn’t have Publish games. Create one that does, and run rally login again.
couldn’t reach …	Check that you’re online, and that the Rally address is right.
… credentials.json is damaged	Delete the file and run rally login again.

The project

Message	What to do
no rally.json in …	Run the command in your game’s folder, or give the folder: rally publish path/to/game.
this rally publishes web games (“runtime”: “web” in rally.json) …	Add "runtime": "web" to rally.json. Studio games are published from Rally Studio.
this project isn’t on Rally yet	Run rally create once, or pass --game <id>.
this project is already on Rally as game …	rally create only runs once. Run rally publish.
rally.json: “client.dir” is required …	rally.json is missing a field, or a field has the wrong type. See the rally.json reference.
the client folder … doesn’t exist	Build the project first, or set build in rally.json so rally publish builds it for you.
the client has no index.html	The client folder has no file with the name in client.entry.
rally needs tar to pack your server	Install tar, or make sure it’s on your PATH.

Publishing

Message	What to do
Only the game’s owner can publish it	--game, or game in rally.json, names someone else’s game.
Game not found	The game id is wrong, the game was deleted, or the CLI is talking to another Rally address.
Invalid manifest: …	Something is over a limit, such as the client’s total size. See Limits.
Too many publishes — try again later	You can publish 30 times an hour.
Too many games created — try again later	You can create 20 web games an hour.

Coming later

The Studio commands will let you work on Rally Studio games in your own code editor, with your own version control, and keep them in step with Studio: start a project from a template, run it on your computer, check it, pull Studio’s draft into files and push your files back. Their files will use the project format. Until they ship, use Rally Studio, or let an AI app work in Studio with you.