Skip to content

CLI

rudder login [--address <url>] [--no-browser]
rudder logout
rudder whoami
rudder project list
rudder project create <name> [--description <text>] [--day-start HH:MM]
rudder project show
rudder 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 list
rudder currency create --file <file>
rudder currency update <slug> --file <file>
rudder currency delete <slug>
rudder image upload --file <file>
rudder environment show --env staging
rudder environment set-origins --env staging --file <file>
rudder release check
rudder 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 init
rudder update
rudder version
rudder help

Every 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.

Terminal window
rudder login
Approve the sign-in in the browser: https://app.rudder.build/device?code=ABCD-EFGH
signed 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.

CommandWhat it does
rudder whoamiPrints signed in to <address> as <email>.
rudder logoutRevokes 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.

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.

Terminal window
rudder project list
NAME ROLE ID
My Game owner 7c9e6679-7425-40de-944b-e07fc1f90ae7
Terminal window
rudder project use "My Game"
using My Game (7c9e6679-7425-40de-944b-e07fc1f90ae7) in staging, written to /work/my-game/rudder.json

rudder 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.

{
"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.

SettingFirst found of
Address--address, RUDDER_URL, rudder.json, https://api.rudder.build
TokenRUDDER_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:

Terminal window
export RUDDER_TOKEN=rdr_pat_...
rudder client generate --lang csharp --output Assets/Rudder/Rudder.g.cs --game-address https://api.rudder.build
VariableMeaning
RUDDER_TOKENA personal access token. Overrides the token of rudder login.
RUDDER_URLThe address of the Rudder API. Overrides rudder.json.

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.

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.

Terminal window
rudder catalog show inventory/items --json
rudder catalog rows inventory/items --key potion --json
rudder catalog add-row inventory/items --file potion.json --json
rudder catalog get-row inventory/items <id> --json
rudder catalog update-row inventory/items <id> --expected-version 1 --file potion.json --json
rudder 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.

CommandResult
currency listRead the draft currencies.
currency create --file gold.jsonAdd a currency with its slug.
currency update gold --file gold-settings.jsonChange its name, icon and visibility.
currency delete goldDelete it when draft content no longer references it.
module apply-sample inventory starterAdd a sample of the installed version.
image upload --file potion.webpUpload 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.

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"]}
Terminal window
rudder environment set-origins --env staging --file origins.json --json

This 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.

Terminal window
rudder release check --json
rudder release publish --expected-revision <revision> --note "Daily quest" --json
rudder release list --json
rudder release show <version> --json

release 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.

Terminal window
rudder module install stores
installed inventory 1.0.0
installed stores 1.0.0

rudder 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 fixed

With --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.

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>.

FlagMeaning
--langcsharp or ts. Required.
--outputThe file to write; its directory is created. Required.
--game-addressThe address the game reaches Rudder at, https://api.rudder.build, written into the client as its default. Not the --address of the CLI.
--namespaceThe C# namespace, Game by default.
--release-versionThe exact positive release number to generate from.

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>.

FlagMeaning
--langts, csharp or go. Required.
--outputThe file to write for ts and csharp, the root package directory for go; its directory is created. Required.
--packageThe Go package name of the root package; the base name of the output directory by default.
--namespaceThe C# namespace, Game by default.
--game-addressThe address the game server reaches Rudder at, written into the client as its default; the address of the CLI by default.
--environmentstaging or prod, the environment of rudder.json by default.
--release-versionThe exact positive release number to generate from.
--projectAnother project than the one of rudder.json.

The client follows a release, not the draft, and includes the functions marked server. See Server SDK.

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.

Terminal window
rudder logs --module shop --errors --follow
14: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 120
14:30:41 timer shop.restock project over the time limit 250ms r42
info restock offers=318

A 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.

FlagMeaning
--envstaging or prod; the environment of rudder.json by default.
--module, --functionOnly the calls of this module, or of this function.
--playerOnly the calls of this player id.
--errorsOnly the calls that did not end ok.
--sinceOnly the calls since a duration ago (1h, 30m) or a time (2026-10-27T14:00:00Z).
--followAfter the last 100, keep printing new calls as they come, until Ctrl+C.
--jsonOne JSON object per call and line: at, source, module, function, player, outcome, code, ms, release and log (level, message).
--game-addressThe 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.

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.

Downloads the newest release for your system, checks it against its line of SHA256SUMS and replaces this binary with it:

Terminal window
$ rudder update
rudder: downloading 1.9.0
updated rudder 1.8.0 → 1.9.0

rudder 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 update

The 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.

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.

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.

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.

ExitMeaningCodes
0Done.
1Failed otherwise: a network error, a refusal of Rudder with no other exit, a failed test.failed, tests_failed
2Wrong usage: an unknown command or flag, a missing argument or project.usage
3Not signed in, or the credentials or the role were refused.not_signed_in
4Not 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
5A 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
6An invalid module: manifest.json, the module code or the samples.invalid_module
7The build failed: the compiler, or finding or downloading it.build_failed