The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Hostim listing page.
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.
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:
Some agents and CI policies refuse to pipe a downloaded script into a shell. The script is not required — fetch the release binary directly:
Build from source instead (Go 1.26+):
Check the install:
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 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:
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:
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:
Projects and apps can be named by name or by ID everywhere.
Available on every command:
Destructive commands (rm, templates apply) ask for confirmation and take
-y / --yes to skip the prompt.
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:
{"status":"created","kind":"app","name":"web"} or
{"status":"ok","kind":"env","set":1};{"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 |
Every example below is runnable as written once a token and a project are set.
--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.
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.
Flags:
Plan IDs are per resource kind and look like sa-1-1 (shared app, 1 core, 1 GB
RAM). List the ones a region offers with hostim regions pricing <region> --for apps.
deploy handles one app. An app that also needs a database, a Redis or a
volume is deployed as a template — see templates.
status shows the current value; events shows how it got there, which is
where to look when an app went unhealthy and came back. --build works for apps
built from git; an app that runs a prebuilt docker image has no build logs.
Environment variables belong either to one app (-a/--app) or to the whole
project (--global). Apps see the global set plus their own.
Changing environment variables restarts the app.
Add the printed record at the DNS provider, then re-run hostim domain status
until it reports the domain as active; the certificate is issued automatically.
Runs a command inside an app's container, or opens an interactive shell when no
command is given. The connection goes through the project's SSH bastion, so the
project has to authorize your public SSH key. The first hostim exec against a
project offers to add the key for you; pass -y to add it without the prompt,
which is what a script or a CI job needs.
Aliases: shell, ssh. The exit status of the remote command becomes the exit
status of hostim exec.
Three engines, the same command shape: hostim db mysql|postgres|redis ls|get|create|credentials|status|rm. pg is an alias for postgres.
--plan is required on create. Plan IDs differ per engine — sp-* for
Postgres, sm-* for MySQL, sr-* for Redis — and hostim regions pricing <region> --for postgres|mysql|redis lists them with their storage and price.
Postgres extensions:
Load a plain-SQL dump (pg_dump --format=plain). It goes through the project's
SSH bastion into psql. SQL errors are printed and counted but do not stop the
import, because dumps from other hosts carry a few harmless ones (event
triggers, extension owners, unknown settings). It exits non-zero only when psql
cannot run the dump at all, for example when it cannot connect. Like exec, it
offers to authorize your SSH key; -y adds it without asking.
Read the credentials into an app's environment in one step:
The plan sets the size (vol-1 is 5 GB); list plans with hostim regions pricing <region> --for volume.
Mount a volume on an app with hostim deploy <app> --volume data:/var/lib/app.
A template is one YAML description of a whole stack — volumes, databases, Redis
and apps — that apply creates in dependency order, waiting for each resource.
apply prints the resources it will create and asks for confirmation
(-y skips it). If any resource already exists in the target project it aborts
before creating anything, so it never overwrites a configured or scaled
resource; --skip-existing creates only what is missing.
Custom domains from the template are attached only after all resources are up:
a domain already held by another project (for example the project a template
was exported from) is reported per-domain and the rest of the apply still
succeeds — add it later with hostim domain add <domain> --app <app>.
Flags for apply:
Use this to find valid --plan and --region values before creating anything.
The binary embeds this README, so the manual an agent reads is exactly the manual shipped with the installed version. Feed it to a coding agent before it writes Hostim commands, and the agent stops guessing flags.
For agents that load skills (Claude Code and others), the same knowledge ships
as a skill: skills/hostim/SKILL.md. Put it at
.claude/skills/hostim/SKILL.md in your repository, or let the installer do it:
That installs the CLI, writes the skill and points AGENTS.md at it.
hostim mcp speaks the Model Context Protocol on stdin/stdout, so a coding
agent can inspect and provision Hostim resources as tools. It is the same
binary, the same token and the same public API as every other command.
Read-only tools are always available: list_projects, list_apps, get_app,
get_app_status, get_app_logs, get_app_events, list_databases,
get_database_credentials, list_volumes, list_regions, list_templates
and list_region_plans. Tools that create, change or delete anything —
projects, apps, databases, volumes, env vars and domains — are only registered
with --allow-write.
Point an MCP client at it. For Claude Desktop, in
claude_desktop_config.json:
Cursor, VS Code and other MCP clients use the same command + args shape.
Claude Desktop can also install it without the CLI: download
hostim.mcpb
from the latest release and open it. Claude Desktop asks for the token and
whether to allow changes.
Because the token comes from the same place as every other command, you can
also leave env out and rely on hostim login's saved token.
A template file is either one template object or a list of them. Field names match the API's JSON (camelCase). Minimal example:
A git-based app uses this source instead:
hostim templates validate -f <file> checks names, plans and deployment
sources offline, before any resource is created.
Two kinds of placeholder are resolved for you, so a template never has to carry a hostname or a hand-written secret.
GENERATE_ME_<n> is replaced by a fresh random secret of <n> characters when
the template is applied. It is expanded by the CLI, so the value that reaches
the API is already the real secret:
$(NAME) references another variable present in the container. These are
expanded at container start, not by the CLI, so hostim env get still shows the
literal $(...) text — that is expected, and the app sees the resolved value:
$(BUILTIN_DOMAIN) — the app's built-in hostname, without a scheme
(myapp-abc123.hostim.app).$(GIT_COMMIT) and $(GIT_COMMIT_SHORT) — the full and 7-character SHA of the
commit the running image was built from. Git apps only; hostim status shows
the short one.- turned into _. A Postgres
named main gives $(MAIN_POSTGRES_HOST), $(MAIN_POSTGRES_PORT),
$(MAIN_POSTGRES_DATABASE), $(MAIN_POSTGRES_USER),
$(MAIN_POSTGRES_PASSWORD). MySQL uses _MYSQL_ with the same five fields;
Redis uses $(<NAME>_REDIS_HOST), $(<NAME>_REDIS_PORT),
$(<NAME>_REDIS_DB) and $(<NAME>_REDIS_PASSWORD).GitHub Actions:
The step fails when the build fails, because deploy waits and exits non-zero.
There is also a ready-made GitHub Action at
https://github.com/hostimdev/action.
Any other CI works the same way: export HOSTIM_TOKEN and HOSTIM_PROJECT,
install the binary, run hostim deploy with -o json.
The API client (api/client.gen.go) is generated from the live public spec
at https://api.hostim.dev/openapi.public.json — the spec is not vendored:
CI (.github/workflows/generate.yml) re-runs make generate against the live
API and fails if api/client.gen.go has drifted, keeping the committed client
in sync with the deployed API.
This README is the single source for the CLI documentation: it is embedded in
the binary and printed by hostim agent. Edit it here, nowhere else.
MIT. See LICENSE.