Hostim

hostim CLI

用于 Hostim.dev 云平台的命令行界面。 通过终端或 CI 工作流，使用公共 REST API https://api.hostim.dev 创建和管理项目、应用、数据库（MySQL / Postgres / Redis）、卷和域名。

本文件是完整手册。二进制文件中也包含相同文本：运行 hostim agent 可将手册打印到标准输出，以便 Agent 或脚本在没有网络连接时读取完整手册。

命令、标志、输出和 API 响应可能会随版本发布而变化。升级前请查看 发行说明。

目录

• 安装
• 登录
• 配置
• 全局标志
• 输出和退出代码
• 命令参考
  • login、logout、whoami、use
  • projects
  • deploy
  • apps
  • status、logs、events、overview
  • env
  • domain
  • exec
  • db
  • volumes
  • backups
  • templates
  • regions
  • completion
  • agent
  • mcp
  • version
• 模板文件
• 从 CI 部署
• 报告问题
• 开发
• 许可证

安装

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

该脚本会下载适用于当前操作系统和架构（Linux 和 macOS，amd64 和 arm64）的发行版二进制文件，并将其安装到 /usr/local/bin；如果该目录不可写，则使用 sudo。如果该目录不可写且也未安装 sudo（例如纯容器环境），脚本会改为安装到 ~/.local/bin，并提示你该目录是否未加入 PATH。设置 PREFIX 可自行选择安装位置：

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

有些 Agent 和 CI 策略不允许将下载的脚本通过管道传给 shell。安装并不一定要用该脚本。你可以使用 Homebrew（macOS 和 Linux）：

brew install hostimdev/tap/hostim

也可以使用 npm（Node 18+）。首次运行时，npx 会下载适用于你平台的发行版二进制文件，根据发行版校验和进行验证，并将其缓存：

npx -y hostim version
npm install -g hostim   # or install it once and run `hostim`

或者直接获取发行版二进制文件：

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

也可以从源代码构建（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)

检查安装结果：

hostim version

登录

hostim login 使用设备代码。它会显示一个 URL 和一段简短代码，你在浏览器中批准请求后，令牌就会自动保存：

hostim login

hostim login 会持续轮询，直到你批准请求，并自行保存令牌，因此无需为它编写等待循环，也不必再次运行。浏览器步骤不需要终端，因此 Agent 可以运行 hostim login 并向你显示代码。如果你已有令牌，也可以直接保存令牌；请在控制面板中创建令牌：https://console.hostim.dev

hostim login --token-value "$T"   # non-interactive, for scripts and CI

login 会先使用 API 验证令牌，然后再将其保存到 ~/.config/hostim/config.yml（权限模式为 0600）。在 CI 中，请跳过 login，改为导出 HOSTIM_TOKEN，这样不会写入文件。

大多数命令都针对一个项目操作。设置一次默认项目即可：

hostim projects ls
hostim use my-project
hostim whoami                     # token source, current project, project count

配置

值的解析顺序为标志 → 环境变量 → 配置文件；API URL 另有内置默认值。

值	标志	环境变量	配置键
API 令牌	--token	HOSTIM_TOKEN	token
API 基础 URL	--api-url	HOSTIM_API_URL	apiUrl（默认 https://api.hostim.dev）
目标项目	-p、--project	HOSTIM_PROJECT	currentProject，由 hostim use 设置

配置文件位于 ~/.config/hostim/config.yml；如果设置了 XDG_CONFIG_HOME，则位于 $XDG_CONFIG_HOME/hostim/config.yml：

token: ...                 # written by `hostim login`
currentProject: my-project # written by `hostim use`
apiUrl: https://api.hostim.dev  # only written when --api-url was passed

所有地方都可以用名称或 ID 指定项目和应用。

全局标志

所有命令均可使用：

--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)

破坏性命令（rm、templates apply）会要求确认，并可使用 -y / --yes 跳过提示。

输出和退出代码

默认输出为面向人类的对齐文本表格。-o json 会将所有命令切换为机器可读输出，适用于脚本和 Agent：

