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.
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.
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 | 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 |
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 | 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 |
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 |