hoster-cli

Vercel-like deploy CLI for hoster.kz / topgrant.kz infrastructure.

| | | |---|---| | Control plane (API + web) | https://deploy.topgrant.kz | | Deployed apps | https://*.apps.topgrant.kz | | npm package | hoster-cli | | Binary | hoster | | Node.js | ≥ 22 |

TEST / MVP — do not use in production. Quotas, billing, and runtime support may change. Data and uptime are not guaranteed.

Works on Windows, macOS, and Linux (also WSL / Git Bash). The hoster bin uses a portable Node shebang (#!/usr/bin/env node).

What it is (for humans & LLMs)

Purpose: Deploy a local app (Node, static, Docker, etc.) to Hoster’s single-VDS PaaS with a short CLI flow: login → init → deploy — DX like Netlify / Railway / Vercel, apps on hoster.kz / topgrant.kz infra (KZ servers, KZT billing).

Constraints (MVP):

• Free plan: 1 project; Starter unlocks more (see billing link in CLI).
• Not production-ready; expect breaking changes.
• CLI validation is UX only; the Laravel API re-validates everything.
• Secrets stay local (keytar or ~/.hoster/config.json); never commit tokens.

Typical layout after hoster init:

| Path | Role | |------|------| | hoster.yaml | Runtime config (safe to commit) | | .hoster/project.json | Local binding to project_id + API URL | | .hosterignore | Extra archive excludes (optional) |

Security notes: Prefer OS keychain; file config uses restrictive permissions when possible. Do not put npm tokens or API tokens in repo files. Device login: code/link in terminal, password only in the browser.

Install

Windows (PowerShell)

# Node 22+ required: node -v
npm install -g hoster-cli
hoster --version

If npm is blocked by PowerShell execution policy, use:

npm.cmd install -g hoster-cli

macOS / Linux

# Node 22+ required: node -v
npm install -g hoster-cli
hoster --version

WSL / Git Bash

Same as Linux (npm install -g hoster-cli). Prefer WSL’s own Node 22+, not a Windows hoster.cmd mixed into a Linux PATH.

From this monorepo (developers)

cd apps/cli
npm install
npm run build
npm link          # or: npm link --ignore-scripts if prepare fails
hoster --version

Fallback without a global link:

node bin/hoster.js --help

Quickstart

hoster login          # open link + enter code in browser
hoster whoami         # shows plan / quota banner

cd /path/to/your-app
hoster init           # creates hoster.yaml + .hoster/
hoster deploy --follow

Production URL: https://<slug>-<shortid>.apps.topgrant.kz.
Each deploy also gets a preview host (immutable until cleanup).

GitHub auto-deploy:

hoster webhook setup --repo https://github.com/OWNER/REPO
# paste Payload URL + Secret into GitHub → Settings → Webhooks (push)

Upgrade / payment (when free limit is hit): https://deploy.topgrant.kz/billing

Common install errors

| Error / symptom | OS | Fix | |-----------------|----|-----| | EEXIST: file already exists … hoster.cmd (or hoster / hoster.ps1) | Windows | Old global/link left behind. Clean then reinstall: npm unlink -g hoster-cli; remove %APPDATA%\npm\hoster*; npm.cmd install -g hoster-cli | | npm.ps1 cannot be loaded because running scripts is disabled | Windows | Use npm.cmd … or relax execution policy for current user; or install via cmd.exe | | engine … node … not satisfied / odd runtime errors | All | Install Node.js 22+ (node -v). LTS below 22 is unsupported | | hoster: command not found / not recognized | All | Ensure npm global bin is on PATH (Windows: %APPDATA%\npm; macOS/Linux: npm prefix -g/bin). Restart the shell | | EACCES / permission denied on global install | macOS/Linux | Prefer a Node version manager (nvm/fnm) over sudo npm. Or use a user prefix: npm config set prefix ~/.npm-global | | glob / peer dependency warnings during install | All | Usually harmless for this package; ignore unless install fails. Package pins glob via overrides | | keytar optional peer missing / native build fail | All | Optional. CLI falls back to ~/.hoster/config.json | | prepare / tsc fails on npm link | Dev | npm run build then npm link --ignore-scripts | | Mixing WSL + Windows npm globals | WSL | Install Node + hoster-cli inside WSL only |

Deeper docs

| Doc | Contents | |-----|----------| | Getting started | Plain steps to deploy your own project | | CLI reference | Commands, auth, publish notes | | Tech stack | Whole monorepo technologies | | Architecture | Control plane, agent, Docker | | Security | Trust boundaries |

When reading from npm only (no monorepo clone), use the GitHub/docs site for the same paths under docs/.

Useful commands

hoster status
hoster logs --follow
hoster projects
hoster domains list | add | verify
hoster webhook setup
hoster env list
hoster env set KEY value
hoster restart | stop | start
hoster rollback
hoster destroy

API override: HOSTER_API_URL or --api <url> (default https://deploy.topgrant.kz).