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)
export HATHORA_TOKEN=ey...
export HATHORA_APP_ID=abc123
hathora build create --file $FILE_PATH
- Config File: Pass in the path to a config file with the variables set (using the object path described in the Config File Path column in the tables below)
build:
id: 5
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 |
|---|---|---|---|---|---|
| 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 |
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 or omit 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 or omit 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 |