th: the ThailandHosting CLI

What th is

th is the command line of ThailandHosting. It talks to the same API as the Console, acting as your account (after th auth login) or as an API key (in CI). Commands are grouped by service: th <group> <command> [arguments] [parameters].

th auth login
th container deploy api --source .
th static-site deploy docs ./dist
th object-storage cp -r ./backups th://my-bucket/backups
th database connect app-db
th queue tail jobs

th help lists every command. Add --help to any command (or run th help container deploy) to see its own parameters. Typing only a group, such as th container, lists the commands in it.

Parameters and arguments can come in any order: th container deploy api --port 3000 and th container deploy --port 3000 api do the same. A flag that is on by default is turned off with --no-, for example --no-ack.

Install

The install scripts download the latest release from GitHub and check it against the release’s SHA256SUMS before installing anything.

# Linux, macOS
curl -fsSL https://raw.githubusercontent.com/mrzack99s/thailandhosting-cli/main/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/mrzack99s/thailandhosting-cli/main/install.ps1 | iex

You can also download an archive for your system from GitHub Releases, or build it with Go 1.23 or newer:

go install github.com/mrzack99s/thailandhosting-cli/cmd/th@latest

Check the installed version with th version.

Sign in

1. Run th auth login. The CLI prints a link and a code, and opens the Console in your browser (with --no-browser it only prints the link, for a server without a desktop).
2. In the Console, check that the code matches the one in your terminal, then click Approve.
3. The terminal says who you are signed in as. If no Project is set yet, your first Project becomes the active one.

The sign-in lasts 90 days and is saved in the th config file (th/config.json in your user config folder, readable only by you). It is listed in the Console under Account → Sessions, where you can sign it out from anywhere.

th auth status        # who the CLI acts as (also: th whoami)
th auth logout        # sign this token out and remove it from the config file

In CI, don’t sign in: set an API key in TH_API_KEY instead (see Use in CI). When TH_API_KEY is set it takes precedence over a saved sign-in.

Choose a Project and region

Most commands work on one Project. New services also need a region. Set them once with th config, or per command:

th projects list
th config set project acme      # ID or slug
th regions list
th config set region bkk
th config list

Each setting is taken from the first place that has it:

1. The parameter on the command line: --project, --region, --endpoint.
2. The environment variable: TH_PROJECT, TH_REGION, TH_ENDPOINT.
3. The config file, set with th config set.

With no region set, a command that creates a service uses the platform’s default region and says so. An API key belongs to one Project, so with TH_API_KEY the Project comes from the key.

Global parameters

Every command takes these parameters as well as its own.

--help (or -h) prints a command’s usage and parameters instead of running it.

Output formats

By default commands print text for people: tables with a header row, or a short sentence saying what was done. With --format json they print the API’s JSON instead, for scripts and tools such as jq.

th container services list
th container services list --format json | jq -r '.[].name'

• Standard output carries only the result: the table, the JSON, the file you asked for (th object-storage cat), or the message (th queue receive).
• Standard error carries progress and hints: “Packing sources…”, build logs, upload progress, prompts and errors. Redirecting standard output to a file therefore gives you clean data.
• Errors look like ERROR: (th.container.deploy) …, naming the command that failed.

Commands that delete or replace something ask Do you want to continue (Y/n)? first. --quiet answers yes for you; without it, a command that cannot ask (no terminal on standard input) stops with an error instead of guessing.

Environment variables

Object Storage and the Queue Service take their own access keys, not the CLI sign-in. Signed in on your own computer you don’t need to create one: th asks the Console for a short-lived key of the Project (valid 12 hours, with what your role allows) and keeps it next to the config file until shortly before it expires. With TH_API_KEY, or to use a specific key, set the variables above.

Use in CI

Create a key in the Console, store it as a secret in your CI, and pass it in an environment variable. Use --quiet so nothing waits for an answer.

An API key works only on its own Project. GitHub Actions:

# .github/workflows/deploy.yml
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          curl -fsSL https://raw.githubusercontent.com/mrzack99s/thailandhosting-cli/main/install.sh | TH_INSTALL_DIR="$HOME/.local/bin" sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
      - run: th container deploy api --source . --quiet
        env:
          TH_API_KEY: ${{ secrets.TH_API_KEY }}

Give each pipeline its own key with only the scopes it needs. If one leaks, revoke just that key.

Exit codes

Command groups