• 读取命令以缩进 JSON 格式打印 API 对象或列表；
• 写入命令会打印一个结果对象，说明执行的操作，例如 {"status":"created","kind":"app","name":"web"} 或 {"status":"ok","kind":"env","set":1}；
• 失败时会在 stderr 上打印 JSON 对象，例如 {"status":"error","error":"..."}，并以非零状态码退出。如果命令缺少多项要求，对象会包含一个 "missing" 数组，一次性列出所有缺少的项。

退出代码：

代码	含义
0	成功
1	CLI 或 API 错误，或确认操作已中止
其他	hostim exec 会传递远程命令的退出状态

命令参考

设置好令牌和项目后，以下示例均可直接运行。

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；可选值请参见 hostim regions ls。

projects export 会写入期望状态模板，而不是备份：不会导出卷和数据库中的内容（数据）。这些数据无论如何都会按计划备份：Postgres 和 MySQL 数据库以及卷，参见 备份（hostim backups）。费用、ID、内置域名和未使用的源代码块会被移除，环境变量的值会以原始格式导出——文件中包含机密信息（密码、API 密钥），因此请像保管密码文件一样存储和共享该文件。Docker 注册表密码和 git 令牌无法通过 API 读取，因此不会导出（注册表用户名会保留）；应用后请重新设置。 使用 hostim templates apply -f prod.yml --new-project prod-clone 重新部署。

deploy

hostim deploy <app> 会在应用不存在时创建应用（使用 --git 或 --docker-image），否则会更新其来源并触发重新构建。该命令会等待构建完成，构建失败时以非零状态码退出，因此可直接用于流水线。hostim apps deploy 是同一命令。

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

标志：

--git string                 git repository URL
--branch string              git branch
--dockerfile string          path to the Dockerfile in the repo; 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)

计划 ID 按资源类型区分，格式类似 sa-1-1（共享应用、1 核心、1 GB RAM）。使用 hostim regions pricing <region> --for apps 查看某个区域提供的计划。

deploy 处理单个应用。需要同时使用数据库、Redis 或卷的应用应作为模板部署——参见模板。

apps

hostim apps ls                    # aliases: app; ls | list; `hostim apps` alone does the same
hostim apps get web
hostim apps status                # health table for every app in the project
hostim apps status web
hostim apps rebuild web           # rebuild from the current source
hostim apps restart web           # restart the running containers
hostim apps rm web -y             # aliases: delete, remove

status, logs, events, overview

hostim status                          # every app in the project
hostim status web                      # one app: build + runtime status
hostim status -o json

hostim logs web                        # last 100 lines, oldest first
hostim logs web -f                     # stream new lines
hostim logs web -n 500                 # 1-10000 lines
hostim logs web --since 2h             # every line of the last 2 hours (up to 10000)
hostim logs web --since 2026-10-14T14:00 --until 2026-10-14T14:10   # one time window
hostim logs web --since 1h | grep -i error   # search
hostim logs web --build --since 1h     # build logs (git-built apps only)

# Logs cover stdout and stderr of every container the app ran in the last
# 7 days, so lines from before a redeploy or a crash are still there.

hostim events web                      # status history: why the app changed state
hostim events web -f                   # keep printing new events
hostim events web -n 20

hostim overview                        # every resource in every project + cost
hostim overview my-project             # alias: resources

status 显示当前值；events 显示该值的变化过程。当应用状态变得不健康又恢复时，可在此查看原因。--build 适用于从 git 构建的应用；运行预构建 docker 镜像的应用没有构建日志。

env

环境变量可以属于单个应用（-a/--app），也可以属于整个项目（--global）。应用可读取全局变量以及自身的变量。

hostim env get -a web
hostim env get --global -o json
hostim env set KEY=VALUE OTHER=2 -a web       # merges with existing vars
hostim env set SENTRY_DSN=... --global
hostim env rm KEY OTHER -a web
hostim env pull -a web --file .env            # write to a file (- for stdout)
hostim env push -a web --file .env            # load from a file, merging
hostim env push -a web --file .env --replace  # replace the whole set

