Hostim

hostim CLI

Command-line interface for the 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.

An app can deploy from a local directory (uploaded and built from its Dockerfile, or served as a static site), a git repository, or a Docker image. A local directory needs no git remote and no registry: hostim deploy web --source . --plan sa-1-1 --port 8080. See deploy.

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.

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
• backups
• templates
• regions
• completion
• agent
• mcp
• version
• Template files
• Deploy from CI
• Reporting problems
• 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. Use Homebrew (macOS and Linux):

brew install hostimdev/tap/hostim

Or npm (Node 18+). npx downloads the release binary for your platform on the first run, checks it against the release checksums and caches it:

npx -y hostim version

npm install -g hostim # or install it once and run hostim

Or 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. That data is backed up on a schedule anyway: Postgres and MySQL databases and volumes, see backups (hostim backups). 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 creates the app when it does not exist (from --source, --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

deploy a local directory: it is uploaded and built with its Dockerfile

hostim deploy web --source . --plan sa-1-1 --port 8080

deploy a built static site (index.html, no Dockerfile): nginx on port 80

npm run build && hostim deploy site --source dist --plan sa-1-1

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: the registry host goes inside the image reference

hostim deploy web --docker-image registry.example.com/me/app:1.2.3 \ --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:

--source string              deploy a local directory: it is uploaded and built with its Dockerfile

--static serve --source as a static site with nginx (automatic when it has an index.html and no Dockerfile) --git string git repository URL --branch string git branch --dockerfile string path to the Dockerfile in the repo or source dir; its directory is the build context --git-token string token for private git repos --docker-image string docker image reference, registry host included --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; required unless --public=false) --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) --wait wait for the build to finish (default true) --timeout duration max time to wait for the build (default 15m0s) --poll-interval duration status poll interval (default 3s)

With --source . the directory is packed into a .tar.gz and uploaded before the build. These paths are always left out: .git/, node_modules/ (at any depth), .env and .env.* files (except .env.example, .env.sample and .env.template). A .dockerignore at the directory root is applied too; the Dockerfile and .dockerignore are always kept. Symlinked directories are not followed, and a symlink is skipped w