Rivet CLI Tips

General

Help

All of the Rivet CLI is documented in the --help flag. Run rivet --help for a list of commands, and rivet <command> --help for help on a specific command.

Open the dashboard in your browser

You can quickly open a game's dashboard in your browser with the rivet view command. For example:

$ rivet game view
$ rivet namespace view prod
$ rivet version view 15fee343-a692-4c5a-a78a-17f5ae44a164

Scripting

`rivet run`

The rivet run command allows you to configure predefined scripts. Running these scripts will automatically populate the RIVET_TOKEN and RIVET_API_ENDPOINT environment variables.

For example, with this rivet.yaml:

scripts:
 server: npm start

Run rivet run server to start the server.

Options

By default, it will run the command with a development token in the staging namespace.

You can change the namespace with rivet run server --namespace prod.

You can issue a public token to test against servers running on Rivet with rivet run server --rivet-servers.

`rivet exec`

The rivet exec command alows you to run a command with the RIVET_TOKEN and RIVET_API_ENDPOINT environment variables. For example:

rivet exec "npm start"

This also supports the same options as rivet run (see above).

Configuration

Namespace overrides with `rivet.{ns}.yaml`

To override config properties, you can create YAML configs specific to a namespace.

For example, if you have a rivet.yaml file like:

matchmaker:
 max_players: 32
 tier: basic-1d2
 # ..etc..

You can create a file called rivet.prod.yaml to override properties for the prod namespace. For example, to override the tier property:

matchmaker:
  tier: basic-1d1

Validate a config

Use the rivet config validate command to validate a version config before deploying it. This is useful for catching errors before deploying.

YAML, JSON, and TOML support

Rivet supports multiple config file formats. You can use rivet.yaml, rivet.json, and rivet.toml for your config files.

Unlink game

To unlink a game, use the rivet unlink command. This allows you to run rivet init to link a different game.

Continuous Integration

Generating GitHub Actions deploy workflow

To generate a GitHub Actions deploy workflow that parallelizes building Docker images & CDN sites, use the rivet ci generate github command.

Deploying

Deploy with config overrides

To override properties in a version you'll deploy, you can use the --override (or -o for short) flag with the JSON value. This flag can be used multiple times to override multiple properties.

This example only works under POSIX-compliant shells (e.g. bash, zsh, etc., not PowerShell):

rivet deploy prod -o 'matchmaker.docker.env.MY_ENV_VAR="foo"' -o 'cdn.build_env.MY_BUILD_ARG="bar"'

The --override flag also works with rivet config validate.

Deploying without applying to namespace

To deploy a version without applying it to a namespace, use the --no-namespace flag. This is useful for deploying a version to a namespace at a later time.

rivet deploy --no-namespace
rivet namespace set-version <namespace> <version> (this can also be done via Rivet Hub under Manage Versions)

Matchmaker & Docker

Reuse a Docker image

You can re-use a deployed Docker image by overriding the docker.image_id property to prevent building it again.

# List deployed versions
$ rivet version list
╭─────────────┬────────────┬──────────────────────────┬──────────────────────────────────────╮
│ Name        │ Namespaces │ Created                  │ ID                                   │
├─────────────┼────────────┼──────────────────────────┼──────────────────────────────────────┤
│ 2024.02 (4) │            │ 2024-02-21T22:13:08.732Z │ 02a969ae-35d6-4efa-9a8f-b8749b8341d7 │
│ 2024.02 (2) │ Production │ 2024-02-10T16:23:11.568Z │ 15fee343-a692-4c5a-a78a-17f5ae44a164 │
│ 2024.02 (1) │            │ 2024-02-10T16:21:17.504Z │ 56efa0b1-5367-41f4-8e50-73dd24f97fa6 │
│ 0.0.1       │ Staging    │ 2024-02-10T16:19:31.656Z │ cbc3342e-b3aa-4298-a32a-66a36e5fee96 │
╰─────────────┴────────────┴──────────────────────────┴──────────────────────────────────────╯

# Read the version config
$ rivet version get 15fee343-a692-4c5a-a78a-17f5ae44a164
CloudVersionFull {
    config: CloudVersionConfig {
        matchmaker: Some(
            CloudVersionMatchmakerConfig {
                game_modes: Some(
                    {
                        "default": CloudVersionMatchmakerGameMode {
                            docker: Some(
                                CloudVersionMatchmakerGameModeRuntimeDocker {
                                    image_id: Some(
                                        2201fedb-c8c9-49ca-91d2-738de442f79b,
                                    ),
                                    # ...
                                }
                            )
                        }
                    }
                )
            }
        )
    }
}


# Deploy with the Docker image override
$ rivet deploy prod -o 'matchmaker.docker.image_id="2201fedb-c8c9-49ca-91d2-738de442f79b"'
Deploying 2024.02 (5)
# ...

The cdn.build_command command is automatically ran with RIVET_TOKEN and RIVET_API_ENDPOINT configured for the namespace you're deploying to. You can read the RIVET_TOKEN environment variable in your build script to automatically handle authentication with the Rivet API. See an example with WebPack here.

Reuse a CDN site

You can re-use a deployed CDN site by overriding the cdn.site_id property to prevent building it again.

# List deployed versions
$ rivet version list
╭─────────────┬────────────┬──────────────────────────┬──────────────────────────────────────╮
│ Name        │ Namespaces │ Created                  │ ID                                   │
├─────────────┼────────────┼──────────────────────────┼──────────────────────────────────────┤
│ 2024.02 (4) │            │ 2024-02-21T22:13:08.732Z │ 02a969ae-35d6-4efa-9a8f-b8749b8341d7 │
│ 2024.02 (2) │ Production │ 2024-02-10T16:23:11.568Z │ 15fee343-a692-4c5a-a78a-17f5ae44a164 │
│ 2024.02 (1) │            │ 2024-02-10T16:21:17.504Z │ 56efa0b1-5367-41f4-8e50-73dd24f97fa6 │
│ 0.0.1       │ Staging    │ 2024-02-10T16:19:31.656Z │ cbc3342e-b3aa-4298-a32a-66a36e5fee96 │
╰─────────────┴────────────┴──────────────────────────┴──────────────────────────────────────╯

# Read the version config
$ rivet version get 15fee343-a692-4c5a-a78a-17f5ae44a164
CloudVersionFull {
    config: CloudVersionConfig {
        cdn: Some(
            CloudVersionCdnConfig {
                # ...
                site_id: Some(
                    7fd83f14-6bfe-407a-8242-013f67b3ca16,
                ),
                # ...
            }
        )
    }
}

# Deploy with the site_id override
$ rivet deploy prod -o 'cdn.site_id="7fd83f14-6bfe-407a-8242-013f67b3ca16"'
Deploying 2024.02 (5)
# ...

rivet init --api-endpoint localhost:8080

This can also be achieved by using the RIVET_API_ENDPOINT environment variable.

export RIVET_API_ENDPOINT=localhost:8080
rivet init

This setting only needs to be specified once and will be remembered for future commands.

Disable telemetry

The --telemetry-disabled flag can be used to disable telemetry when running the Rivet CLI.

rivet --telemetry-disabled

This can also be achieved by using the RIVET_TELEMETRY_DISABLED environment variable.

export RIVET_TELEMETRY_DISABLED=true
rivet init