更改环境变量会重启应用。

要访问同一项目中的其他应用，请在其 HTTP 端口上使用内部 DNS 名称 app-<name>-service，例如 API_URL=http://app-api-service:8080。hostim status <app> 会将其显示为“内部 DNS”。没有 HTTP 端口的应用不会有此项。

值可以使用 $(...) 引用数据库变量，也可以在较长的值（例如 DSN）中使用。这些变量会在容器启动时展开，因此 hostim env get 会显示原始文本。所有变量名称请参见envVars 中的占位符。

hostim env set -a web \
  'DATABASE_URL=mysql://$(MAIN_MYSQL_USER):$(MAIN_MYSQL_PASSWORD)@$(MAIN_MYSQL_HOST):$(MAIN_MYSQL_PORT)/$(MAIN_MYSQL_DATABASE)'

domain

hostim domain add app.example.com -a web    # prints the DNS record to create
hostim domain status web                    # domains + DNS/certificate state
hostim domain rm app.example.com -a web -y

在 DNS 提供商处添加打印出的记录，然后重新运行 hostim domain status，直到显示域名已激活；系统会自动签发证书。

exec

在应用的容器中运行命令；如果未提供命令，则打开交互式 shell。连接通过项目的 SSH 堡垒机进行，因此项目必须授权你的 SSH 公钥。首次对项目运行 hostim exec 时，系统会提示你添加密钥；传入 -y 可跳过提示并直接添加，适用于脚本或 CI 作业。

hostim exec web                                   # interactive shell
hostim exec web -- rails c                        # one-off command
hostim exec web -- sh -c 'ls -la /var/www | head'
hostim exec web -- cat /tmp/app.log               # read a file the app does not log
cat dump.sql | hostim exec --stdin db -- psql app # pipe local data in
hostim exec web -i ~/.ssh/id_ed25519 -- env       # pick the SSH key
hostim exec -y web -- ./migrate.sh                 # no prompts, for CI

别名：shell、ssh。远程命令的退出状态会成为 hostim exec 的退出状态。

db

三种引擎，命令格式相同：hostim db mysql|postgres|redis ls|get|create|credentials|status|rm。pg 是 postgres 的别名。

hostim db postgres ls
hostim db postgres create main --plan sp-1
hostim db postgres get main
hostim db postgres status main
hostim db postgres credentials main -o json   # hostname, port, username, password, database
hostim db postgres rm main -y

hostim db mysql ls
hostim db mysql create app --plan sm-1
hostim db mysql get app
hostim db mysql status app
hostim db mysql credentials app -o json
hostim db mysql rm app -y

hostim db redis ls
hostim db redis create cache --plan sr-1
hostim db redis get cache
hostim db redis status cache
hostim db redis credentials cache -o json
hostim db redis rm cache -y

创建时必须提供 --plan。各引擎的计划 ID 不同——Postgres 使用 sp-*，MySQL 使用 sm-*，Redis 使用 sr-*——hostim regions pricing <region> --for postgres|mysql|redis 会列出这些计划及其存储空间和价格。

Postgres 扩展：

hostim db postgres extensions ls              # what a database can request (alias: ext)
hostim db postgres extensions add main postgis pg_trgm

加载纯 SQL 转储（pg_dump --format=plain）。数据会通过项目的 SSH 堡垒机导入 psql。SQL 错误会被打印并计数，但不会中止导入，因为来自其他主机的转储可能带有一些无害错误（事件触发器、扩展所有者、未知设置）。只有当 psql 完全无法运行转储时（例如无法连接），命令才会以非零状态退出。与 exec 一样，系统会提示你授权 SSH 密钥；传入 -y 可跳过提示并直接添加。

hostim db postgres import main -f dump.sql
hostim db postgres import main -y < dump.sql

一步将凭据读入应用的环境变量：

