CLI Command Reference

`metaplay [flags]`

Metaplay CLI for development, deployment, and operations

Examples

shell

# Initialize a new Metaplay project in an existing Unity project
MyGame$ metaplay init project

# Run your game server locally for development
MyGame$ metaplay dev server

# Manually deploy your game server to a cloud environment
MyGame$ metaplay build image
MyGame$ metaplay deploy server

# View server logs in a cloud environment
MyGame$ metaplay debug logs

Flags

--color <string>: Should the output be colored (yes/no/auto)? [env: METAPLAYCLI_COLOR] (default: auto)
--project, -p <string>: Path to the to project directory (where metaplay-project.yaml is located)
--skip-version-check: Skip the check for a new CLI version being available
--verbose, -v: Enable verbose logging, useful for troubleshooting [env: METAPLAYCLI_VERBOSE]

`metaplay auth`

Commands related to authenticating with Metaplay Cloud. Supports sign in via a browser for human users and using a secret for machine users.

`metaplay auth login [AUTH_PROVIDER]`

The default auth provider is 'metaplay'. If you have multiple auth providers configured in your 'metaplay-project.yaml', you can specify the name of the provider you want to use with the argument AUTH_PROVIDER.

Expected arguments:

AUTH_PROVIDER (optional) -- Name of the auth provider to use. Defaults to 'metaplay'.

`metaplay auth logout [AUTH_PROVIDER]`

Delete the locally persisted credentials to sign out from the target authentication provider.

Expected arguments:

AUTH_PROVIDER (optional) -- Name of the auth provider to use. Defaults to 'metaplay'.

`metaplay auth machine-login [AUTH_PROVIDER] [flags]`

Expected arguments:

AUTH_PROVIDER (optional) -- Name of the auth provider to use. Defaults to 'metaplay'.

Flags

--dev-credentials <string>: Machine login credentials (prefer passing credentials via the environment variable METAPLAY_CREDENTIALS for better security)

`metaplay auth whoami [AUTH_PROVIDER] [flags]`

Show information about the signed in user.

By default, displays the information in a human-readable text format. Use --format=json to get the complete user information in JSON format.

Expected arguments:

AUTH_PROVIDER (optional) -- Name of the auth provider to use. Defaults to 'metaplay'.

Examples

shell

# Show user information in text format
metaplay auth whoami

# Show complete user information in JSON format
metaplay auth whoami --format=json

# Show user information for a specific auth provider
metaplay auth whoami myAuthProvider

Flags

--format <string>: Output format. Valid values are 'text' or 'json' (default: text)

`metaplay build`

Build game server components locally

Aliases

b

`metaplay build botclient [flags]`

Build the BotClient .NET project using the .NET SDK.

This command:

Verifies the required .NET SDK version is installed
Builds the BotClient project using 'dotnet build'

The BotClient is used for automated testing and load testing of the game server. It simulates real player behavior by running multiple bot instances that connect to the server and perform various actions.

Related commands:

'metaplay deploy botclient ...' to deploy bot clients to a cloud environment
'metaplay dev botclient ...' to run the bot client locally
'metaplay remove botclient ...' to remove bot clients from an environment
'metaplay debug logs ...' to view bot client logs in an environment

Examples

shell

# Build the BotClient project
metaplay build botclient

# Build and then run the bot client locally
metaplay build botclient && metaplay dev botclient

`metaplay build dashboard [flags]`

Build the Vue.js LiveOps Dashboard locally.

This command first checks that Node.js and pnpm are installed and satisfy version requirements. Then it installs dashboard dependencies (unless --skip-install is used) and builds the dashboard.

The build process includes TypeScript compilation and Vite bundling. By default, the output is placed in Backend/Dashboard/dist/. The locally running game server (with 'metaplay run server') will serve this output on http://localhost:5550.

If you want to include the a pre-built version of the dashboard in your version control, so that it can be served locally without the Node/pnpm tooling installed, use the --output-prebuilt flag to place the build output in Backend/PrebuiltDashboard/. If you do this, you should commit the Backend/PrebuiltDashboard/ directory to version control.

Related commands:

'metaplay build server' builds the game server .NET project.
'metaplay build image' builds a Docker image with the server and dashboard.
'metaplay dev dashboard' runs the dashboard in development mode.

Aliases

dash

Examples

shell

# Build the dashboard.
metaplay build dashboard

# Output pre-built dashboard (see help text for explanations)
metaplay build dashboard --output-prebuilt

# Skip dependency installation (faster builds if deps already installed)
metaplay build dashboard --skip-install

# Pass extra arguments to vite build
metaplay build dashboard -- --mode production

Flags

--output-prebuilt: Output pre-built version of the dashboard (see help text)
--skip-install: Skip the pnpm install step
--skip-pnpm: Skip the pnpm install step (deprecated, use --skip-install)

`metaplay build image [IMAGE] [flags] [-- EXTRA_ARGS]`

