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, with sudo if that needs root. In a container with neither write access nor sudo it falls back to ~/.local/bin and prints a PATH hint. 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

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​

hostim login

The command prints a short code and a URL. Open the URL, log in, and approve the code. hostim login keeps polling until you approve and stores the token itself, so there is no need to wrap it in a waiting loop or run it again. The browser step needs no terminal, so an AI agent can run hostim login and show you the code.

To use a token you already have, create one in the console under Account Settings → API Tokens and store it directly:

hostim login --token-value "$TOKEN"

Either way 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.

Use it from an AI agent (MCP)​

The CLI is also an MCP server. hostim mcp speaks the Model Context Protocol on stdin/stdout, so Claude Desktop, Cursor, VS Code and other MCP clients can read and change your Hostim resources with tools instead of shell commands.

Read tools are on by default: list projects, apps, databases and volumes, read status, logs and events, and list regions, plans and templates. Tools that create, change or delete anything need --allow-write, so an agent cannot spend money by accident:

hostim mcp                 # read-only
hostim mcp --allow-write   # read and write

Point your MCP client at the command. For Claude Desktop, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "hostim": {
      "command": "hostim",
      "args": ["mcp", "--allow-write"],
      "env": { "HOSTIM_TOKEN": "your-api-token" }
    }
  }
}

Cursor and other clients use the same command, args and env shape. You can leave env out if you already ran hostim login — the server uses the token from your config, the same as every other command.

Give an agent the instructions​

MCP is for clients that speak it. For a coding agent that reads your repository instead, there is a skill and a paste-into-AGENTS.md block:

curl -fsSL https://hostim.dev/agent.sh | sh

That installs the CLI, writes the Hostim skill to .claude/skills/hostim/SKILL.md, and points AGENTS.md at it. Both are also on hostim.dev/agents, which is written for the agent reading it rather than the human.

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. Without the CLI installed, the same manual is on the web at hostim.dev/cli-manual.md.

The manual is also where the template placeholders are documented: GENERATE_ME_32 for a generated secret, $(BUILTIN_DOMAIN) for the app's own hostname, and $(MAIN_POSTGRES_HOST)-style references to a managed database named main.