hostim db postgres credentials main -o json \
  | jq -r '"DATABASE_URL=postgres://\(.username):\(.password)@\(.hostname):\(.port)/\(.database)"' \
  | xargs hostim env set -a web

volumes

hostim volumes ls                                   # aliases: volume, vol
hostim volumes get data
hostim volumes create data --plan vol-1
hostim volumes rm data -y

计划决定大小（vol-1 为 5 GB）；使用 hostim regions pricing <region> --for volume 列出计划。

使用 hostim deploy <app> --volume data:/var/lib/app 将卷挂载到应用上。

backups

hostim backups                        # schedule, retention and last backup per resource
hostim backups create                 # start a manual backup of the whole project
hostim backups create data --wait     # back up one resource and wait for it to finish
hostim backups ls data                # the backups of one database or volume, newest first
hostim backups ls main --kind postgres   # skip the kind lookup
hostim backups download 1a2b3c4d               # prepare, then download
hostim backups download --latest data          # the newest backup of one resource
hostim backups download 1a2b3c4d -f -           # write to stdout (no resume)

hostim backups 会列出每个数据库和卷最近一次备份的时间，然后显示备份计划和保留策略。时间使用你的本地时区。hostim backups create 会启动手动备份；如果未指定资源，则备份整个项目。--wait 会轮询直至任务完成，如果未成功则以非零状态退出。hostim backups ls 显示压缩前的数据大小； 下载的文件会更小。hostim backups ls 需要资源名称；如果数据库和卷同名，请传入 --kind postgres|mysql|volume。hostim backups download --latest <resource> 会跳过 ID 查询，直接获取最新备份。hostim backups download 会先准备文件，大型备份可能需要几分钟，然后再下载。如果传输中断，重新运行相同命令即可：它会从磁盘上的部分文件 <file>.part 继续传输。-f - 会将内容写入标准输出，且无法续传。

下载内容使用 zstd 压缩。数据库备份是 .sql.zst 文件（使用 zstd -d <file> 解压），卷备份是 .tar.zst 归档（使用 tar --zstd -xf <file> 解压；内容会解压到以卷名称命名的文件夹中）。

templates

模板是一个描述整个技术栈的 YAML 文件，包含卷、数据库、Redis 和应用；apply 会按依赖顺序创建这些资源，并逐个等待资源就绪。

hostim templates ls                        # curated templates (aliases: template, tpl)
hostim templates show freshrss

# deploy a curated template into the current project
hostim templates apply --id freshrss

# deploy into a brand new project
hostim templates apply --id freshrss --new-project blog --region eu-center

# save it as YAML, edit, then deploy the edited file
hostim templates apply --id freshrss --save stack.yml
hostim templates validate -f stack.yml     # offline check, no API calls
hostim templates apply -f stack.yml -y

# convert a docker-compose file into a template
hostim templates apply --compose docker-compose.yml --save stack.yml
hostim templates apply --compose docker-compose.yml

# a file holding a list of templates: pick one entry
hostim templates apply -f templates.yml --id freshrss

apply 会打印将要创建的资源并请求确认（-y 可跳过确认）。如果目标项目中已有任何资源，命令会在创建任何内容之前中止，因此不会覆盖已配置或已扩容的资源；--skip-existing 则只创建缺少的资源。

模板中的自定义域名只会在所有资源就绪后绑定：如果某个域名已由其他项目持有（例如导出模板的项目），命令会逐个报告此类域名，但其余资源仍会成功应用——之后可使用 hostim domain add <domain> --app <app> 添加该域名。

apply 的标志：

--id string                curated template ID, or the entry to pick out of a -f list
-f, --file string          local template YAML file to deploy
--compose string           docker-compose file to convert and deploy
--save string              write the resolved template to a YAML file instead of deploying
--new-project string       create a new project with this name before deploying
--region string            region for --new-project (defaults to the only region when there is one)
--skip-existing            skip resources that already exist instead of aborting
--wait                     wait for each resource to become ready (default true)
--timeout duration         max time to wait per resource (default 15m0s)
--poll-interval duration   status poll interval (default 3s)
-y, --yes                  skip the confirmation prompt

