Hathora CLI tool

Hathora offers a command-line interface (CLI) that lets you create builds and deployments on our platform using terminal or through an automated system.

note

We recommend all users migrate from our old CLI (it has been deprecated and will no longer receive updates). Follow our migration guide for detailed instructions.

Install the CLI

You have four options for installing Hathora CLI.

1. Install Script

The install script can be used to download and install the appropriate binary for your platform.

note

The install script requires sudo/admin privileges to execute.

Windows (Powershell)

iwr -useb https://raw.githubusercontent.com/hathora/ci/main/install.ps1 | iex

MacOS/Linux

curl -s https://raw.githubusercontent.com/hathora/ci/main/install.sh | sh

2. Raw Binary Downloads

Download the latest binaries for your platform here.

3. Go Install

go install github.com/hathora/ci/hathora@latest

4. Docker Image

Pull from GitHub Container Registry.

docker pull ghcr.io/hathora/ci:latest

Command-line Flags

You can pass in command-line flags in a couple of ways:

• Inline: Pass the flag in as an argument (using the Flag Name) to the command (i.e.--token ey...)
• Inline Abbreviations: Pass the flag in as an argument (using the Abbreviated Alias) to the command (i.e. -t ey...)
• Environment Variables: Set the value as an environment variable prior to running the command (using the Env Var Alias)
• Config file: use a config file like config.yaml to pass parameters for your CLI commands

export HATHORA_TOKEN=ey...
export HATHORA_APP_ID=abc123
hathora build create --file $FILE_PATH

Config File

• In your CLI command, set the path to your config file:

hathora deploy -t ... --config ./config.yaml

• Example config.yaml file:

app:
  id: app-1234abcd-9cac-4bf2-ac0b-f86ae44e0c69
build:
  id: bld-abcd1234-3ea7-4504-ae1b-b35c3cdbb358

• Reference the tables below to see config file structure for each flag.

Global Flags

Flags available for all hathora commands

Flag	Env Var	Config File Path	Required	Description	Example
output(-o)	HATHORA_OUTPUT	global.output	false	Either json, text, or buildIdValue (which only returns the buildId to stdout).	json
output-pretty			false	Whether to pretty print JSON output. Has no effect if output is not json.	--output-pretty for true, omit for false
verbosity(-v,-vv,-vvv)	HATHORA_VERBOSITY	global.verbosity	false	Set the logging verbosity level.	2
hathora-cloud-endpoint	HATHORA_CLOUD_ENDPOINT	global.cloud-endpoint	false	Override the default API base URL	https://example.com
token(-t)	HATHORA_TOKEN		true	The access token for authenticating with the API	abc123

Build Flags

Flags available for the hathora build create command.

Flag	Env Var	Config File Path	Required	Description	Example
build-id (-b)	HATHORA_BUILD_ID	build.id	false	A build id override to use when creating the build	custom-build-id
build-tag(-bt)	HATHORA_BUILD_TAG	build.tag	false	The build tag (custom string)	v1.0.0
file(-f)	HATHORA_BUILD_FILE	build.file	true	The route to the tar file or the directory of the game server	/build/server.tgz

Deployment Flags

Flags available for the hathora deployment create command.

Flag	Env Var	Config File Path	Required	Description	Example
app-id(-a)	HATHORA_APP_ID	app.id	true	The application ID	app-258c30dd-cc4b-453a-9976-165c4c4af791
build-id(-b)	HATHORA_BUILD_ID	build.id	true (without --from-latest)	The ID of the build to deploy	10
deployment-tag	HATHORA_DEPLOYMENT_DEPLOYMENT_TAG	deployment.deployment-tag	false	The deployment tag (custom string)	my-deployment-tag-123
idle-timeout-enabled	HATHORA_DEPLOYMENT_IDLE_TIMEOUT_ENABLED	deployment.idle-timeout-enabled	true (without --from-latest)	Option to shut down processes that have had no new connections or rooms for five minutes	--idle-timeout-enabled for true, --idle-timeout-enabled=false for false
rooms-per-process	HATHORA_DEPLOYMENT_ROOMS_PER_PROCESS	deployment.rooms-per-process	true (without --from-latest)	How many rooms can be scheduled in a process. Between 1 and 10,000	50
transport-type	HATHORA_DEPLOYMENT_TRANSPORT_TYPE	deployment.transport-type	true (without --from-latest)	The underlying communication protocol to the exposed port. Either tcp, udp, or tls	tcp
container-port	HATHORA_DEPLOYMENT_CONTAINER_PORT	deployment.container-port	true (without --from-latest)	Default server port. Between 1 and 65535	8080
requested-memory-mb	HATHORA_DEPLOYMENT_REQUESTED_MEMORY_MB	deployment.requested-memory-mb	true (without --from-latest)	The amount of memory in MB allocated to your process. Between 1024 and 8192. Must be a 2048:1 ratio to requested cpu.	2048
requested-cpu	HATHORA_DEPLOYMENT_REQUESTED_CPU	deployment.requested-cpu	true (without --from-latest)	The number of cores allocated to your process. Between 0.5 and 4	1
additional-container-ports	HATHORA_DEPLOYMENT_ADDITIONAL_CONTAINER_PORTS	deployment.additional-container-ports	false	Additional ports and protocols to expose. <name>:<port>/<transport>. Can be passed multiple times or as a comma-delimited list.	auth:8081/tls
env	HATHORA_DEPLOYMENT_ENV		false	Environment variables to set in the process. <key>=<value> . Can be passed multiple times or as a comma-delimited list.	LOG_LEVEL=debug,MODE=1v1
from-latest	HATHORA_DEPLOYMENT_FROM_LATEST		false	Initializes any unset flag values based on the latest deployment	--from-latest for true, omit for false

