CLI (uptimyctl)

Manage incidents, maintenance windows, healthchecks, heartbeats, and workspace configuration from the command line.

Overview

uptimyctl is a command-line tool for managing your Uptimy workspace. It provides full CRUD access to incidents, maintenance windows, healthchecks, and applications, and reads uptime and SLA reports. It also supports exporting and importing your workspace configuration for infrastructure-as-code workflows.

Source code and releases are available at github.com/uptimy/uptimyctl.

Installation

Install uptimyctl using one of the following methods.

Quick Install (curl)

install.sh

curl -sSfL https://raw.githubusercontent.com/uptimy/uptimyctl/master/scripts/install.sh | sudo bash

Go Install

go-install.sh

go install github.com/uptimy/uptimyctl@latest

Build from Source

build.sh

git clone https://github.com/uptimy/uptimyctl.git
cd uptimyctl
go build -o uptimyctl .

Authentication

uptimyctl supports three ways to provide your API key, listed in order of precedence.

Method	Details
Flag	`--api-key YOUR_KEY` on any command
Environment variable	`UPTIMYCTL_API_KEY=YOUR_KEY`
Config file	`~/.config/uptimyctl/config.yaml` (created by `uptimyctl auth login`)

The easiest way to sign in is uptimyctl auth login. It opens the Uptimy app in your browser, where you pick a workspace and approve access. The browser hands a one-time code back to the CLI, which exchanges it for an API key for that machine, valid for 90 days. The key itself never passes through the browser. Each key is named uptimyctl (hostname), so you can revoke it under Settings → API Keys.

# Opens your browser and saves the key automatically
uptimyctl auth login

# Over SSH or on a headless machine: open the printed URL anywhere, paste the code
uptimyctl auth login --no-browser

# In scripts: pipe an existing key
echo "$UPTIMY_KEY" | uptimyctl auth login

Commands Reference

Applications

applications.sh

uptimyctl applications list
uptimyctl applications get <uuid>

Healthchecks

healthchecks.sh

uptimyctl healthchecks list
uptimyctl healthchecks get <uuid>
uptimyctl healthchecks trigger <uuid>
uptimyctl healthchecks pause <uuid>
uptimyctl healthchecks resume <uuid>

Incidents

incidents.sh

uptimyctl incidents list
uptimyctl incidents get <uuid>
uptimyctl incidents create --title "API outage" --severity critical --public
uptimyctl incidents update <uuid> --status investigating
uptimyctl incidents add-update <uuid> --message "Root cause identified"
uptimyctl incidents resolve <uuid>
uptimyctl incidents stats

Maintenance Windows

maintenance.sh

uptimyctl maintenances list
uptimyctl maintenances create --title "DB migration" --description "Scheduled database migration" --start-at "2026-03-01T02:00:00Z" --finish-at "2026-03-01T04:00:00Z"
uptimyctl maintenances update <uuid> --title "DB migration (extended)"
uptimyctl maintenances start <uuid>
uptimyctl maintenances resolve <uuid>
uptimyctl maintenances cancel <uuid>
uptimyctl maintenances delete <uuid>

Heartbeats

Heartbeats are dead man's switches for cron jobs and workers: they alert when check-ins stop. New heartbeats default to a 1-hour interval with 5 minutes of grace. Durations accept values like 90s, 5m or 24h. update only changes the flags you pass.

heartbeats.sh

uptimyctl heartbeats list
uptimyctl heartbeats create --name "Nightly backup" --interval 24h --grace 30m
uptimyctl heartbeats create --name "Nightly backup" --client-ref backup-prod   # idempotent
uptimyctl heartbeats get <uuid>              # includes the ping URL
uptimyctl heartbeats update <uuid> --interval 12h
uptimyctl heartbeats pause <uuid>
uptimyctl heartbeats resume <uuid>
uptimyctl heartbeats ping <uuid>             # send a test check-in
uptimyctl heartbeats delete <uuid>

create prints the heartbeat's ping URL. Call it at the end of every successful run; it needs no API key:

crontab

0 3 * * *  /usr/local/bin/backup.sh && curl -fsS https://heartbeats.upti.my/v1/monitors/<id>

Dependencies

Follow the third-party services Uptimy measures, like GitHub, Cloudflare or Stripe. When a followed service goes down, your workspace gets its own incident. See Dependencies.

dependencies.sh

uptimyctl dependencies catalog                  # every service you can follow
uptimyctl dependencies list                     # what you follow, with live status
uptimyctl dependencies get github               # its probes and which ones you follow
uptimyctl dependencies follow github            # every probe
uptimyctl dependencies follow github --probe rest-api --probe git-operations
uptimyctl dependencies unfollow github

Reports

Read uptime reports: availability against the SLA target, downtime, incidents and planned maintenance for a period. get defaults to the last 30 days of the All monitors report; --report takes a report's name or UUID. Months, quarters, ranges and the current week need Growth or above; --week (the last sent weekly report) is free.

reports.sh

uptimyctl reports list
uptimyctl reports get --last 7d --report Acme   # 7d, 30d or 90d
uptimyctl reports get --week                    # the last sent weekly report
uptimyctl reports get --this-week
uptimyctl reports get --month 2026-09
uptimyctl reports get --quarter 2026-Q3 -o json
uptimyctl reports get --from 2026-09-01 --to 2026-09-15 --csv days > september.csv

--csv takes monitors, days, incidents or maintenance.

Schedulers (Regions)

schedulers.sh

uptimyctl schedulers list
uptimyctl schedulers get <uuid>

Export & Import

Export your entire workspace configuration to a JSON file and import it into another workspace. This is useful for promoting configuration from staging to production or for backup purposes.

export-import.sh

uptimyctl export -f config.json
uptimyctl import config.json

Output Formats

By default, uptimyctl outputs results in a human-readable table format. Use -o json for machine-readable JSON output.

json-output.sh

uptimyctl incidents list -o json

CI/CD Integration

Use uptimyctl in your deployment pipelines to create maintenance windows before deploys and resolve them afterward. This suppresses false alerts during expected downtime.

.github/workflows/deploy.yml

- name: Start maintenance window
  id: maintenance
  run: |
    uptimyctl maintenances create \
      --title "Deploy ${{ github.sha }}" \
      --description "Automated deployment maintenance window" \
      --start-at "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
      --finish-at "$(date -u -d '+30 minutes' +%Y-%m-%dT%H:%M:%SZ)"
  env:
    UPTIMYCTL_API_KEY: ${{ secrets.UPTIMYCTL_API_KEY }}

- name: Deploy application
  run: ./deploy.sh

- name: Resolve maintenance window
  run: uptimyctl maintenances resolve ${{ steps.maintenance.outputs.id }}
  env:
    UPTIMYCTL_API_KEY: ${{ secrets.UPTIMYCTL_API_KEY }}

💡 Config Management

Use uptimyctl export and uptimyctl import for Terraform-style config management. Export from production, review changes, and import into staging or new workspaces.

Configuration

The config file is stored at ~/.config/uptimyctl/config.yaml and is created automatically by uptimyctl auth login. Environment variables and flags override config file values.

~/.config/uptimyctl/config.yaml

api_key: upt_your-api-key-here
api_url: https://api.upti.my
incidents_api_url: https://workflows.upti.my
heartbeats_api_url: https://heartbeats.upti.my

API keys start with the upt_ prefix. Incidents and maintenance windows are served by the workflows service at incidents_api_url, and heartbeats by the heartbeat service at heartbeats_api_url. Output format is controlled with the -o flag, not the config file.