regions

hostim regions ls                                  # aliases: region
hostim regions get eu-center
hostim regions pricing eu-center                   # app plans (default)
hostim regions pricing eu-center --for postgres    # apps, mysql, postgres, redis, volume

创建资源前，可使用此命令查找有效的 --plan 和 --region 值。

completion

hostim completion bash > /etc/bash_completion.d/hostim
hostim completion zsh > "${fpath[1]}/_hostim"
hostim completion fish > ~/.config/fish/completions/hostim.fish
hostim completion powershell | Out-String | Invoke-Expression

agent

hostim agent            # print this manual to stdout
hostim agent > CLI.md

二进制文件内嵌了此 README，因此 Agent 读取的手册与已安装版本随附的手册完全一致。在编写 Hostim 命令前，将其提供给编码 Agent，它就不会再猜测标志。

对于会加载技能的 Agent（Claude Code 等），同样的知识也以技能形式提供：skills/hostim/SKILL.md。将它放到仓库中的 .claude/skills/hostim/SKILL.md，或让安装程序代为处理：

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

这会安装 CLI、写入技能，并让 AGENTS.md 指向它。

mcp

hostim mcp                      # Model Context Protocol server on stdio, read-only
hostim mcp --allow-write        # also expose tools that create, change and delete

hostim mcp 通过 stdin/stdout 使用 Model Context Protocol，因此编码 Agent 可以将 Hostim 资源作为工具进行检查和配置。它与其他所有命令使用相同的二进制文件、令牌和公共 API。

只读工具始终可用：list_projects、list_apps、get_app、get_app_status、get_app_logs、get_app_events、list_databases、get_database_credentials、list_volumes、list_backups、list_regions、list_templates 和 list_region_plans。只有使用 --allow-write 才会注册用于创建、更改或删除内容的工具，包括项目、应用、数据库、卷、环境变量、域名、备份和备份下载。

将 MCP 客户端指向它。对于 Claude Desktop，在 claude_desktop_config.json 中配置：

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

Cursor、VS Code 和其他 MCP 客户端使用相同的 command + args 格式。

Claude Desktop 也可以不通过 CLI 直接安装：从最新版本下载 hostim.mcpb 并打开。Claude Desktop 会询问令牌以及是否允许更改。 令牌与其他所有命令的令牌来自同一处，因此也可以省略 env，改用 hostim login 保存的令牌。

version

hostim version          # hostim version v1.2.3
hostim --version        # same thing

模板文件

模板文件可以是单个模板对象，也可以是模板对象列表。字段名称与 API 的 JSON（camelCase）一致。最简示例：

id: my-stack
name: My stack
description: A web app with a Postgres database and a volume
components:
  volumes:
    - name: data
      plan: vol-1
  postgres:
    - name: main
      plan: sp-1
  mysql: []
  redis: []
  apps:
    - name: web
      plan: sa-1-1
      public: true
      replicas: 1
      httpPort: 8080
      healthCheckPath: /healthz
      domains: []
      deploymentSource:
        type: docker
        docker:
          image: ghcr.io/me/app:latest
      envVars:
        - name: LOG_LEVEL
          value: info
      volumeMounts:
        - name: data
          mountPath: /var/lib/app

基于 Git 的应用使用以下来源：

      deploymentSource:
        type: git
        git:
          url: https://github.com/me/app
          branch: main
          dockerfilepath: Dockerfile

hostim templates validate -f <file> 会在创建任何资源前离线检查名称、计划和部署来源。

envVars 中的占位符

有两种占位符会自动解析，因此模板无需包含主机名或手写的密钥。

应用模板时，GENERATE_ME_<n> 会替换为一个包含 <n> 个字符的新随机密钥。它由 CLI 展开，因此传给 API 的值已经是真正的密钥：

      envVars:
        - name: APP_SECRET
          value: GENERATE_ME_32

