Skip to main content

Command-line interface

hostim is the command-line client for Hostim.dev. It creates projects, deploys apps, manages databases, volumes and domains, reads logs and runs commands inside a container — everything the console does, from a terminal or a CI job.

The CLI is open source (MIT): github.com/hostimdev/cli. It is a thin client over the public REST API at https://api.hostim.dev, so anything the CLI does you can also do with an HTTP request. The full API reference is at api.hostim.dev/reference.

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.

Install​

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

The script downloads the release binary for your OS and architecture (Linux and macOS, amd64 and arm64) and installs it into /usr/local/bin. Set PREFIX to install somewhere else:

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

Windows binaries and checksums are attached to every release. You can also build from source with Go 1.26 or newer.

Check the install:

hostim --version

Log in​

Create an API token in the console under Account Settings → API Tokens, then:

hostim login                      # prompts for the token, input is hidden

The token is validated against the API and saved to ~/.config/hostim/config.yml with mode 0600. Most commands act on one project, so set a default once:

hostim projects ls
hostim use my-project

Deploy an app​

From a Git repository — the CLI waits for the build and exits non-zero if it fails:

hostim deploy web --git https://github.com/me/app --branch main --plan sa-1-1 --port 3000

From a Docker image:

hostim deploy web --docker-image nginx:alpine --plan sa-1-1 --port 80

hostim deploy creates the app if it does not exist and rebuilds it if it does, so the same command works for the first deploy and every one after it. Plan IDs come from hostim regions pricing eu-center.

An app that also needs a database, a Redis or a volume is deployed as a template instead. hostim templates apply --compose docker-compose.yml converts a Compose file, and hostim templates apply -f stack.yml creates every resource in order.

Deploy your app has the same commands filled in with real images, real repositories and real template IDs, ready to copy.

Everyday commands​

hostim status                             # build and runtime status of every app
hostim overview                           # all resources and their monthly cost
hostim logs web --follow                  # stream logs
hostim env set -a web DATABASE_URL=postgres://...
hostim env pull -a web                    # write the app's variables to .env
hostim domain add app.example.com -a web  # prints the DNS record to create
hostim db postgres create maindb --plan sp-1
hostim exec web -- rails c                # shell into the container

Every command takes -o json for scripting, and every write prints a single result object:

hostim status -o json | jq '.[].name'

In CI​

Skip hostim login and export the token instead — nothing is written to disk:

- name: Deploy
  env:
    HOSTIM_TOKEN: ${{ secrets.HOSTIM_TOKEN }}
    HOSTIM_PROJECT: my-project
  run: |
    curl -fsSL https://raw.githubusercontent.com/hostimdev/cli/main/install.sh | PREFIX=$HOME/.local sh
    $HOME/.local/bin/hostim deploy web --git https://github.com/me/app --branch main

For GitHub Actions specifically there is also a dedicated action that does not need the CLI installed.

The full manual​

This page is an introduction. The complete manual — every command, every flag, the JSON output contract, the environment variables and the exit codes — is the README of the CLI repository, and the binary carries the same text:

hostim agent

That prints the whole manual to stdout, for the version you actually have installed. It is meant to be piped into an AI coding assistant, or read with hostim agent | less.