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)
curl -sSfL https://raw.githubusercontent.com/uptimy/uptimyctl/master/scripts/install.sh | sudo bashGo Install
go install github.com/uptimy/uptimyctl@latestBuild from Source
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.
sudo uptimyctl update
uptimyctl update --check # only report whether a newer release existsAuthentication
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 loginCommands Reference
Applications
uptimyctl applications list
uptimyctl applications get <uuid>Healthchecks
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> --clearIncidents
--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.
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 statsMaintenance 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.
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.
uptimyctl tags listHeartbeats
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.
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:
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.
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 githubReports
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.
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)
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.
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 agentversion: 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.
uptimyctl incidents list -o jsonCI/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.
- 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.
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.myAPI 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.