@rhost-rw/cli
v0.3.0
Published
RHost from your terminal: deploy, tail logs, manage env vars, databases and DNS — plus an MCP server that gives AI agents the same abilities.
Readme
RHost CLI
Deploy, tail logs and manage apps, databases and DNS from a terminal — and, through the same package, let an AI agent do the same over MCP.
npm install -g @rhost-rw/cli
rhost login
cd my-app && rhost link
rhost deployRequires Node 20.11 or newer. The package has no runtime dependencies.
rhost help lists every command; rhost help <command> prints one in full,
with its flags and worked examples; rhost <command> --help is the same page.
rhost help install, rhost help ci and rhost help mcp-setup cover the rest.
Installing
It runs anywhere Node 20.11+ runs — macOS, Linux, Windows, WSL and containers.
Without installing anything. What CI should use, and the quickest way to try it:
npx -y @rhost-rw/cli deploy # npm
pnpm dlx @rhost-rw/cli deploy # pnpm
bunx @rhost-rw/cli deploy # bunInstalled for good, with whichever package manager you already use:
npm install -g @rhost-rw/cli
pnpm add -g @rhost-rw/cli
yarn global add @rhost-rw/cli
bun add -g @rhost-rw/cli
rhost --versionIf you do not have Node yet:
| Platform | Getting Node 20.11+ |
|---|---|
| macOS | brew install node, or nvm install --lts |
| Ubuntu / Debian | nvm install --lts — the packaged nodejs is often too old |
| Fedora / RHEL | sudo dnf install nodejs |
| Arch | sudo pacman -S nodejs npm |
| Windows | winget install OpenJS.NodeJS.LTS, or choco install nodejs-lts |
| WSL | Follow the Linux row — a Windows install is not on the PATH inside WSL |
| Docker / CI | FROM node:20-alpine, then npm install -g @rhost-rw/cli |
On Windows it behaves the same in PowerShell, Command Prompt and Windows Terminal. The CLI checks the Node version itself and refuses to start on one too old, rather than failing later with a syntax error that explains nothing.
If your shell cannot find rhost after a global install, npm's bin directory
is not on your PATH — npm prefix -g prints where it put things (the commands
are in that folder on Windows, in its bin/ on macOS and Linux). If a global
install asks for sudo, you are installing into a system-owned Node; install
Node with nvm or Homebrew instead rather than running npm as root.
Signing in
rhost login asks for your RHost email and password, and for a second factor
if your account has one (an authenticator code or an emailed code — a passkey
needs a browser, so add an authenticator app under Settings → Security if
that is all you have).
The session is written to ~/.rhost/config.json, owner-readable only. It is a
real session: it shows up under Settings → Security → Sessions and you can
end it from there.
rhost whoami who you are, and which workspace is selected
rhost workspaces workspaces you belong to
rhost use "Acme Ltd" pick the default workspace
rhost logout forget the session on this machineLinking a directory
rhost link writes .rhost.json next to your code:
{ "workspaceId": "…", "appId": "…", "nodeId": "…", "kind": "node", "name": "api" }Commit it. It holds no secrets, and it means a teammate who clones the
repository can run rhost logs without looking anything up. Every command
below takes the app from this file unless you name one.
Making something new
rhost create asks the same questions the console's New-app wizard asks —
what you are building, where the code is, which server, which port, which
address — and then builds it:
rhost create ask what to make, then ask for what it needs
rhost create app [name] web service, private service, worker, cron job, static
rhost create db [name] Postgres, MySQL or Redis
rhost create site [name] a static site built from Git and served by RHost
rhost create project [name] group apps and databases
rhost create env Staging --project Acme
rhost projects projects and their environments
rhost move api --project Acme --environment ProductionEverything it asks can be given as a flag instead, which is what makes it scriptable:
rhost create app api \
--server edge-1 --kind web --repo https://github.com/acme/api --branch main \
--port 3000 --env NODE_ENV=production --env-file .env.production \
--project Acme --environment Production --link| Flag | |
|---|---|
| --server <name> | Which of your servers it runs on |
| --kind | web, private, worker, cron, static — default web |
| --repo / --image | Build a repository, or run something already built |
| --branch, --root | For a repository; --root is the folder in a monorepo |
| --port <n> | The port it listens on inside the container |
| --cron "0 3 * * *" | Schedule, for --kind cron |
| --build-command, --start-command, --publish-dir | Overrides |
| --domain <fqdn> | Your own domain. Omit it (or pass --free) for a free RHost address |
| --env K=V, --env-file, --build-env K | Variables; --env repeats |
| --project, --environment | File it under a project as it is created |
| --link | Link this directory to the new app |
Addresses. Leave --domain out and the app gets a free *.apps.rhost.rw
name that is live at once, because RHost writes that record into its own zone.
Give a domain you own and the app waits at awaiting_dns until an A record
points at the server — the CLI prints the exact record, and offers to add it
for you when the zone is one RHost already serves.
What it will not create. Apps and databases on RHost's own hardware are paid subscriptions bought through a checkout, so they are made in the console — the CLI says so and gives you the link rather than failing at an endpoint. Your own servers and static sites cost nothing extra and are created outright.
Shipping
rhost deploy build and release; follows the build
rhost deploy --no-cache rebuild without the layer cache
rhost logs -f follow the running container's output
rhost logs --since 2h a past window
rhost logs --build the last build's transcript
rhost deployments history, newest first
rhost rollback put the last good deploy back
rhost rollback 3f9a21c …or a specific one
rhost cancel stop a build that is still running
rhost status state, address, last deploy
rhost events what RHost did to this app and when
rhost run -- npx prisma migrate deployrhost deploy follows the build when it is attached to a terminal and exits
non-zero if the deploy fails, so it works as a CI step unchanged. Piped or
redirected, it triggers the deploy and returns.
Environment variables
rhost env names, values masked
rhost env --reveal values too
rhost env set DATABASE_URL=postgres://…
rhost env rm OLD_FLAG
rhost env pull .env.productionSetting or removing a variable redeploys the app: a running container cannot be handed new values.
The rest of the platform
rhost apps everything deployable in the workspace
rhost overview what is running, failing, and recently changed
rhost db managed databases
rhost db url orders connection details for one
rhost domains domains, and whether their nameservers point here
rhost dns example.rw its DNS records
rhost dns example.rw add A www 102.22.11.1
rhost servers servers you registered yourselfIn CI
Authenticate with a token instead of a password:
rhost token --reveal # run once locally, store the output as a secret# .forge/workflows/deploy.yml
- name: Deploy
env:
RHOST_TOKEN: ${{ secrets.RHOST_TOKEN }}
RHOST_WORKSPACE: Acme Ltd
run: npx -y @rhost-rw/cli deploy --followRHOST_TOKEN is a credential that can deploy and read everything in the
workspace. Keep it in your CI secret store; never in the repository. Revoke it
by ending that session under Settings → Security → Sessions.
| Variable | What it does |
|---|---|
| RHOST_TOKEN | Credential to use instead of the stored session |
| RHOST_WORKSPACE | Workspace name or id to act in |
| RHOST_API_URL | API base URL (default https://rhost.rw/api) |
| RHOST_CONFIG_DIR | Where the session is kept (default ~/.rhost) |
| NO_COLOR | Turn off colour |
Every listing command takes --json, so pipe to jq rather than parsing
tables:
rhost apps --json | jq -r '.[] | select(.status=="failed") | .name'MCP: giving an AI agent the same abilities
The package ships an MCP server on stdio. Point any MCP client at it:
{
"mcpServers": {
"rhost": {
"command": "npx",
"args": ["-y", "@rhost-rw/cli", "mcp"],
"env": { "RHOST_WORKSPACE": "Acme Ltd" }
}
}
}The configuration is the same everywhere; only the file changes:
| Client | Where the file lives |
|---|---|
| Claude Code | .mcp.json in the project, or ~/.claude.json for every project |
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json |
| Cursor | .cursor/mcp.json in the project, or ~/.cursor/mcp.json |
| Anything else | Wherever that client keeps its list of MCP servers |
Any client that speaks MCP over stdio works the same way, on any platform.
rhost help mcp-setup prints all of this in the terminal.
The server reuses the session rhost login created, so there is no second
credential to manage. In an environment with no interactive login — a container,
a hosted agent — set RHOST_TOKEN instead.
Tools. Reading: rhost_guide, rhost_overview, rhost_list_apps,
rhost_app_status, rhost_app_logs, rhost_list_deployments,
rhost_app_events, rhost_get_env, rhost_list_databases,
rhost_database_connection, rhost_list_servers, rhost_list_domains,
rhost_list_dns_records, rhost_list_projects. Writing: rhost_deploy,
rhost_rollback, rhost_set_env, rhost_set_app_running,
rhost_run_command, rhost_create_dns_record, rhost_create_app,
rhost_create_database, rhost_create_static_site, rhost_create_project,
rhost_move_to_project.
What it will not do by default.
- Secrets are masked. Environment values come back as lengths, and
rhost_database_connectionrefuses outright, unless you start the server withRHOST_MCP_ALLOW_SECRETS=1. RHOST_MCP_READ_ONLY=1removes every write tool from the list, so an agent cannot deploy, roll back or change a variable even if it tries.- Nothing destructive is exposed at all: no tool deletes an app, a database, a domain or a record.
rhost_guide is worth knowing about: it hands the agent a short description of
how RHost deploys work, what the phases mean, and the handful of failure modes
that account for most broken apps — so it diagnoses from the platform's actual
behaviour instead of guessing.
Developing
pnpm install
pnpm run build
pnpm test
node dist/bin/rhost.js --helppnpm run build compiles src/ to dist/. pnpm test builds and runs the
unit tests (node --test) over the pure helpers — argument parsing, log
de-duplication, time windows, table layout.