Build a Docker image of your project to be deployed in the cloud. The built image contains both the game server (C# project), the LiveOps Dashboard, and the BotClient.

Expected arguments:

IMAGE (optional) -- Docker image name (optional) and tag, eg, 'mygame:364cff09' or '364cff09'.
EXTRA_ARGS (optional) -- Passed as-is to docker build.

Related commands:

'metaplay deploy server ...' to push and deploy the game server image into a cloud environment.
'metaplay image push ...' to push the built image into a target environment's registry.

Aliases

i

Examples

shell

# Build Docker image, produces image named '\<projectID\>:\<timestamp\>'. Only recommended when
# building images manually. In CI, you should always specify the tag explicitly.
metaplay build image

# Specify only the tag, produces image named '\<projectID\>:364cff09'.
metaplay build image 364cff09

# Build a project from another directory.
metaplay -p ../MyProject build image

# Build docker image with commit ID and build number specified.
metaplay build image mygame:364cff09 --commit-id=1a27c25753 --build-number=123

# Build using docker's BuildKit engine (in case buildx isn't available).
metaplay build image mygame:364cff09 --engine=buildkit

# Build an image to be run on an arm64 machine.
metaplay build image mygame:364cff09 --architecture=arm64

# Build a multi-arch image for both amd64 and arm64 (only supported with 'buildx').
metaplay build image mygame:364cff09 --architecture=amd64,arm64

# Pass extra arguments to the docker build.
metaplay build image mygame:364cff09 -- --build-arg FOO=BAR

Flags

--architecture <stringSlice>: Architectures of build targets (comma-separated), eg, 'amd64' or 'amd64,arm64' (default: [amd64])
--build-number <string>: Number identifying this build, eg, '715'
--commit-id <string>: Git commit SHA hash or similar, eg, '7d1ebc858b'
--engine <string>: Docker build engine to use ('buildx' or 'buildkit'), auto-detected if not specified

`metaplay build server [flags]`

Build the game server .NET project locally.

Also check that the .NET SDK is installed and is a recent enough version.

This command is roughly equivalent to: Backend/Server$ dotnet build

Related commands:

'metaplay build dashboard' builds the LiveOps Dashboard.
'metaplay build botclient' builds the BotClient project.
'metaplay build image' builds a Docker image with the server and dashboard.
'metaplay dev server' runs the game server locally.

Examples

shell

# Build the game server
metaplay build game-server

`metaplay completion`

Generate the autocompletion script for metaplay for the specified shell. See each sub-command's help for details on how to use the generated script.

`metaplay completion bash`

Generate the autocompletion script for the bash shell.

This script depends on the 'bash-completion' package. If it is not installed already, you can install it via your OS's package manager.

To load completions in your current shell session:

source <(metaplay completion bash)

To load completions for every new session, execute once:

Linux:

metaplay completion bash > /etc/bash_completion.d/metaplay

macOS:

metaplay completion bash > $(brew --prefix)/etc/bash_completion.d/metaplay

You will need to start a new shell for this setup to take effect.

Flags

--no-descriptions: disable completion descriptions

`metaplay completion fish [flags]`

Generate the autocompletion script for the fish shell.

To load completions in your current shell session:

metaplay completion fish | source

To load completions for every new session, execute once:

metaplay completion fish > ~/.config/fish/completions/metaplay.fish

You will need to start a new shell for this setup to take effect.

Flags

--no-descriptions: disable completion descriptions

`metaplay completion powershell [flags]`

Generate the autocompletion script for powershell.

To load completions in your current shell session:

metaplay completion powershell | Out-String | Invoke-Expression

To load completions for every new session, add the output of the above command to your powershell profile.

Flags

--no-descriptions: disable completion descriptions

`metaplay completion zsh [flags]`

Generate the autocompletion script for the zsh shell.

If shell completion is not already enabled in your environment you will need to enable it. You can execute the following once:

echo "autoload -U compinit; compinit" >> ~/.zshrc

To load completions in your current shell session:

source <(metaplay completion zsh)

To load completions for every new session, execute once:

Linux:

metaplay completion zsh > "${fpath[1]}/_metaplay"

macOS:

metaplay completion zsh > $(brew --prefix)/share/zsh/site-functions/_metaplay

You will need to start a new shell for this setup to take effect.

Flags

--no-descriptions: disable completion descriptions

`metaplay database`

Commands for managing and interacting with game server databases

Aliases

db

`metaplay database reset [ENVIRONMENT] [flags]`

Reset the database by dropping all tables in all shards. This operation is designed to handle database schema version mismatches and ensure a clean database state.

The reset process uses the following sequence:

Mark reset in progress by setting MasterVersion to -4004
Drop all tables except MetaInfo (preserves reset state)
Drop MetaInfo tables in reverse shard order

This ensures the reset can be resumed if interrupted and maintains consistency.

WARNING: This operation is DESTRUCTIVE and will delete ALL data in the database. Use with extreme caution and only on development/staging environments.

Expected arguments:

ENVIRONMENT (optional) -- Target environment name or id, eg, 'lovely-wombats-build-nimbly'.

Aliases

nuke

Examples

shell

# Reset database in nimbly environment (requires confirmation)
metaplay database reset nimbly

# Auto-accept reset without confirmation prompt
metaplay database reset nimbly --yes

# Force reset even if game servers are deployed
metaplay database reset nimbly --force --yes

Flags

--force: Proceed with reset even if game server deployments are active
--yes: Skip confirmation prompt and proceed with reset

`metaplay debug`

Commands for debugging and diagnostics of running game servers

Aliases

d

`metaplay debug admin-request ENVIRONMENT METHOD PATH [flags]`

PREVIEW: This is a preview feature and interface may change in the future.

Make HTTP requests to the game server admin API.

This command allows you to interact with the game server's admin API endpoint using various HTTP methods. You can pass a request body using either the --body flag for providing raw content directly or the --file flag to read content from a file.

Expected arguments:

ENVIRONMENT -- Target environment name or id, eg, 'tough-falcons'.
METHOD -- HTTP method to use: GET, POST, DELETE, PUT.
PATH -- Path for the admin API request, eg '/api/v1/status'.

Related commands:

'metaplay debug server-status ...' checks the status of a game server deployment.

Aliases

admin

Examples

shell

# Get the server hello message.
metaplay debug admin-request tough-falcons GET /api/hello

# Pipe JSON output to jq for colored rendering.
metaplay debug admin-request tough-falcons GET /api/hello | jq

# Send a POST request with request body from command line.
metaplay debug admin-request tough-falcons POST /api/some-endpoint --body '{"name":"test-resource"}'

# Send a PUT request with request payload from file.
metaplay debug admin-request tough-falcons PUT /api/some-endpoint --file update.json

# Send a DELETE request.
metaplay debug admin-request tough-falcons DELETE /api/some-endpoint

Flags

--body <string>: Raw content to use as the request body
--file <string>: Path to a file containing content to use as the request body

`metaplay debug collect-cpu-profile [ENVIRONMENT] [POD] [flags]`

PREVIEW: This is a preview feature and interface may change in the future.

Collect a CPU profile from a running .NET server pod using dotnet-trace.

This command will create a debug container, collect the CPU profile using dotnet-trace, and copy it back to your local machine.

The health probes will be temporarily modified to always return a success value to avoid the kubelet from considering the game server to not be responsive which would lead to its termination.

Expected arguments:

ENVIRONMENT (optional) -- Target environment name or id, eg, 'tough-falcons'.
POD (optional) -- Docker image name and tag, eg, 'mygame:364cff09' or '364cff09'.
EXTRA_ARGS (optional) -- Passed as-is to 'dotnet-trace'

Examples

shell

# Collect CPU profile from the only running pod.
metaplay debug collect-cpu-profile tough-falcons

# Collect CPU profile from pod 'service-0'.
metaplay debug collect-cpu-profile tough-falcons service-0

# Specify custom output path on your disk.
metaplay debug collect-cpu-profile tough-falcons -o /path/to/output.nettrace

# Specify format (speedscope, chromium, nettrace)
metaplay debug collect-cpu-profile tough-falcons --format speedscope

# Specify duration in seconds (default: 30)
metaplay debug collect-cpu-profile tough-falcons --duration 60

# Pass extra arguments to dotnet-trace (after --)
metaplay debug collect-cpu-profile tough-falcons -- --providers Microsoft-Windows-DotNETRuntime:4:4

Flags

--duration <int>: Duration of the trace in seconds (default: 30)
--format <string>: Output format: 'nettrace', 'speedscope', or 'chromium' (default: nettrace)
--output, -o <string>: Output path for the CPU profile file (default: profile-YYYYMMDD-hhmmss.nettrace)

`metaplay debug collect-heap-dump [ENVIRONMENT] [POD] [flags]`

PREVIEW: This is a preview feature and interface may change in the future.

Collect a heap dump from a running .NET server pod using dotnet-gcdump.

WARNING: This operation is very intrusive as it completely freeze the target process for the duration of the operation. This can be from seconds to minutes, depending on the process heap size.

This command will create a debug container, collect the heap dump using dotnet-gcdump, and copy it back to your local machine.

The health probes will be temporarily modified to always return a success value to avoid the kubelet from considering the game server to not be responsive which would lead to its termination.

Expected arguments:

ENVIRONMENT (optional) -- Target environment name or id, eg, 'tough-falcons'.
POD (optional) -- Docker image name and tag, eg, 'mygame:364cff09' or '364cff09'.

Examples

shell

# Collect heap dump from the only running pod.
metaplay debug collect-heap-dump tough-falcons

# Collect heap dump from pod 'service-0'.
metaplay debug collect-heap-dump tough-falcons service-0

# Use 'dotnet-dump' instead of 'dotnet-gcdump'.
metaplay debug collect-heap-dump tough-falcons --mode dump

# Specify custom output path on your disk. The .gcdump suffix must be used with dotnet-gcdump!
metaplay debug collect-heap-dump tough-falcons -o /path/to/output.gcdump

# Don't ask for confirmation on the operation.
metaplay debug collect-heap-dump tough-falcons --yes

Flags

--output, -o <string>: Output path for the heap dump file (default: dump-YYYYMMDD-hhmmss.gcdump)
--yes: Skip heap size warning and proceed with dump

`metaplay debug database [ENVIRONMENT] [POD] [SHARD] [flags]`

PREVIEW: This is a preview feature and interface may change in the future.

Connect to a database shard for the specified environment using MariaDB CLI.

This command starts a temporary debug pod and runs an SQL client inside it, connecting to the specified database replica (read-only or read-write), and shard.

By default, the read-only replica will be used, for safety. Use --read-write to connect to the read-write replica.

Optionally, you can use --query <sql> to specify a SQL statement to execute immediately and output the result, or --query-file <filename> to read the SQL statement from a file.

When running non-interactive queries (using --query or --query-file), you can use --output <filename> to write the output to a file instead of stdout.

Expected arguments:

ENVIRONMENT (optional) -- Target environment name or id, eg, 'tough-falcons'.
SHARD (optional) -- Optional: Database shard index to connect to. If not specified, the first shard (index 0) will be used.

Related commands:

'metaplay debug shell' starts a debug shell in a running game server pod.

Aliases

db

Examples

shell

# Connect to a database shard in the 'nimbly' environment using the first shard
metaplay debug database nimbly

# Connect to the second shard in the 'nimbly' environment (0-based indexing is used)
metaplay debug database nimbly 1

# Connect to the read-write replica instead of the default read-only replica
metaplay debug database nimbly --read-write

# Run a query on the first shard and exit immediately after
metaplay debug database nimbly 0 --query "SELECT COUNT(*) FROM Players"

# Run a query on the first shard and write the output to a file
metaplay debug database nimbly 0 --query "SELECT COUNT(*) FROM Players" --output count.txt

# Run a query from a file on the first shard and exit immediately after
metaplay debug database nimbly 0 --query-file ./my_query.sql

Flags

--output <string>: Write output to a file instead of stdout (non-interactive)
--query, -q <string>: Run this SQL query and exit (non-interactive)
--query-file <string>: Read SQL query from a file and execute it (non-interactive)
--read-write: Connect to the read-write replica (default: read-only)

`metaplay debug logs [ENVIRONMENT] [flags]`

Show logs from one or more game server pods in the target environment.

Expected arguments:

ENVIRONMENT (optional) -- Target environment name or id, eg, 'tough-falcons'.

Related commands:

'metaplay deploy server ...' to deploy a game server into the cloud.

Examples

shell

# Show logs from environment 'tough-falcons' up until now.
metaplay debug logs tough-falcons

# Show logs and keep streaming them until terminated.
metaplay debug logs tough-falcons -f

# Show logs only from the 'service-0' pod.
metaplay debug logs tough-falcons --pod service-0

# Show logs more recent than 3 hours.
metaplay debug logs tough-falcons --since=3h

# Show logs since Dec 27th, 2024 15:04:05 UTC.
metaplay debug logs tough-falcons --since-time=2024-12-27T15:04:05Z

Flags

--follow, -f: Keep streaming logs from pods until terminated.
--pod <string>: Show logs only from the pod matching this name.
--since <duration>: Show logs more recent than specified duration like 30s, 15m, or 3h. Defaults to all logs. (default: 0s)
--since-time <string>: Show logs more recent than specified timestamp. Defaults to all logs.

`metaplay debug server-status ENVIRONMENT [flags]`

Check the status of a game server deployment.

Runs the same checks as 'deploy server' but without deploying anything:

All expected pods are present, healthy, and ready.
Client-facing domain name resolves correctly.
Game server responds to client traffic.
Admin domain name resolves correctly.
Admin endpoint responds with a success code.

Expected arguments:

ENVIRONMENT (optional) -- Target environment name or id, eg, 'tough-falcons'.

Related commands:

'metaplay deploy server ...' deploys a game server and runs these checks.
'metaplay get server-info ...' shows information about the game server deployment.

Aliases

srv

Examples

shell

# Let the CLI ask for the target environment to check deployment status.
metaplay debug server-status

# Check the status of a game server deployment in a specific environment.
metaplay debug server-status tough-falcons

`metaplay debug shell [ENVIRONMENT] [POD] [flags]`

PREVIEW: This command is in preview and subject to change

Start a debug container targeting a game server pod in the specified environment. This command creates a Kubernetes ephemeral debug container that attaches to an existing game server pod, allowing you to inspect and troubleshoot the running server.

If multiple game server pods are running in the environment, you must specify which pod to debug by providing its name as the second argument. If only one pod is running, the pod name is optional.

The debug container uses the metaplay/diagnostics:latest image which contains various debugging and diagnostic tools. The container is attached to the shard-server container within the pod, giving you direct access to the game server process.

Expected arguments:

ENVIRONMENT (optional) -- Target environment, eg, 'tough-falcons'.
POD (optional) -- Target pod name, eg, 'all-0'.

Aliases

sh

Examples

shell

# Start a debug container in the 'tough-falcons' environment (when only one pod is running).
metaplay debug shell tough-falcons

# Start a debug container pod named 'service-0' in the environment 'tough-falcons'.
metaplay debug shell tough-falcons service-0

`metaplay deploy`

Deploy server or bots into the cloud

`metaplay deploy botclient [ENVIRONMENT] [IMAGE_TAG] [flags] [-- EXTRA_ARGS]`

PREVIEW: This command is in preview and subject to change! It also still lacks some key functionality.

Deploy bots into the target cloud environment using the specified docker image version. The image must exist in the target environment image repository.

Expected arguments:

ENVIRONMENT (optional) -- Target environment name or id, eg, 'tough-falcons'.
IMAGE_TAG -- Docker image name and tag, eg, '364cff09'.
EXTRA_ARGS (optional) -- Passed as-is to Helm.

Related commands:

'metaplay build image ...' to build the docker image.
'metaplay image push ...' to push the built image to the environment.
'metaplay debug logs ...' to view logs from the deployed server.
'metaplay debug shell ...' to debug a running server pod.

Aliases

bots, botclients

Examples

shell

# Deploy bots into environment tough-falcons with the docker image tag 364cff09.
metaplay deploy botclient tough-falcons 364cff09

Flags

--helm-chart-repo <string>: Override for Helm chart repository to use for the metaplay-loadtest chart
--helm-chart-version <string>: Override for Helm chart version to use, eg, '0.4.2'
--helm-release-name <string>: Helm release name to use for the bot deployment (defaults to '<environmentID>-loadtest'
--local-chart-path <string>: Path to a local version of the metaplay-loadtest chart (repository and version are ignored if this is set)
--values, -f <string>: Override for path to the Helm values file, e.g., 'Backend/Deployments/develop-botclients.yaml'

`metaplay deploy server ENVIRONMENT [IMAGE:]TAG [flags] [-- EXTRA_ARGS]`

Deploy a game server into a cloud environment using the specified docker image version.

After deploying the server image, various checks are run against the deployment to help help diagnose any potential issues:

All expected pods are present, healthy, and ready.
Client-facing domain name resolves correctly.
Game server responds to client traffic.
Admin domain name resolves correctly.
Admin endpoint responds with a success code.

When a full docker image tag is specified (eg, 'mygame:364cff09'), the image is first pushed to the environment's registry. If only a tag is specified (eg, '364cff09'), the image is assumed to be present in the remote registry already.

Expected arguments:

ENVIRONMENT (optional) -- Target environment name or id, eg, 'tough-falcons'.
[IMAGE:]TAG (optional) -- Docker image name and tag, eg, 'mygame:364cff09' or '364cff09'.
EXTRA_ARGS (optional) -- Passed as-is to Helm.

Related commands:

'metaplay build image ...' to build the docker image.
'metaplay image push ...' to push the built image to the environment.
'metaplay debug logs ...' to view logs from the deployed server.
'metaplay debug shell ...' to start a shell on a running server pod.

Aliases

srv

Examples

shell

# Push the local image and deploy to the environment tough-falcons.
metaplay deploy server tough-falcons mygame:364cff09

# Deploy an image that has already been pushed into the environment.
metaplay deploy server tough-falcons 364cff09

# Deploy the latest locally built image for this project.
metaplay deploy server tough-falcons latest-local

# Pass extra arguments to Helm.
metaplay deploy server tough-falcons mygame:364cff09 -- --set-string config.image.pullPolicy=Always

# Use Helm chart from the local disk.
metaplay deploy server tough-falcons mygame:364cff09 --local-chart-path=/path/to/metaplay-gameserver

# Override the Helm chart repository and version.
metaplay deploy server tough-falcons mygame:364cff09 --helm-chart-repo=https://custom-repo.domain.com --helm-chart-version=0.7.0

# Override the Helm release name.
metaplay deploy server tough-falcons mygame:364cff09 --helm-release-name=my-release-name

Flags

--helm-chart-repo <string>: Override for Helm chart repository to use for the metaplay-gameserver chart
--helm-chart-version <string>: Override for Helm chart version to use, eg, '0.7.0'
--helm-release-name <string>: Helm release name to use for the game server deployment (default to '<environmentID>-gameserver')
--local-chart-path <string>: Path to a local version of the metaplay-gameserver chart (repository and version are ignored if this is set)
--values, -f <string>: Override for path to the Helm values file, e.g., 'Backend/Deployments/develop-server.yaml'

`metaplay dev [flags]`

Commands for local development

Flags

--color <string>: Should the output be colored (yes/no/auto)? [env: METAPLAYCLI_COLOR] (default: auto)
--project, -p <string>: Path to the to project directory (where metaplay-project.yaml is located)
--skip-version-check: Skip the check for a new CLI version being available
--verbose, -v: Enable verbose logging, useful for troubleshooting [env: METAPLAYCLI_VERBOSE]

`metaplay dev botclient [flags] [-- EXTRA_ARGS]`

Run simulated bots against the locally running server, or a cloud environment.

Expected arguments:

EXTRA_ARGS (optional) -- Passed as-is to 'dotnet run'.

Related commands:

'metaplay dev server' runs the game server locally.
'metaplay dev dashboard' runs the LiveOps Dashboard locally.
'metaplay build botclient' builds the BotClient project.

Examples

shell

# Run bots against the locally running server.
metaplay dev botclient

# Run bots against the 'tough-falcons' cloud environment.
metaplay dev botclient -e tough-falcons

# Pass additional arguments to 'dotnet run' of the BotClient project.
metaplay dev botclient -- -MaxBots=5 -MaxBotId=20

Flags

--environment, -e <string>: Environment (from metaplay-project.yaml) to run the bots against.

`metaplay dev dashboard`

Run the dashboard Vue.js project locally in development mode

Aliases

dash

`metaplay dev image IMAGE:TAG [flags] [-- EXTRA_ARGS]`

Run a pre-built docker image locally.

The LiveOps Dashboard is served at http://localhost:5550.

Expected arguments:

IMAGE:TAG (optional) -- Docker image name and tag, eg, 'mygame:364cff09'.
EXTRA_ARGS (optional) -- Passed as-is to 'docker run'.

Related commands:

'metaplay build image ...' to build a server Docker image.

Examples

shell

# Run the docker image (until terminated).
metaplay dev image mygame:test

# Run the latest built local docker image.
metaplay dev image latest-local

`metaplay dev server [flags] [-- EXTRA_ARGS]`

Run the C# game server locally.

Also check that the .NET SDK is installed and is a recent enough version.

This command is roughly equivalent to running: Backend/Server$ dotnet run EXTRA_ARGS

Expected arguments:

EXTRA_ARGS (optional) -- Passed as-is to 'dotnet run'.

Examples

shell

# Run the server. Stop the server by pressing 'q'.
metaplay dev server

# Run with specific log level.
metaplay dev server -- -LogLevel=Warning

# Pass additional arguments to the game server (dotnet run).
metaplay dev server -- -ExitAfter=00:00:30

`metaplay get`

Get information about cloud resources

`metaplay get aws-credentials ENVIRONMENT [flags]`

Get temporary AWS credentials for accessing resources in the target environment. These credentials can be used to authenticate AWS CLI commands or SDK calls.

The credentials include:

AWS Access Key ID
AWS Secret Access Key
AWS Session Token (for temporary credentials)

Two output formats are supported:

text: Human-readable format, suitable for reading and copying values
json: Machine-readable format, suitable for parsing and automation

Expected arguments:

ENVIRONMENT (optional) -- Target environment name or id, eg, 'tough-falcons'.

Related commands:

'metaplay get kubeconfig ...' to get Kubernetes configuration
'metaplay get environment-info ...' to get environment details

Aliases

aws-creds

Examples

shell

# Get credentials in human-readable text format (default)
metaplay get aws-credentials tough-falcons

# Get credentials in JSON format for scripting
metaplay get aws-credentials tough-falcons --format json

# Example of using the credentials with AWS CLI (bash):
eval $(metaplay get aws-credentials tough-falcons --format json | jq -r '
  "export AWS_ACCESS_KEY_ID=\(.AccessKeyId)
   export AWS_SECRET_ACCESS_KEY=\(.SecretAccessKey)
   export AWS_SESSION_TOKEN=\(.SessionToken)"
')

Flags

--format, -f <string>: Output format (text or json) (default: text)

`metaplay get environment-info ENVIRONMENT [flags]`

Get information about the target environment.

By default, displays the most relevant information in a human-readable text format. Use --format=json to get the complete environment information in JSON format.

Expected arguments:

ENVIRONMENT (optional) -- Target environment name or id, eg, 'tough-falcons'.

Related commands:

'metaplay get server-info ...' to get information about the game server deployment.
'metaplay debug server-status ...' to get diagnostics about the health of the deployment.

Aliases

env-info

Examples

shell

# Show relevant environment information in text format (default)
metaplay get environment-info tough-falcons

# Show complete environment information in JSON format
metaplay get environment-info tough-falcons --format=json

Flags

--format <string>: Output format. Valid values are 'text' or 'json' (default: text)

`metaplay get kubeconfig ENVIRONMENT [AUTH_PROVIDER] [flags]`

Get the Kubernetes KubeConfig for accessing the target environment's cluster.

The KubeConfig can be generated with two different credential handling types:

dynamic: Uses the Metaplay CLI to fetch fresh credentials when needed (recommended for human users)
static: Embeds static credentials in the KubeConfig (recommended for CI/CD pipelines)

If no type is specified, it defaults to:

dynamic for human users (logged in with refresh token)
static for machine users (logged in with access token only)

The KubeConfig can be written to a file using the --output flag, or printed to stdout if not specified.

Expected arguments:

ENVIRONMENT (optional) -- Target environment name or id, eg, 'tough-falcons'.
AUTH_PROVIDER (optional) -- Name of the auth provider to use. Defaults to 'metaplay'.

Examples

shell

# Get KubeConfig for environment tough-falcons with dynamic credentials
metaplay get kubeconfig tough-falcons --type=dynamic

# Get KubeConfig with static credentials and save to a file
metaplay get kubeconfig tough-falcons --type=static --output=kubeconfig.yaml

# Get KubeConfig with default credentials type (based on user type)
metaplay get kubeconfig tough-falcons

# Get KubeConfig using a custom auth provider
metaplay get kubeconfig tough-falcons my-auth-provider

Flags

--output, -o <string>: Path of the output file where to write kubeconfig (written to stdout if not specified)
--type, -t <string>: Type of credentials handling in kubeconfig, static or dynamic

`metaplay get server-info ENVIRONMENT [flags]`

PREVIEW: This command is currently in preview and may change in future releases.

This command shows details about the game server deployment running in the cloud, including information about the Helm release and the deployed container image.

By default, displays the most relevant information in a human-readable text format. Use --format=json to get the complete server information in JSON format. WARNING: The JSON output is subject to change!

Expected arguments:

ENVIRONMENT (optional) -- Target environment name or id, eg, 'lovely-wombats-build-nimbly'.

Related commands:

'metaplay get env-info ...' to get information about the target environment.
'metaplay debug server-status ...' to get diagnostics about the health of the deployment.
'metaplay deploy server ...' to deploy a game server.

Aliases

srv-info

Examples

shell

# Show server deployment information in text format (default)
metaplay get server-info lovely-wombats-build-nimbly

Flags

--format <string>: Output format. Valid values are 'text' or 'json' (default: text)

`metaplay help [command]`

Help provides help for any command in the application. Simply type metaplay help [path to command] for full details.

`metaplay image`

Commands for managing server Docker images

`metaplay image push ENVIRONMENT IMAGE:TAG`

Push a built game server docker image to the target environment's image repository.

Expected arguments:

ENVIRONMENT -- Target environment ID, eg, 'tough-falcons'.
IMAGE:TAG -- Docker image name and tag, eg, 'mygame:364cff09'.

Related commands:

The docker image can be built with 'metaplay build image ...'.
After pushing, the image can be deployed into the environment using 'metaplay deploy server ...'.

Examples

shell

# Push the docker image 'mygame:1a27c25753' into environment 'tough-falcons'.
metaplay image push tough-falcons mygame:1a27c25753

`metaplay init`

Initialize project features

`metaplay init dashboard [flags]`

Setup the development environment for a custom LiveOps Dashboard in your project.

This command does the following:

Populate a fresh LiveOps Dashboard Node.js project into Backend/Dashboard
Initialize the following in your project:

pnpm-workspace.yaml (pnpm workspace configuration file)
Backend/dashboard.code-workspace (Visual Studio Code workspace)

Update metaplay-project.yaml to refer to your custom dashboard.
Generate the pnpm-lock.yaml file using 'pnpm install'.

Related commands:

'metaplay build dashboard' to build the dashboard locally.
'metaplay dev dashboard' to serve the dashboard locally.

Examples

shell

# Initialize the custom LiveOps Dashboard in the project.
metaplay init dashboard

`metaplay init project [flags]`

Integrate Metaplay SDK into an existing project.

By default, this command downloads the latest Metaplay SDK from the portal. You must be logged in (using 'metaplay auth login') and have signed the SDK terms and conditions in the portal (https://portal.metaplay.dev).

This command does the following:

Extract the Metaplay SDK contents into MetaplaySDK/.
Initialize the following in your project:

metaplay-project.yaml ...
<unity-project>/Assets/MetaplayHelloWorld
<unity-project>/Assets/SharedCode
<unity-project>/Assets/StreamingAssets/...
Backend/

Add reference to the Metaplay Client SDK to your Unity project package.json.

Related commands:

'metaplay build image' builds a docker image to be deployed to the cloud.
'metaplay update project-environments' updates the environments list in metaplay-project.yaml from the cloud.
'metaplay init dashboard' initializes custom LiveOps Dashboard in the project.

Examples

shell

# Initialize SDK in your project using the interactive wizard.
metaplay init project

# Initialize SDK in your project using a specific project ID.
metaplay init project --project-id=fancy-gorgeous-bear

# Initialize SDK in your project at a specific path.
metaplay init project --project ../project-path

# Specify Metaplay SDK version to use (only 32.0 and above are supported).
metaplay init project --sdk-version=32.0

# Use a pre-downloaded Metaplay SDK archive.
metaplay init project --sdk-source=metaplay-sdk-release-32.0.zip

Flags

--auto-agree: Automatically agree to the privacy policy and terms and conditions
--project-id <string>: The ID for your project, eg, 'fancy-gorgeous-bear' (optional)
--sdk-source <string>: Install from the specified SDK archive file or use existing MetaplaySDK directory, eg, 'metaplay-sdk-release-32.0.zip' (optional)
--sdk-version <string>: Specify Metaplay SDK version to use, defaults to latest (optional)
--unity-project <string>: Path to the Unity project files within the project (default: auto-detect)
--yes: Automatically confirm the 'Does this look correct?' confirmation

`metaplay init project-config [flags]`

Initialize a metaplay-project.yaml configuration file in an existing project directory. This file is used by the CLI to understand the project structure and configuration.

The command will auto-detect various project paths and settings:

Unity project location
MetaplaySDK directory
Game backend directory
Game dashboard directory (if present)
Shared code directory
.NET runtime version

The detected paths can be overridden using command-line flags if needed. All paths are stored relative to the project root directory.

After detection, the command will:

Validate the detected paths and settings
Show a summary of what was found
Ask for confirmation (unless --yes is specified)
Create the metaplay-project.yaml file

Requires Metaplay SDK 32.0 or later to be updated in your project repository.

Related commands:

'metaplay init project' to create a new project from scratch
'metaplay update project-environments' to update environment configurations

Examples

shell

# Generate the in your project.
metaplay init project-config

# Specify the project ID.
metaplay init project-config --project-id=lovely-wombats-build

# Auto-approve the operation.
metaplay init project-config --yes

Flags

--backend-path <string>: Path to the game backend directory (default: auto-detect)
--dashboard-path <string>: Path to the game dashboard directory (default: auto-detect)
--dotnet-version <string>: .NET runtime version (default: auto-detect)
--project-id <string>: The ID for your project, eg, 'fancy-gorgeous-bear' (optional)
--sdk-path <string>: Path to the MetaplaySDK directory (default: auto-detect)
--shared-code-path <string>: Path to the shared code directory (default: auto-detect)
--unity-project <string>: Path to the Unity project files within the project (default: auto-detect)
--yes: Automatically confirm to the 'Does this look correct?' confirmation

`metaplay remove`

Remove deployed components from the cloud

`metaplay remove botclient [ENVIRONMENT]`

Remove the BotClient deployment from the target environment.

Expected arguments:

ENVIRONMENT (optional) -- Target environment name or id, eg, 'tough-falcons'.

Aliases

bots, botclients

Examples

shell

# Remove botclient deployment from environment tough-falcons.
metaplay remove botclient tough-falcons

`metaplay remove server ENVIRONMENT`

Remove the game server deployment from the target environment.

Expected arguments:

ENVIRONMENT (optional) -- Target environment name or id, eg, 'tough-falcons'.

Aliases

game-server

Examples

shell

# Remove game server deployment from environment tough-falcons.
metaplay remove game-server tough-falcons

`metaplay secrets`

Manage Kubernetes secrets of an environment

`metaplay secrets create ENVIRONMENT NAME [flags]`

Create a user secret in the target environment with the given name and payload.

Secret name must start with 'user-'. This avoids conflicts with other secrets.

Each secret consists of multiple entries, with each entry being a key-value pair. Use the --from-literal and --from-file flags to prove the key-value pairs. Multiple key-value pairs can be specified with any combination of the flag. All the keys must be unique within a single secret.

The game server supports a special syntax 'kube-secret://<secretName>#<secretKey>' to access Kubernetes secrets in the various runtime options, configurable from the Options.*.yaml files.

Expected arguments:

ENVIRONMENT (optional) -- Target environment name or id, eg, 'tough-falcons'.
NAME (optional) -- Name of the secret, e.g., 'user-some-secret'.

Related commands:

'metaplay secrets delete ENVIRONMENT NAME ...' to delete a user secret.
'metaplay secrets list ENVIRONMENT ...' to list all user secrets.
'metaplay secrets show ENVIRONMENT NAME ...' to show the contents of a user secret.

Examples

shell

# Create a secret named 'user-mysecret' in environment 'tough-falcons' with two entries.
# Accessible with URLs 'kube-secret://user-mysecret#username' and 'kube-secret://user-mysecret#password'
metaplay secrets create tough-falcons user-mysecret --from-literal=username=foobar --from-literal=password=tops3cret

# Create a secret with entry payload read from a file.
# Accessible with URL 'kube-secret://user-mysecret#credentials'
metaplay secrets create tough-falcons user-mysecret --from-file=credentials=../../credentials-dev.json

Flags

--from-file <stringArray>: Provide a key-value pair entry with the value read from a file (e.g., secret=../secret.txt) (default: [])
--from-literal <stringArray>: Provide a key-value pair entry using the literal value (e.g., username=foobar) (default: [])

`metaplay secrets delete ENVIRONMENT NAME [flags]`

Delete a user-created secret with the given name from the target environment.

Expected arguments:

ENVIRONMENT -- Target environment name or id, eg, 'tough-falcons'.
NAME -- Name of the secret, e.g., 'user-some-secret'.

Related commands:

'metaplay secrets create ENVIRONMENT NAME ...' to create a new user secret.
'metaplay secrets list ENVIRONMENT ...' to list all user secrets.
'metaplay secrets show ENVIRONMENT NAME ...' to show the contents of a user secret.

Examples

shell

# Delete the secret 'user-mysecret' from the environment 'tough-falcons'.
metaplay secrets delete tough-falcons user-mysecret

`metaplay secrets list ENVIRONMENT [flags]`

Show all user-created secrets in the target environment.

In the default output mode, the secrets are sanitized to avoid accidentally showing them. Use --show-values flag to show the secrets. When using --format=json, the secret values are always shown.

Expected arguments:

ENVIRONMENT (optional) -- Target environment name or id, eg, 'tough-falcons'.

Related commands:

'metaplay secrets create ENVIRONMENT NAME ...' to create a new user secret.
'metaplay secrets delete ENVIRONMENT NAME ...' to delete a user secret.
'metaplay secrets show ENVIRONMENT NAME ...' to show the contents of a user secret.

Examples

shell

# Show all secrets in text format (default) with their values censored.
metaplay secrets list tough-falcons

# Show all secrets with their values shown.
metaplay secrets list tough-falcons --show-values

# Show all secrets in JSON format (with all Kubernetes metadata included).
metaplay secrets list tough-falcons --format=json

Flags

--format <string>: Output format. Valid values are 'text' or 'json'. JSON format always shows values. (default: text)
--show-values: Show the values of the secrets. Only applies to text format.

`metaplay secrets show ENVIRONMENT NAME [flags]`

Show the contents of a single user secret.

By default, a human-readable text format is used. When using in a script, use the --format=json to output JSON format.

Expected arguments:

ENVIRONMENT -- Target environment name or id, eg, 'tough-falcons'.
NAME -- Name of the secret, e.g., 'user-some-secret'.

Related commands:

'metaplay secrets create ENVIRONMENT NAME ...' to create a new user secret.
'metaplay secrets delete ENVIRONMENT NAME ...' to delete a user secret.
'metaplay secrets list ENVIRONMENT ...' to list all user secrets.

Examples

shell

# Show the contents of secret user-mysecret in environment tough-falcons.
metaplay secrets show tough-falcons user-mysecret

# Show the contents of secret in text format (default).
metaplay secrets show tough-falcons user-mysecret --format=text

# Show the contents of secret in JSON format.
metaplay secrets show tough-falcons user-mysecret --format=json

# Extract the value of the secret field named 'default' and decode the raw value of it.
metaplay secrets show tough-falcons user-mysecret --format=json | jq -r .data.default | base64 -d

Flags

--format <string>: Output format. Valid values are 'text' or 'json'. JSON format includes all Kubernetes metadata. (default: text)

`metaplay update`

Update components or tools in the project

`metaplay update cli`

Update the Metaplay CLI to the latest version

`metaplay update project-environments [flags]`

Update the environments in the metaplay-project.yaml from the Metaplay Portal.

Related commands:

'metaplay deploy server' ...

Aliases

project-envs

Examples

shell

# Update the project environments from the portal.
metaplay update project-environments

`metaplay version [flags]`

Print the version information of this CLI

Flags

--format <string>: Output format. Valid values are 'text' or 'json' (default: text)

Release Notes

Release 33

Release 32

Release 31

Release 30

Release 29

Release 27

Release 25

metaplay [flags] ​

Examples ​

Flags ​

metaplay auth ​

metaplay auth login [AUTH_PROVIDER] ​

metaplay auth logout [AUTH_PROVIDER] ​

metaplay auth machine-login [AUTH_PROVIDER] [flags] ​

Flags ​

metaplay auth whoami [AUTH_PROVIDER] [flags] ​

Examples ​

Flags ​

metaplay build ​

Aliases ​

metaplay build botclient [flags] ​

Examples ​

metaplay build dashboard [flags] ​

Aliases ​

Examples ​

Flags ​

metaplay build image [IMAGE] [flags] [-- EXTRA_ARGS] ​

Aliases ​

Examples ​

Flags ​

metaplay build server [flags] ​

Examples ​

metaplay completion ​

metaplay completion bash ​

Linux: ​

macOS: ​

Flags ​

metaplay completion fish [flags] ​

Flags ​

metaplay completion powershell [flags] ​

Flags ​

metaplay completion zsh [flags] ​

Linux: ​

macOS: ​

Flags ​

metaplay database ​

Aliases ​

metaplay database reset [ENVIRONMENT] [flags] ​

Aliases ​

Examples ​

Flags ​

metaplay debug ​

Aliases ​

metaplay debug admin-request ENVIRONMENT METHOD PATH [flags] ​

Aliases ​

Examples ​

Flags ​

metaplay debug collect-cpu-profile [ENVIRONMENT] [POD] [flags] ​

Examples ​

Flags ​

metaplay debug collect-heap-dump [ENVIRONMENT] [POD] [flags] ​

Examples ​

Flags ​

metaplay debug database [ENVIRONMENT] [POD] [SHARD] [flags] ​

Aliases ​

Examples ​

Flags ​

metaplay debug logs [ENVIRONMENT] [flags] ​

Examples ​

Flags ​

metaplay debug server-status ENVIRONMENT [flags] ​

Aliases ​

Examples ​

metaplay debug shell [ENVIRONMENT] [POD] [flags] ​

Aliases ​

Examples ​

metaplay deploy ​

metaplay deploy botclient [ENVIRONMENT] [IMAGE_TAG] [flags] [-- EXTRA_ARGS] ​

`metaplay [flags]`

Examples

Flags

`metaplay auth`

`metaplay auth login [AUTH_PROVIDER]`

`metaplay auth logout [AUTH_PROVIDER]`

`metaplay auth machine-login [AUTH_PROVIDER] [flags]`

Flags

`metaplay auth whoami [AUTH_PROVIDER] [flags]`

Examples

Flags

`metaplay build`

Aliases

`metaplay build botclient [flags]`

Examples

`metaplay build dashboard [flags]`

Aliases

Examples

Flags

`metaplay build image [IMAGE] [flags] [-- EXTRA_ARGS]`

Aliases

Examples

Flags

`metaplay build server [flags]`

Examples

`metaplay completion`

`metaplay completion bash`

Linux:

macOS:

Flags

`metaplay completion fish [flags]`

Flags

`metaplay completion powershell [flags]`

Flags

`metaplay completion zsh [flags]`

Linux:

macOS:

Flags

`metaplay database`

Aliases

`metaplay database reset [ENVIRONMENT] [flags]`

Aliases

Examples

Flags

`metaplay debug`

Aliases

`metaplay debug admin-request ENVIRONMENT METHOD PATH [flags]`

Aliases

Examples

Flags

`metaplay debug collect-cpu-profile [ENVIRONMENT] [POD] [flags]`

Examples

Flags

`metaplay debug collect-heap-dump [ENVIRONMENT] [POD] [flags]`

Examples

Flags

`metaplay debug database [ENVIRONMENT] [POD] [SHARD] [flags]`

Aliases

Examples

Flags

`metaplay debug logs [ENVIRONMENT] [flags]`

Examples

Flags

`metaplay debug server-status ENVIRONMENT [flags]`

Aliases

Examples

`metaplay debug shell [ENVIRONMENT] [POD] [flags]`

Aliases

Examples

`metaplay deploy`

`metaplay deploy botclient [ENVIRONMENT] [IMAGE_TAG] [flags] [-- EXTRA_ARGS]`

Aliases

Examples

Flags

`metaplay deploy server ENVIRONMENT [IMAGE:]TAG [flags] [-- EXTRA_ARGS]`

Aliases

Examples

Flags

`metaplay dev [flags]`

Flags