Skip to main content

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

FlagEnv VarConfig File PathRequiredDescriptionExample
output(-o)HATHORA_OUTPUTglobal.outputfalseEither json, text, or buildIdValue (which only returns the buildId to stdout).json
output-prettyfalseWhether 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_VERBOSITYglobal.verbosityfalseSet the logging verbosity level.2
hathora-cloud-endpointHATHORA_CLOUD_ENDPOINTglobal.cloud-endpointfalseOverride the default API base URLhttps://example.com
token(-t)HATHORA_TOKENtrueThe access token for authenticating with the APIabc123

Build Flags

Flags available for the hathora build create command.

FlagEnv VarConfig File PathRequiredDescriptionExample
build-id (-b)HATHORA_BUILD_IDbuild.idfalseA build id override to use when creating the buildcustom-build-id
build-tag(-bt)HATHORA_BUILD_TAGbuild.tagfalseThe build tagv1.0.0
file(-f)HATHORA_BUILD_FILEbuild.filetrueThe 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.

FlagEnv VarConfig File PathRequiredDescriptionExample
app-id(-a)HATHORA_APP_IDapp.idtrueThe application IDapp-258c30dd-cc4b-453a-9976-165c4c4af791
build-id(-b)HATHORA_BUILD_IDbuild.idtrue (without --from-latest)The ID of the build to deploy10
idle-timeout-enabledHATHORA_DEPLOYMENT_IDLE_TIMEOUT_ENABLEDdeployment.idle-timeout-enabledtrue (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-processHATHORA_DEPLOYMENT_ROOMS_PER_PROCESSdeployment.rooms-per-processtrue (without --from-latest)How many rooms can be scheduled in a process. Between 1 and 10,00050
transport-typeHATHORA_DEPLOYMENT_TRANSPORT_TYPEdeployment.transport-typetrue (without --from-latest)The underlying communication protocol to the exposed port. Either tcp, udp, or tlstcp
container-portHATHORA_DEPLOYMENT_CONTAINER_PORTdeployment.container-porttrue (without --from-latest)Default server port. Between 1 and 655358080
requested-memory-mbHATHORA_DEPLOYMENT_REQUESTED_MEMORY_MBdeployment.requested-memory-mbtrue (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-cpuHATHORA_DEPLOYMENT_REQUESTED_CPUdeployment.requested-cputrue (without --from-latest)The number of cores allocated to your process. Between 0.5 and 41
additional-container-portsHATHORA_DEPLOYMENT_ADDITIONAL_CONTAINER_PORTSdeployment.additional-container-portsfalseAdditional ports and protocols to expose. <name>:<port>/<transport>. Can be passed multiple times or as a comma-delimited list.auth:8081/tls
envHATHORA_DEPLOYMENT_ENVfalseEnvironment 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-latestHATHORA_DEPLOYMENT_FROM_LATESTfalseInitializes 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

FlagEnv VarConfig File PathRequiredDescriptionExample
app-id (-a)HATHORA_APP_IDapp.idtrueThe application IDapp-258c30dd-cc4b-453a-9976-165c4c4af791
build-tag (-bt)HATHORA_BUILD_TAGbuild.tagfalseThe build tagv1.0.0
file (-f)HATHORA_BUILD_FILEbuild.filetrueThe route to the tar file or the directory of the game server/build/server.tgz
idle-timeout-enabledHATHORA_DEPLOYMENT_IDLE_TIMEOUT_ENABLEDdeployment.idle-timeout-enabledfalseOption 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-processHATHORA_DEPLOYMENT_ROOMS_PER_PROCESSdeployment.rooms-per-processtrue (without --from-latest)How many rooms can be scheduled in a process. Between 1 and 10,00050
transport-typeHATHORA_DEPLOYMENT_TRANSPORT_TYPEdeployment.transport-typetrue (without --from-latest)The underlying communication protocol to the exposed port. Either tcp, udp, or tlstcp
container-portHATHORA_DEPLOYMENT_CONTAINER_PORTdeployment.container-porttrue (without --from-latest)Default server port. Between 1 and 655358080
requested-memory-mbHATHORA_DEPLOYMENT_REQUESTED_MEMORY_MBdeployment.requested-memory-mbtrue (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-cpuHATHORA_DEPLOYMENT_REQUESTED_CPUdeployment.requested-cputrue (without --from-latest)The number of cores allocated to your process. Between 0.5 and 41
additional-container-portsHATHORA_DEPLOYMENT_ADDITIONAL_CONTAINER_PORTSdeployment.additional-container-portsfalseAdditional ports and protocols to expose. <name>:<port>/<transport>. Can be passed multiple times or as a comma-delimited list.auth:8081/tls
envHATHORA_DEPLOYMENT_ENVfalseEnvironment variables to set in the process. <key>=<value> . Can be passed multiple times or as a comma-delimited list.LOG_LEVEL=debug
from-latestHATHORA_DEPLOYMENT_FROM_LATESTfalseInitializes any unset deployment flag values based on the latest deployment

Log Flags

Flags available for the hathora log command

FlagEnv VarConfig File PathRequiredDescriptionExample
app-id (-a)HATHORA_APP_IDapp.idtrueThe application IDapp-258c30dd-cc4b-453a-9976-165c4c4af791
followHATHORA_LOG_FOLLOWlog.followfalsewhether to stream logs in real time (default false)false
process-id (-p)HATHORA_LOG_PROCESS_IDlog.process-idtrueID of the runtime instance of your game serverdabad027-b2b9-4bcc-8b38-41134ed0f811
tail-linesHATHORA_LOG_TAIL_LINESlog.tail-linesfalseNumber of lines to return from the most recent log history (1-5000)50