CLI reference

Overview

gw signs you in, checks a build folder, uploads it and moves branches. It never changes your files. Human-readable output is the default; add --json for one JSON event per line, which is what scripts and CI should read.

usage: gw <command> [options]

  gw login | gw logout | gw whoami
  gw init [--app <app>] [--depot <depot>=<path> …] [--notes <file>] [--force]
  gw doctor
  gw app list | gw app info <app>
  gw depot list <app> | gw depot create <app> --os macos|windows|linux --arch arm64|x64|universal [--kind client|server]
  gw inspect <path> [--os <os>] [--arch <arch>] [--exclude <glob>] [--exe <relpath>]
  gw build push <app> --depot <depot>=<path> … --label <v> [options]
  gw build list <app> | gw build info <buildId>
  gw branch list <app> | gw branch set <app> <branch> <buildId> | gw branch rollback <app> <branch>
  gw verify <path> --build <buildId> --depot <depot>
  gw server list|create|update|rotate-key|delete …

<app> is the app id (the number from 1000 up) or its short name. <depot> is the depot name you made in the portal.

Download

Download the archive for your system, check that its SHA-256 matches, unpack it and move the gw file (gw.exe on Windows) to a folder that is on your PATH. The quick start goes through it step by step.

Global options

Signing in

gw login

Opens your browser on the Gameway consent page, which names your account and this computer, and waits for you to press Continue. The answer returns to a port on 127.0.0.1 that only this computer can reach, so the browser must run on the same computer. If nothing opens, copy the link the tool prints. The wait ends after five minutes (GW_LOGIN_TIMEOUT_S changes it).

The sign-in is stored encrypted for this computer, and the key that opens it lives in a separate folder that backups skip. Developers need two-factor authentication on the account, and the session must have used it.

gw logout, gw whoami

logout ends this computer's session. whoami prints who you are and which teams you belong to, or the key prefix when GW_API_KEY is set.

Headless use

A build machine can use an API key instead of a person: set GW_API_KEY to the key and every command uses it. A key has scopes (upload, release, servers) and is limited to the apps it names. Creating keys is a team admin's action that asks for a second factor: in the developer portal open your app, then Servers, API keys. The secret is shown once.

Setting up

gw doctor

Checks the API address, the clock (sign-in proofs need it within five minutes), your sign-in and a gw.toml in the current folder, and says which one fails.

gw init

Asks which app you mean and which folder goes into which depot, and writes the answers to gw.toml so the push command gets short.

gw app list, gw app info

Lists the apps of your teams, or shows one: id, kind, status and branches.

gw depot list, gw depot create

A depot holds the files of one platform. depot create takes the operating system, the architecture and the kind (client, which players download, or server, which they never see). The portal does the same from Depots.

gw depot create <app> --os windows --arch x64 --kind client

Checking a build

gw inspect <path>

Reads a build folder and prints what the upload would see, with no network:

• files, size and executables,
• whether Unity data is compressed (a warning when it is: see the store assets guide),
• the program that will launch, or no launch executable found when it cannot tell,
• on macOS, whether the app bundle signature is intact,
• a dry run of the chunking, so you can see how much of the folder is unique.

Pushing a build

gw build push

gw build push <app> --depot <depot>=<path> [--depot <depot>=<path> …] --label 0.1.0 [options]

Chunks the folders, asks the server which chunks it lacks, uploads only those and waits for the server to verify and sign the build. The build is private until you release it.

gw build list, gw build info

build list <app> shows recent builds with their status. build info <buildId> shows one build: depots, sizes, how much was new and the warnings.

Branches

Branches are named pointers to a build: players on a branch get what it points at. A new app has a private stable branch. Create more in the portal (Branches), including ones guarded by an access code for testers.

gw branch list <app>
gw branch set <app> <branch> <buildId> [--expect-current <id>]
gw branch rollback <app> <branch>

Setting a build live and rolling back need the Admin role, or an API key with the release scope. Releasing to a public branch also asks for your second factor in the portal. rollback returns the branch to its previous build and keeps the history.

Verifying a folder

gw verify <path> --build <buildId> --depot <depot> [--manifest <file>]

Compares a local folder with a build's manifest and lists files that differ or are missing. Exit code 5 means they differ.

Dedicated servers

Registers a dedicated game server so it can check online passes, and prints its secret key once. See Online passes on dedicated servers.

gw server create <app> --name eu-1 --endpoint 203.0.113.5:27777
gw server list <app>
gw server update <app> <serverId> [--name <name>] [--endpoint <ip:port> …] [--disable | --enable]
gw server rotate-key <app> <serverId> --yes
gw server delete <app> <serverId> --yes

Environment variables

The project file

An optional gw.toml in the folder you run from keeps the repeated parts of a push. Flags on the command line override it.

app = "1000"

[depots.windows-x64]
path = "Builds/Windows"

[depots.macos-universal]
path = "Builds/Mac/MyGame.app"

[push]
notes = "CHANGELOG.md"   # the section whose heading matches --label becomes the patch notes

With that file, a release is gw build push --label 0.2.0 --set-live beta.

Exit codes