$(NAME) 引用容器中存在的另一个变量。这些变量会在容器启动时展开，而不是由 CLI 展开，因此 hostim env get 仍会显示字面文本 $(...)——这是预期行为，应用会看到解析后的值：

• $(BUILTIN_DOMAIN) — 应用内置的主机名，不含 scheme (myapp-abc123.hostim.app)。
• $(GIT_COMMIT) 和 $(GIT_COMMIT_SHORT) — 运行中镜像的构建来源提交的完整 SHA 和 7 个字符的 SHA。仅适用于 Git 应用；hostim status 会显示短 SHA。
• 同一项目中的托管数据库会发布连接变量。变量前缀为数据库名称，转换为大写，并将 - 替换为 _。名为 main 的 Postgres 会提供 $(MAIN_POSTGRES_HOST)、$(MAIN_POSTGRES_PORT)、$(MAIN_POSTGRES_DATABASE)、$(MAIN_POSTGRES_USER)、$(MAIN_POSTGRES_PASSWORD)。MySQL 使用 _MYSQL_，字段相同；Redis 使用 $(<NAME>_REDIS_HOST)、$(<NAME>_REDIS_PORT)、$(<NAME>_REDIS_DB) 和 $(<NAME>_REDIS_PASSWORD)。

  postgres:
    - name: main
      plan: sp-1
  apps:
    - name: web
      envVars:
        - name: DATABASE_URL
          value: postgresql://$(MAIN_POSTGRES_USER):$(MAIN_POSTGRES_PASSWORD)@$(MAIN_POSTGRES_HOST):$(MAIN_POSTGRES_PORT)/$(MAIN_POSTGRES_DATABASE)
        - name: BASE_URL
          value: https://$(BUILTIN_DOMAIN)
        - name: SESSION_SECRET
          value: GENERATE_ME_32

从 CI 部署

GitHub Actions：

- name: Deploy
  env:
    HOSTIM_TOKEN: ${{ secrets.HOSTIM_TOKEN }}
    HOSTIM_PROJECT: my-project
  run: |
    curl -fsSL https://raw.githubusercontent.com/hostimdev/cli/main/install.sh | sh
    hostim deploy web \
      --docker-image ghcr.io/${{ github.repository }}:${{ github.sha }} \
      --plan sa-1-1 --port 8080 -o json

构建失败时，此步骤也会失败，因为 deploy 会等待并以非零状态码退出。 此外，还有一个现成的 GitHub Action：https://github.com/hostimdev/action。

其他 CI 也采用相同方式：导出 HOSTIM_TOKEN 和 HOSTIM_PROJECT，安装二进制文件，然后使用 -o json 运行 hostim deploy。

报告问题

如果 Hostim 工具、CLI 命令或 API 调用返回了错误或令人困惑的结果，而这并非由你输入的内容导致，请告知用户并提出报告问题。首选方式：在 GitHub 上提交 Issue，网址为 https://github.com/hostimdev/cli/issues。先起草标题和正文并展示给用户，只有在用户同意后，才使用 gh issue create 创建 Issue。用户也可以在控制台中联系支持聊天（https://console.hostim.dev），或发送邮件至 [email protected]。请注明你调用的工具或命令、返回的内容以及预期结果。不要包含机密信息和环境变量值。

开发

API 客户端（api/client.gen.go）根据 实时 公共规范生成，规范地址为 https://api.hostim.dev/openapi.public.json，且不会随代码库一同提供：

make generate    # curl live spec → oapi-codegen → api/client.gen.go
make build
make test
make lint

CI（.github/workflows/generate.yml）会针对实时 API 重新运行 make generate，如果 api/client.gen.go 存在偏差则会失败，以确保已提交的客户端与已部署的 API 保持同步。

此 README 是 CLI 文档的唯一来源：它会嵌入二进制文件，并由 hostim agent 打印。请只在此处编辑，不要在其他地方编辑。

许可证

MIT。请参阅 LICENSE。