Tools

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 manages incidents, maintenance windows, healthchecks, heartbeats, status pages and applications, and reads uptime and SLA reports. It also keeps your whole workspace in a file you can review and apply, so you or your coding agent set Uptimy up by editing a file instead of clicking.

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 .

Update

uptimyctl update installs the latest release for your platform, checked against its checksums. Run it with sudo when uptimyctl is in /usr/local/bin, as the quick install puts it. Builds from source are updated the way they were built.

In a terminal, uptimyctl tells you after a command when a newer release is out. It checks at most once a day and stays quiet with -o json, in CI, and with UPTIMYCTL_NO_UPDATE_CHECK=1.

update.sh
sudo uptimyctl update
uptimyctl update --check   # only report whether a newer release exists

Authentication

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

MethodDetails
Flag--api-key YOUR_KEY on any command
Environment variableUPTIMYCTL_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.

login.sh
# 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>
uptimyctl healthchecks tag <uuid> --tag production --tag api   # replaces its tags
uptimyctl healthchecks tag <uuid> --clear

Incidents

--status-page shows an incident on that status page and tells its subscribers; without it the incident stays internal. Statuses are written as the app shows them: Created, Acknowledged, Investigating, Identified, Monitoring and Resolved. An incident a monitor opened resolves on its own when the monitor recovers, so resolve only works on incidents created by hand.

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

Maintenance Windows

A maintenance window starts and completes on its own at its start and end times. While it runs, alerts are held back only for the monitors in --services: each entry is a monitor's UUID from uptimyctl applications list or a heartbeat's from uptimyctl heartbeats list, with the name status pages show. --status-page shows the window on that status page (UUIDs from uptimyctl status-pages list). start and resolve start or complete a window early.

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" \
  --services '[{"uuid":"<application-uuid>","name":"API"}]' \
  --status-page <status-page-uuid>
uptimyctl maintenances update <uuid> --finish-at "2026-03-01T05:00:00Z"
uptimyctl maintenances start <uuid>      # start before its start time
uptimyctl maintenances resolve <uuid>    # complete before its end time
uptimyctl maintenances cancel <uuid>
uptimyctl maintenances delete <uuid>

Tags

Tags are given by name or id; tag replaces a monitor's tags, and an unknown name lists the workspace's tags. Create tags in the app.

tags.sh
uptimyctl tags list

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 tag <uuid> --tag production,cron
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://ping.upti.my/<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 and above; --week (the last sent weekly report) works on every plan.

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>

The workspace as a file

uptimyctl export writes your monitors, cron job monitors, status pages, alerts and reports to a YAML file. uptimyctl plan shows what applying a changed file would do, and uptimyctl apply does it. Everything is matched by name; what the file doesn't have is kept unless you add --prune. Monitors managed by an Uptimy Agent and workflows built in the workflow editor are never touched.

terminal
uptimyctl export -f uptimy.yaml
# edit uptimy.yaml, or ask your coding agent to
uptimyctl plan -f uptimy.yaml
uptimyctl apply -f uptimy.yaml          # shows the plan and asks first
uptimyctl apply -f uptimy.yaml --yes    # in CI, or from an agent
uptimy.yaml
version: 2
monitors:
  - name: Website
    target: https://acme.com      # http by default; also ssl, tcp, ping, dns, mcp
    tags: [prod]
  - name: acme.com SSL
    type: ssl
    target: acme.com
heartbeats:
  - name: Nightly backup
    cron: "0 2 * * *"
    timezone: Europe/Berlin
statusPages:
  - name: Acme Status
    public: true
    groups:
      - name: Services
        monitors: [Website, Nightly backup]
alerts:
  - name: "Prod to #ops"
    to: { integration: slack }    # or emails: [...], or webhook: https://...
    tags: [prod]
reports:
  - name: Globex                  # e.g. one per client
    tags: [globex]                # or monitors: [...]; neither = every monitor
    sla: 99.5
    emails: [cto@globex.com]
    brand: { name: Globex, color: "#0055ff" }

Left out means the default: every region your plan allows, a check every 60 seconds (SSL hourly), a 30 second timeout, alerts for opened and resolved incidents, and reports at a 99.9% SLA target, emailed monthly on the 1st at 09:00 when they have recipients. The All monitors report can be changed but never removed. Slack and the other integrations are connected in the app; an alert names one. Report logos and share links are set up in the app too.

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 open a maintenance window for the services you deploy. Alerts for them are held back while it runs, and the status page shows the window. It completes on its own at --finish-at; the last step completes it early once the deploy is done.

.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)" \
      --services '[{"uuid":"<application-uuid>","name":"API"}]' \
      --status-page <status-page-uuid> \
      -o json > maintenance.json
    echo "id=$(jq -r .uuid maintenance.json)" >> "$GITHUB_OUTPUT"
  env:
    UPTIMYCTL_API_KEY: ${{ secrets.UPTIMYCTL_API_KEY }}

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

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

Keep the workspace in Git

Commit uptimy.yaml next to your code, run uptimyctl plan in pull requests and uptimyctl apply --yes on merge. The same file applied with another workspace's key copies the setup to it.

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
reports_api_url: https://reports.upti.my

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