Deploy Flags

Flags available for the hathora deploy command

Flag	Env Var	Config File Path	Required	Description	Example
app-id (-a)	HATHORA_APP_ID	app.id	true	The application ID	app-258c30dd-cc4b-453a-9976-165c4c4af791
build-tag (-bt)	HATHORA_BUILD_TAG	build.tag	false	The build tag (custom string)	v1.0.0
file (-f)	HATHORA_BUILD_FILE	build.file	true	The route to the tar file or the directory of the game server	/build/server.tgz
deployment-tag	HATHORA_DEPLOYMENT_DEPLOYMENT_TAG	deployment.deployment-tag	false	The deployment tag (custom string)	my-deployment-tag-123
idle-timeout-enabled	HATHORA_DEPLOYMENT_IDLE_TIMEOUT_ENABLED	deployment.idle-timeout-enabled	false	Option to shut down processes that have had no new connections or rooms for five minutes	--idle-timeout-enabled for true, --idle-timeout-enabled=false for false
rooms-per-process	HATHORA_DEPLOYMENT_ROOMS_PER_PROCESS	deployment.rooms-per-process	true (without --from-latest)	How many rooms can be scheduled in a process. Between 1 and 10,000	50
transport-type	HATHORA_DEPLOYMENT_TRANSPORT_TYPE	deployment.transport-type	true (without --from-latest)	The underlying communication protocol to the exposed port. Either tcp, udp, or tls	tcp
container-port	HATHORA_DEPLOYMENT_CONTAINER_PORT	deployment.container-port	true (without --from-latest)	Default server port. Between 1 and 65535	8080
requested-memory-mb	HATHORA_DEPLOYMENT_REQUESTED_MEMORY_MB	deployment.requested-memory-mb	true (without --from-latest)	The amount of memory in MB allocated to your process. Between 1024 and 8192. Must be a 2048:1 ratio to requested cpu.	2048
requested-cpu	HATHORA_DEPLOYMENT_REQUESTED_CPU	deployment.requested-cpu	true (without --from-latest)	The number of cores allocated to your process. Between 0.5 and 4	1
additional-container-ports	HATHORA_DEPLOYMENT_ADDITIONAL_CONTAINER_PORTS	deployment.additional-container-ports	false	Additional ports and protocols to expose. <name>:<port>/<transport>. Can be passed multiple times or as a comma-delimited list.	auth:8081/tls
env	HATHORA_DEPLOYMENT_ENV		false	Environment variables to set in the process. <key>=<value> . Can be passed multiple times or as a comma-delimited list.	LOG_LEVEL=debug
from-latest	HATHORA_DEPLOYMENT_FROM_LATEST		false	Initializes any unset deployment flag values based on the latest deployment

Log Flags

Flags available for the hathora log command

Flag	Env Var	Config File Path	Required	Description	Example
app-id (-a)	HATHORA_APP_ID	app.id	true	The application ID	app-258c30dd-cc4b-453a-9976-165c4c4af791
follow	HATHORA_LOG_FOLLOW	log.follow	false	whether to stream logs in real time (default false)	false
process-id (-p)	HATHORA_LOG_PROCESS_ID	log.process-id	true	ID of the runtime instance of your game server	dabad027-b2b9-4bcc-8b38-41134ed0f811
tail-lines	HATHORA_LOG_TAIL_LINES	log.tail-lines	false	Number of lines to return from the most recent log history (1-5000)	50