hostim CLI

Command-line interface for the Hostim cloud platform. Create and manage projects, apps, databases (MySQL / Postgres / Redis), volumes and domains from a terminal or a CI pipeline, over the public REST API at https://api.hostim.dev.

This file is the complete manual. The binary carries the same text: run hostim agent to print it to stdout, so an agent or a script can read the whole manual without network access.

Beta. The CLI and the public API are in beta. Commands, flags, output and API responses can change between releases. Check the release notes before you upgrade.

Contents

• Install
• Log in
• Configuration
• Global flags
• Output and exit codes
• Command reference
  • login, logout, whoami, use
  • projects
  • deploy
  • apps
  • status, logs, events, overview
  • env
  • domain
  • exec
  • db
  • volumes
  • templates
  • regions
  • completion
  • agent
  • mcp
  • version
• Template files
• Deploy from CI
• Development
• License

Install

curl -fsSL https://raw.githubusercontent.com/hostimdev/cli/main/install.sh | sh

The script downloads the release binary for the current OS and architecture (Linux and macOS, amd64 and arm64) and installs it into /usr/local/bin, using sudo when that directory is not writable. When it is not writable and sudo is not installed either — a plain container, for example — the script falls back to ~/.local/bin and tells you if that directory is not on your PATH. Set PREFIX to choose the location yourself:

curl -fsSL https://raw.githubusercontent.com/hostimdev/cli/main/install.sh | PREFIX=$HOME/.local sh

Some agents and CI policies refuse to pipe a downloaded script into a shell. The script is not required — fetch the release binary directly:

VERSION=$(curl -fsSL https://api.github.com/repos/hostimdev/cli/releases/latest | grep -o '"tag_name": *"[^"]*"' | cut -d'"' -f4)
curl -fsSL "https://github.com/hostimdev/cli/releases/download/${VERSION}/hostim_linux_amd64.tar.gz" | tar -xz hostim
install -m 0755 hostim /usr/local/bin/hostim   # or anywhere on your PATH

Build from source instead (Go 1.26+):

git clone https://github.com/hostimdev/cli && cd cli
make build           # writes bin/hostim
make install         # installs into /usr/local/bin (PREFIX to change)

Check the install:

hostim version

Log in

hostim login uses a device code. It prints a URL and a short code, you approve the request in the browser, and the token is saved automatically:

hostim login

hostim login polls until you approve and saves the token itself, so there is no need to write a waiting loop around it or to run it a second time. The browser step does not need a terminal, so an agent can run hostim login and show you the code. If you already have a token, store it directly instead — create one in the dashboard at https://console.hostim.dev:

hostim login --token-value "$T"   # non-interactive, for scripts and CI

login validates the token against the API before saving it to ~/.config/hostim/config.yml (mode 0600). In CI, skip login and export HOSTIM_TOKEN instead — no file is written.

Most commands act on one project. Set a default once:

hostim projects ls
hostim use my-project
hostim whoami                     # token source, current project, project count

Configuration

Values are resolved as flag → environment variable → config file, with a built-in default for the API URL.

The config file lives at ~/.config/hostim/config.yml, or $XDG_CONFIG_HOME/hostim/config.yml when XDG_CONFIG_HOME is set:

token: ...                 # written by `hostim login`
currentProject: my-project # written by `hostim use`
apiUrl: https://api.hostim.dev  # only written when --api-url was passed

Projects and apps can be named by name or by ID everywhere.

Global flags

Available on every command:

--token string      API token (overrides HOSTIM_TOKEN and config)
--api-url string    API base URL (default https://api.hostim.dev)
-p, --project       project to target (overrides HOSTIM_PROJECT and current project)
-o, --output        output format: table or json (default "table")
-h, --help          help for the command
-v, --version       version (root command only)

Destructive commands (rm, templates apply) ask for confirmation and take -y / --yes to skip the prompt.

Output and exit codes

Default output is an aligned text table meant for a human. -o json switches every command to machine output and is the right mode for scripts and agents:

• read commands print the API object or list as indented JSON;
• write commands print a single result object naming what happened, for example {"status":"created","kind":"app","name":"web"} or {"status":"ok","kind":"env","set":1};
• failures print a JSON object on stderr, for example {"status":"error","error":"..."}, and exit non-zero. When a command is short of several requirements, the object carries a "missing" array listing all of them at once.

Exit codes:

Command reference

Every example below is runnable as written once a token and a project are set.

login, logout, whoami, use

hostim login                          # device login: approve a code in the browser
hostim login --token-value "$TOKEN"   # store an existing API token instead
hostim logout                         # remove the stored token
hostim whoami                         # API URL, token source, current project
hostim whoami -o json
hostim use my-project                 # set the default project (verifies it exists)
hostim use my-project --force         # skip the check (offline)
hostim use --clear                    # unset the default project

projects

hostim projects ls                            # aliases: project, proj; ls | list
hostim projects get my-project
hostim projects create my-project --region eu-center
hostim projects rm my-project -y
hostim projects export -p prod -f prod.yml    # template YAML for `templates apply`
hostim projects export -p prod -o json        # template as JSON on stdout

--region is required on create; see hostim regions ls for the values.

projects export writes a desired-state template, not a backup: volume and database contents (data) are not exported. Costs, IDs, built-in domains and unused source blocks are stripped, and env var values are exported RAW — the file holds secrets (passwords, API keys), so store and share it like a password file. Docker registry passwords and git tokens are not readable through the API and are left out (registry usernames are kept); set them again after applying. Redeploy with hostim templates apply -f prod.yml --new-project prod-clone.

deploy

hostim deploy <app> creates the app when it does not exist (from --git or --docker-image) and otherwise updates its source and triggers a rebuild. It waits for the build and exits non-zero if the build fails, so it drops straight into a pipeline. hostim apps deploy is the same command.

# first deploy from a git repo
hostim deploy web \
  --git https://github.com/me/app --branch main \
  --plan sa-1-1 --port 8080 \
  --health-check-path /healthz \
  --env LOG_LEVEL=debug --env-file .env

# redeploy: source is unchanged, just rebuild
hostim deploy web

# deploy a docker image and do not wait
hostim deploy web --docker-image ghcr.io/me/app:latest --wait=false

# private registry
hostim deploy web --docker-image me/app:1.2.3 \
  --registry registry.example.com --docker-user ci --docker-pass "$REG_PASS"

# private git repo
hostim deploy web --git https://github.com/me/private --git-token "$GH_TOKEN"

# mount a volume and attach a domain on create
hostim deploy web --docker-image nginx --plan sa-1-1 --port 80 \
  --volume data:/var/lib/app --domain app.example.com

Flags: