CLI

Manage Norcube Monitor from the terminal with norcube / nrc. Monitors, check history, incidents and alert channels, plus two commands that gate a deploy pipeline on what the checks found.

The Norcube CLI (norcube, alias nrc) exposes Norcube Monitor under the nrc monitor command group. Everything the dashboard does with monitors, incidents and channels is there, scriptable, and two commands are made for CI: fail a job while a critical incident is open, and run a monitor's check now and fail when it finds the site down. Status pages have a page of their own. Every flag of every command is in the generated CLI reference.

Every command supports --org <slug> to override the organization, --profile <name> to use another profile, -o table|json|yaml|text for output and --query to pick fields (see output and scripting). Setup is the standard CLI login:

nrc login
nrc org use <slug>
nrc monitor status        # sanity check

Monitors and channels are named by their id or, where a command says so, by their exact name ("Shop API").

Gate a deploy

# Fail the job while a critical incident is open anywhere in the organization
nrc monitor status --fail-on critical

# Fail it while any incident (warnings included) is open
nrc monitor status --fail-on warning

# Check one monitor right after the deploy and fail if it is down
nrc monitor monitors run "Shop API" --wait

# ... or also when it is slow
nrc monitor monitors run "Shop API" --wait --fail-on warning

status prints the open incidents by severity, the monitors by status and every monitor that is critical or warning. The verdict comes from open incidents, which are problems the checks confirmed. With --fail-on it exits 1 while incidents of that severity or worse are open; the default none always exits 0.

monitors run runs the check right away (a paused monitor too) and prints the stored result. It is billed like a scheduled check and rate limited to 200 per user and 600 per organization an hour. With --wait the result becomes the command's outcome: exit 1 (code job_failed, the result in the error's details) when the check found the monitor critical or couldn't reach a verdict, exit 7 when nothing arrived within --wait-timeout (2 minutes by default). Without --wait it exits 0 whatever the check found.

A GitHub Actions step:

- name: Is the shop up?
  run: nrc monitor monitors run "Shop API" --wait
  env:
    NORCUBE_TOKEN: ${{ secrets.NORCUBE_MONITOR_TOKEN }}

Monitors

nrc monitor monitors list
nrc monitor monitors list --status critical -o json --query "[].name"
nrc monitor monitors get "Shop API"

# create (the first check runs at once)
nrc monitor monitors create "Shop" --type http --url https://shop.example.com/health
nrc monitor monitors create "Login page" --type keyword --url https://example.com/login --keyword "Sign in"
nrc monitor monitors create "API cert" --type ssl --host api.example.com --alert-days 30,7
nrc monitor monitors create "example.com" --type domain --domain example.com --interval 24h

# change only what you pass
nrc monitor monitors update "Shop" --interval 5m
nrc monitor monitors pause "Shop"
nrc monitor monitors resume "Shop"
nrc monitor monitors delete "Shop"

# many at once
nrc monitor monitors bulk pause <monitor> <monitor>

create takes --type http, keyword, ssl or domain with the flags of that type; settings you don't pass get defaults, the same as the dashboard's except for the SSL interval (1 hour here, 1 minute there). Secret header values are read from a file or standard input (--secret-headers-file), never from arguments. Anything the flags don't cover goes in as the API's JSON body with --from-file.

Check history

nrc monitor monitors results list "Shop API"             # raw checks, newest first
nrc monitor monitors status-changes list "Shop API"      # up, down, expiring, and for how long
nrc monitor monitors stats get "Shop API" --range 7d     # uptime, response times, counts
nrc monitor monitors availability get "Shop API"         # per UTC day, up to 90
nrc monitor monitors certificate get "API cert"          # the newest certificate seen

Alert routing

nrc monitor monitors alerts get "Shop"
nrc monitor monitors alerts set "Shop" --route "On-call webhook=down,recovered" --route ops-email=down
nrc monitor monitors alerts set "Shop" --confirm-failures 3 --reminder 30m
nrc monitor monitors alerts set "Shop" --mute
nrc monitor monitors alerts set "Shop" --defaults

Incidents

nrc monitor incidents list
nrc monitor incidents list --status open --severity critical
nrc monitor incidents get <incident>
nrc monitor incidents acknowledge <incident>
nrc monitor incidents summary

Alert channels

nrc monitor channels list
nrc monitor channels create "Ops" --kind email --address [email protected] --default
nrc monitor channels create "On-call webhook" --kind webhook \
  --url https://example.com/hooks/monitor --secret-file webhook-secret.txt
pbpaste | nrc monitor channels create "#alerts" --kind slack --url-file -
nrc monitor channels create "On-call phone" --kind sms --phone +420601123456

nrc monitor channels verify "On-call phone"              # sends a code and asks for it
nrc monitor channels test "Ops"
nrc monitor channels update "Ops" --default=false
nrc monitor channels update "On-call webhook" --rotate-secret --secret-file new-secret.txt
nrc monitor channels deliveries list "On-call webhook" --status dead
nrc monitor channels delete "Ops"

Credentials never pass through arguments or stdout: Slack and Discord URLs come from a file or standard input (--url-file), a webhook's signing secret is written to the file you name with --secret-file and never printed, and verification codes are typed on the terminal or read with --code-file.

CI tokens and scopes

A CI token needs a Norcube Monitor scope. Each scope includes every read.

Scope	Allows
`monitor.read`	Every read: monitors, results, stats, status changes, availability, certificates, alert routing, incidents and their summary, channels (never their credentials), delivery logs and status pages. Enough for `nrc monitor status`.
`monitor.check`	Reads, plus `monitors run`. The "is it up?" step of a pipeline, without being able to change monitors.
`monitor.write`	Reads and checks, plus creating, changing, pausing, resuming and deleting monitors (one by one and in bulk), setting their alert routing and acknowledging incidents.
`monitor.channels`	Reads, plus creating, changing, deleting, testing and verifying alert channels.
`monitor.statuspages`	Reads, plus managing status pages and posting incidents on them. No other scope includes it.

Alert channels have a scope of their own on purpose: they hold credentials, every send reaches a real phone or endpoint, and a token that could switch off the default channel would silence the organization's alerts. monitor.write does not include monitor.channels, and monitor.channels changes no monitor. Routing a monitor to existing channels is a monitor change (monitor.write).

Set the token as NORCUBE_TOKEN; a request outside the token's scopes is refused with a 403 (exit code 5).

Anything else

nrc api monitor <method> <path> sends any request to the Norcube Monitor API with your CLI session; see calling any API and the API page.

On this page