cli

# hostim CLI

Command-line interface for the [Hostim](https://hostim.dev) 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](#install)
- [Log in](#log-in)
- [Configuration](#configuration)
- [Global flags](#global-flags)
- [Output and exit codes](#output-and-exit-codes)
- [Command reference](#command-reference)
  - [login, logout, whoami, use](#login-logout-whoami-use)
  - [projects](#projects)
  - [deploy](#deploy)
  - [apps](#apps)
  - [status, logs, events, overview](#status-logs-events-overview)
  - [env](#env)
  - [domain](#domain)
  - [exec](#exec)
  - [db](#db)
  - [volumes](#volumes)
  - [templates](#templates)
  - [regions](#regions)
  - [completion](#completion)
  - [agent](#agent)
  - [mcp](#mcp)
  - [version](#version)
- [Template files](#template-files)
- [Deploy from CI](#deploy-from-ci)
- [Development](#development)
- [License](#license)

## Install

```sh
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:

```sh
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:

```sh
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+):

```sh
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:

```sh
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:

```sh
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>:

```sh
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:

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

| Value | Flag | Environment variable | Config key |
|---|---|---|---|
| API token | `--token` | `HOSTIM_TOKEN` | `token` |
| API base URL | `--api-url` | `HOSTIM_API_URL` | `apiUrl` (default `https://api.hostim.dev`) |
| Target project | `-p`, `--project` | `HOSTIM_PROJECT` | `currentProject`, set by `hostim use` |

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

```yaml
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:

| Code | Meaning |
|---|---|
| 0 | success |
| 1 | any CLI or API error, or an aborted confirmation |
| other | `hostim exec` passes through the remote command's exit status |

## Command reference

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

### login, logout, whoami, use

```sh
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

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

```sh
# 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:

```
--git string                 git repository URL
--branch string              git branch
--dockerfile string          path to the Dockerfile in the repo
--git-token string           token for private git repos
--docker-image string        docker image reference
--registry string            docker registry
--docker-user string         docker registry username
--docker-pass string         docker registry password
--plan string                app plan (required when creating)
--port int                   HTTP port (on create)
--public                     expose the app publicly (on create) (default true)
--replicas int               number of replicas (on create) (default 1)
--domain stringArray         custom domain (repeatable, on create)
--volume stringArray         mount a volume as name:mountPath (repeatable)
--env stringArray            environment variable as KEY=VALUE (repeatable, merges)
--env-file string            read environment variables from a .env file (merges)
--command string             override the container command (empty value restores the image default)
--health-check-path string   HTTP path for the readiness probe (empty value disables it)
--wa