CLI
rudder login [--address <url>] [--no-browser]rudder logoutrudder whoamirudder project listrudder project create <name> [--description <text>] [--day-start HH:MM]rudder project showrudder project use [--environment staging|prod] <name or id>rudder module list [--installed] [--module <slug>] [--limit 50] [--cursor <cursor>]rudder module show <module>[@<version>]rudder module install <module>[@<version>]rudder module apply-sample <module> <sample>rudder catalog list <module> [--limit 50] [--cursor <cursor>]rudder catalog show <module>/<catalog>rudder catalog rows <module>/<catalog> [--key <key>] [--limit 50] [--cursor <cursor>]rudder catalog get-row <module>/<catalog> <id>rudder catalog add-row <module>/<catalog> --file <file>rudder catalog update-row <module>/<catalog> <id> --expected-version N --file <file>rudder catalog delete-row <module>/<catalog> <id>rudder catalog move-row <module>/<catalog> <id> [--after <id>]rudder currency listrudder currency create --file <file>rudder currency update <slug> --file <file>rudder currency delete <slug>rudder image upload --file <file>rudder environment show --env stagingrudder environment set-origins --env staging --file <file>rudder release checkrudder release publish --expected-revision N [--note <text>]rudder release list [--limit 50] [--cursor <cursor>]rudder release show <version>rudder client generate --lang csharp|ts --output <file> [--game-address <url>] [--namespace <name>] [--release-version N]rudder server generate --lang ts|csharp|go --output <file or directory> [--game-address <url>] [--package <name>] [--namespace <name>] [--release-version N]rudder logs [--env staging|prod] [--module <module>] [--function <function>] [--player <id>] [--errors] [--since <duration or time>] [--follow] [--game-address <url>]rudder agent initrudder updaterudder versionrudder helpEvery command also takes --json, and the commands that talk to Rudder take --address,
--project and --environment (or --env).
The CLI on Download holds every command of this page, the module commands included.
Sign in
Section titled “Sign in”rudder loginApprove the sign-in in the browser: https://app.rudder.build/device?code=ABCD-EFGHsigned in to https://api.rudder.build as [email protected]rudder login [--address <url>] opens the Dashboard with a code and waits; approving the code
there signs the CLI in. --no-browser only prints the address, for a machine without a browser,
and the code can be approved from any device. The code lasts 10 minutes. The CLI keeps a
personal access token for the address, named cli <hostname>, which Settings → Personal
Access Tokens lists and revokes. A new login at the same address replaces the token of the
previous one.
| Command | What it does |
|---|---|
rudder whoami | Prints signed in to <address> as <email>. |
rudder logout | Revokes the kept token and forgets it. Prints signed out of <address>. |
The tokens are kept in rudder/credentials.json of the configuration directory of your user,
readable by you only.
Create and choose a project
Section titled “Create and choose a project”rudder project create <name> [--description <text>] [--day-start HH:MM] creates a project
and returns its ID. Choose it separately with rudder project use <id>. rudder project show
reads the selected project’s settings, role and plan. The day start uses UTC.
rudder project listNAME ROLE IDMy Game owner 7c9e6679-7425-40de-944b-e07fc1f90ae7rudder project use "My Game"using My Game (7c9e6679-7425-40de-944b-e07fc1f90ae7) in staging, written to /work/my-game/rudder.jsonrudder project use [--environment staging|prod] <name or id> writes rudder.json, with the
environment staging unless you give another. A name two of your projects share is refused
with their ids; use the id.
rudder.json
Section titled “rudder.json”{ "address": "https://api.rudder.build", "project": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "environment": "staging"}It holds no secret: commit it with your game. project use writes it next to the
rudder.json the commands already read, else at the root of the git repository, else in the
current directory. Every command reads the nearest rudder.json up from the current directory.
How a command finds its settings
Section titled “How a command finds its settings”| Setting | First found of |
|---|---|
| Address | --address, RUDDER_URL, rudder.json, https://api.rudder.build |
| Token | RUDDER_TOKEN, the token rudder login kept for the address |
| Project | --project, rudder.json |
| Environment | --environment, rudder.json, staging |
A build server does not log in. Give it a personal access token of a member of the project,
created on Settings → Personal Access Tokens of the Dashboard, and the project in
rudder.json (committed) or in flags:
export RUDDER_TOKEN=rdr_pat_...rudder client generate --lang csharp --output Assets/Rudder/Rudder.g.cs --game-address https://api.rudder.build| Variable | Meaning |
|---|---|
RUDDER_TOKEN | A personal access token. Overrides the token of rudder login. |
RUDDER_URL | The address of the Rudder API. Overrides rudder.json. |
Discover modules
Section titled “Discover modules”rudder module list --json returns a page of the module versions your project can install.
Use --module quests to list versions of one module. --installed lists the modules of the
draft. Read a contract with rudder module show quests --json or name a version with
[email protected]. The result contains the manifest, definitions of its types, catalog schemas,
functions, dependencies and sample descriptions.
Without a version, module show reads the installed version. For a module not installed yet,
it chooses a version by the rules of module install and identifies the chosen version in
the result.
Paged lists take --limit and --cursor. The default page size is 50 and the maximum is 200.
The result has items and, when more items remain, next. Each invocation reads one page.
Pass next to --cursor with the same filters for the next page.
Draft pages also contain revision. An edit anywhere in the draft expires a continuation,
which returns cursor_expired. Read the first page again. An invalid_cursor error means
the cursor is malformed or belongs to a different collection or filter.
Configure catalogs
Section titled “Configure catalogs”catalog list <module> pages the catalogs of an installed module. catalog show <module>/<catalog> reads the declaration, row schema and types needed to interpret it.
catalog rows <module>/<catalog> reads the records with their IDs and versions. For a catalog
with a declared key, --key <key> finds that exact key.
rudder catalog show inventory/items --jsonrudder catalog rows inventory/items --key potion --jsonrudder catalog add-row inventory/items --file potion.json --jsonrudder catalog get-row inventory/items <id> --jsonrudder catalog update-row inventory/items <id> --expected-version 1 --file potion.json --jsonrudder catalog move-row inventory/items <id> --after <previous-id>rudder catalog delete-row inventory/items <id>A row file holds its content object. For example, potion.json can contain the following.
{"key":"potion","name":"Potion","kind":"stack","stack":99}Use the version read from the record for an update. A row_changed error includes the current
record in row. Read and reconcile it before saving again. A move with no --after puts the
record first.
Content changes require staging. They reach the game when you publish the draft. Files are
JSON, and --file - reads JSON from stdin.
Currencies, samples and images
Section titled “Currencies, samples and images”| Command | Result |
|---|---|
currency list | Read the draft currencies. |
currency create --file gold.json | Add a currency with its slug. |
currency update gold --file gold-settings.json | Change its name, icon and visibility. |
currency delete gold | Delete it when draft content no longer references it. |
module apply-sample inventory starter | Add a sample of the installed version. |
image upload --file potion.webp | Upload an image and return its URL for content. |
A create file can contain {"slug":"gold","name":"Gold","clientVisible":true}. An update
file contains the editable fields and the slug comes from the command argument. Create
currencies before applying samples or adding rewards that name them.
Sample application returns added and skipped. An existing key or an already-filled single
catalog is skipped. A catalog without a key receives another copy each time the sample is
applied. Read the sample description with module show, then inspect the catalogs after
applying it.
Connect staging
Section titled “Connect staging”rudder environment show --env staging --json returns the staging SDK key and allowed
origins. The SDK key is used in the game client. For a browser game or Unity WebGL, the owner
sets the exact origin of the game with environment set-origins.
{"allowedOrigins":["http://localhost:5173"]}rudder environment set-origins --env staging --file origins.json --jsonThis saves the full list. Read the current list first and retain the origins the game needs. A native game uses the SDK key without an origin setting.
Check and publish staging
Section titled “Check and publish staging”rudder release check --jsonrudder release publish --expected-revision <revision> --note "Daily quest" --jsonrudder release list --jsonrudder release show <version> --jsonrelease check validates the entire draft and returns valid, revision and problems.
An invalid check exits 5 with release_refused while retaining valid, revision and
problems in JSON. Problems identify the module, catalog and records when known. Fix them and
check again.
Pass that successful check’s revision to release publish. A draft_changed error means a
new edit happened after the check. Read the changes and validate again.
A publication returns its project, environment, release version and module versions. Generate
the game client with that --release-version, sign a test device in, check that its session
names staging, and perform the feature through the SDK. Read the outcomes and release
number with rudder logs.
After a network failure during creation, sample application or publication, read the current state before repeating the command. The operation may have completed before its reply was lost.
rudder module install
Section titled “rudder module install”rudder module install storesinstalled inventory 1.0.0installed stores 1.0.0rudder module install <module>[@<version>] puts a published version of a module, of the
marketplace or of your project, into the draft of the project, as Install in the Dashboard
does. The modules it requires and the draft lacks come with it. Without a version it installs the
newest version that fits the draft and is not a dev build. It prints each module installed (installed), changed
(changed <module> from <old> to <new>) or already there (was installed already), then every
problem of the catalogs of the draft, which a release waits for:
problem in bonus/settings: ...the draft cannot be released until the problems are fixedWith --json: {"modules": [{"module", "version", "previous", "shared"}], "problems": [{"module", "catalog", "message", "rows"}]}. A module or version that does not exist exits
with 4, module_not_found; a version that does not fit the draft exits with 5. Promotion and
rollback are made in the Dashboard only.
rudder client generate
Section titled “rudder client generate”Writes the typed game client of the selected release of the environment. Without
--release-version, it uses the newest release. Prints
wrote <file> from release <version> of <environment>.
| Flag | Meaning |
|---|---|
--lang | csharp or ts. Required. |
--output | The file to write; its directory is created. Required. |
--game-address | The address the game reaches Rudder at, https://api.rudder.build, written into the client as its default. Not the --address of the CLI. |
--namespace | The C# namespace, Game by default. |
--release-version | The exact positive release number to generate from. |
rudder server generate
Section titled “rudder server generate”Writes the typed server client of the selected release of the environment. Without
--release-version, it uses the newest release. Your game server
calls the modules of your project for a player it names, and updates the profile and the ban of
the player. Prints wrote <file> from release <version> of <environment>.
| Flag | Meaning |
|---|---|
--lang | ts, csharp or go. Required. |
--output | The file to write for ts and csharp, the root package directory for go; its directory is created. Required. |
--package | The Go package name of the root package; the base name of the output directory by default. |
--namespace | The C# namespace, Game by default. |
--game-address | The address the game server reaches Rudder at, written into the client as its default; the address of the CLI by default. |
--environment | staging or prod, the environment of rudder.json by default. |
--release-version | The exact positive release number to generate from. |
--project | Another project than the one of rudder.json. |
The client follows a release, not the draft, and includes the functions marked server. See
Server SDK.
rudder logs
Section titled “rudder logs”Prints the recent calls of the environment, the last 100, oldest first, the same calls as
Activity in the Dashboard. The environment is the one of
rudder.json unless --env names another.
rudder logs --module shop --errors --follow14:31:07 client shop.buy 7c2e…2d03 error:insufficient 9ms r42 info buy offer=gem_pack_s price=120 gold warn balance 80 gold is below the price 12014:30:41 timer shop.restock project over the time limit 250ms r42 info restock offers=318A line is the time, who called (client, server, operator, event, timer), the module and
function, the player (project for a timer of the shared data), how it ended (ok,
error:<code>, trap, over the time limit, try again), the milliseconds and the release.
The lines the module logged follow it, indented with their level.
| Flag | Meaning |
|---|---|
--env | staging or prod; the environment of rudder.json by default. |
--module, --function | Only the calls of this module, or of this function. |
--player | Only the calls of this player id. |
--errors | Only the calls that did not end ok. |
--since | Only the calls since a duration ago (1h, 30m) or a time (2026-10-27T14:00:00Z). |
--follow | After the last 100, keep printing new calls as they come, until Ctrl+C. |
--json | One JSON object per call and line: at, source, module, function, player, outcome, code, ms, release and log (level, message). |
--game-address | The address the game reaches Rudder at, the address of the CLI by default. |
Every role of the project reads the calls. It shows the last 10 000 calls of the environment.
rudder agent init
Section titled “rudder agent init”Writes the Rudder skill to .agents/skills/rudder/SKILL.md and updates the Rudder block
in AGENTS.md. The instructions require the SDK and CLI instead of direct HTTP calls; see
Point an agent at Rudder.
rudder update
Section titled “rudder update”Downloads the newest release for your system, checks it against its line of SHA256SUMS and
replaces this binary with it:
$ rudder updaterudder: downloading 1.9.0updated rudder 1.8.0 → 1.9.0rudder 1.9.0 is the newest version means there is nothing to do, and a platform no release is
built for is refused. On Windows the old file stays as rudder.exe.old until the process ends.
A command that ends well says so by itself when a newer release exists, one line on stderr:
rudder: 1.9.0 is available, you have 1.8.0; run rudder updateThe CLI asks for that at most once in fifteen minutes and keeps the answer in its cache
directory. RUDDER_NO_UPDATE_CHECK=1 turns the line off, for CI and scripts. A build of the
source (rudder dev) never checks.
Release notes
Section titled “Release notes”Starting with CLI 1.9.0, the first successful text command of a new version prints that version’s release notes on stderr. The notice is shown once for your local user configuration. The notes are included in the executable and can be displayed offline.
JSON commands, commands run with CI set, and failed commands leave the notice pending for a
later successful text command. When upgrading from 1.8.0 to 1.9.0, run another text command,
such as rudder version, to see the notes after the update.
Read the complete release history whenever you need it. CLI changelog
After updating, run rudder agent init in your game repository to refresh its instructions.
rudder version
Section titled “rudder version”Prints the version of the CLI, rudder <version> (dev for a build without a version).
rudder --version does the same. rudder help, --help and
-h print the usage.
Output and exit codes
Section titled “Output and exit codes”Text goes to stdout for a person, and a failure to stderr as rudder: <message>, followed by
the usage for wrong usage.
With --json command results are JSON on stdout, and a failure has the following shape.
{"error": {"code": "module_not_found", "message": "..."}}path, when known, is the place the error is about. A refusal keeps the code Rudder answered.
Structured problems and the current conflict row are retained when supplied. Agents can
use those fields directly to correct content or reconcile a conflicting save.
| Exit | Meaning | Codes |
|---|---|---|
| 0 | Done. | |
| 1 | Failed otherwise: a network error, a refusal of Rudder with no other exit, a failed test. | failed, tests_failed |
| 2 | Wrong usage: an unknown command or flag, a missing argument or project. | usage |
| 3 | Not signed in, or the credentials or the role were refused. | not_signed_in |
| 4 | Not found: a project name no project has, an environment with no release, a module with no such version or no version in a range. | project_not_found, release_not_found, module_not_found |
| 5 | A conflict, a contract incompatible with rudder.lock.json or with an earlier version of the line, a directory that is not empty. | incompatible_contract, directory_not_empty |
| 6 | An invalid module: manifest.json, the module code or the samples. | invalid_module |
| 7 | The build failed: the compiler, or finding or downloading it. | build_failed |