Skip to content

What do you need to do?

Docs

CLI

realuptime is a zero-dependency command-line client over the REST API and the public outage endpoint. Node 22 or newer, nothing else.

Install

Two install paths work today. Both install the same release tarball, version 0.2.0, built from the public source mirror.

Homebrew (macOS and Linux)

bash
brew install realuptimehq/realuptime/realuptime

The tap formula pins the release tarball by URL and SHA-256 and depends on Homebrew's node. Upgrade with brew upgrade realuptime.

npm, from the GitHub release

bash
npm install -g https://github.com/RealUptimeHQ/realuptime-cli/releases/download/cli-0.2.0/realuptime-cli-0.2.0.tgz

Works with any npm 7 or newer and Node 22 or newer. The package has zero runtime dependencies, so this downloads one small tarball and nothing from the registry.

npm, from the registry (once published)

bash
npm install -g @realuptime/cli

@realuptime/cli is not on the npm registry yet. This command will work the day it is; until then use one of the two paths above, which are the real, working installs.

Verify a release

Every release ships SHA256SUMS and SHA256SUMS.sig beside the tarball. The signature is a cosign signature by the same key that signs the Monitor agent's releases; its public half is served at https://realuptime.io/.well-known/cosign.pub. If a release was cut without the signing key, its release notes say so explicitly rather than shipping an unsigned file quietly.

bash
curl -fsSLO https://realuptime.io/.well-known/cosign.pub
curl -fsSLO https://github.com/RealUptimeHQ/realuptime-cli/releases/download/cli-0.2.0/SHA256SUMS
curl -fsSLO https://github.com/RealUptimeHQ/realuptime-cli/releases/download/cli-0.2.0/SHA256SUMS.sig
cosign verify-blob --key cosign.pub --signature SHA256SUMS.sig SHA256SUMS
sha256sum -c SHA256SUMS   # after downloading the tarball into the same directory

Configure

Every command except outages needs an API key, generated from the dashboard's API & MCP access section. The REST API, and so the CLI's keyed commands, is a Growth or Scale feature, reads included (the same rule the API reference sets out). A key's scope applies exactly as it does over HTTP: a read key can list, a read_write key can also create, update, and delete.

  • --api-key <key> or REALUPTIME_API_KEY. Prefer the environment variable: a flag value lands in shell history.
  • --api-url <url> or REALUPTIME_API_URL, default https://realuptime.io/api/v1.
  • --json on any command prints the untouched API response.
  • --version, help.

Commands

bash
export REALUPTIME_API_KEY=ru_live_...

realuptime checks list
realuptime checks create --name API --url https://api.example.com/health --interval 60 --regions iad,fra
realuptime checks delete <id>

realuptime incidents list --limit 20
realuptime incidents create --status-page-id <id> --check-id <id> --region iad --title "API is down" --body "Investigating."
realuptime incidents update <id> --status resolved --body "Fixed."

realuptime status-pages list

realuptime errors issues list --project-id <id> --status open
realuptime errors releases announce --project-id <id> --release v2.4.1 --commit-sha a1b2c3d --repo-url https://github.com/acme/widgets
CommandCallsKey scope
realuptime checks listGET /checksread
realuptime checks createPOST /checksread_write
realuptime checks delete <id>DELETE /checks/:idread_write
realuptime incidents listGET /incidentsread
realuptime incidents createPOST /incidentsread_write
realuptime incidents update <id>POST /incidents/:id/updatesread_write
realuptime status-pages listGET /statusread
realuptime outages <slug>GET /outages/:slug (public)none
realuptime errors issues listGET /errors/projects/:id/issuesread
realuptime errors releases announcePOST /errors/releasesread_write

Each command is a thin wrapper over one REST call with the same validation, limits, and refusals; the API reference is the source of truth for every field. incidents update accepts --force to resolve an incident whose monitor is still down, exactly like the API's force field.

Outages without a key

realuptime outages <slug> never sends a key. It reads the same public JSON endpoint the outage tracker pages and the keyless MCP tools read, so the answer carries the regions actually measured, a measurement time, and an explicit verdict; a blocked probe is never reported as down, and a service we do not track says so. Add --region for one region's reading.

bash
# No API key, no account: reads the public /outages/<slug> JSON endpoint.
realuptime outages github
realuptime outages cloudflare --region fra --json

Machine-readable output

Without --json the CLI prints a short human summary. With it, stdout is exactly the API's response body, so anything that reads the API can read the CLI:

bash
realuptime checks list --json | jq '.checks[] | select(.status != "operational") | .name'

Errors and exit codes

A refusal prints the API's own error message, its RU-XXXX code, and, when the API sent one, the knowledge base link for that code, exactly as the API returned them, then exits 1. The CLI never invents its own copy for a server-side refusal. Exit 0 means the command succeeded; exit 1 means it did not (a refusal, a missing key, a malformed flag, or a network failure). Usage with no command prints help and exits 1.

text
$ realuptime checks delete 7f3c...   # with a read-only key
This API key is read-only. Generate a read-write key to perform this action. [RU-1004]
https://realuptime.io/kb/errors/RU-1004
$ echo $?
1

Source and license

MIT licensed. The source, the compiled package, and every release live at github.com/RealUptimeHQ/realuptime-cli; the Homebrew tap at github.com/RealUptimeHQ/homebrew-realuptime. Prefer an assistant to a shell? The MCP server exposes the same API as tools.