@uptimerobot/cli 0.3.0 → 1.0.0

package/README.md

@@ -36,6 +36,13 @@ uptimerobot --version
 uptimerobot --help
 ```
 
+`--version` prints one human-readable line. The `version` command reports the same facts through the normal output flags, so a script asserting a minimum version reads a field instead of parsing a sentence:
+
+```sh
+uptimerobot version --json
+# {"version":"1.0.0","platform":"darwin-arm64","node":"24.12.0"}
+```
+
 ## AI agent skills
 
 Install the [UptimeRobot AI skills](https://github.com/uptimerobot/ai) for supported coding agents:
@@ -123,6 +130,30 @@ uptimerobot monitors update 797054213 --set interval=120
 uptimerobot monitors create http --body - < monitor.json
 ```
 
+`--body` is a base document, and typed flags and `--set` are applied on top of it. Those two are peers, so giving the same field a different value with both is an error rather than a silent win for one of them:
+
+```sh
+uptimerobot monitors create http --name checkout-api --set friendlyName=checkout
+# INVALID_INPUT: friendlyName received conflicting values:
+#   --name checkout-api and --set friendlyName=checkout. Pass only one.
+```
+
+## Heartbeat monitors
+
+A heartbeat monitor stays silent until something pings it, so normalized output carries a derived `pingUrl` — the address that job should call. Both it and the `url` it is built from are secrets, so both are redacted unless you ask for them:
+
+```sh
+uptimerobot monitors get 803704830 --json
+# {"type":"HEARTBEAT","id":803704830,"url":"[REDACTED]","pingUrl":"[REDACTED]"}
+
+uptimerobot monitors get 803704830 --json --reveal-secrets
+# {"type":"HEARTBEAT","id":803704830,"url":"997c8970…","pingUrl":"https://heartbeat.uptimerobot.com/m803704830-997c8970…"}
+```
+
+Reach for `--reveal-secrets` when wiring up the job that pings it, which is normally once per monitor. Anyone holding the ping URL can report the heartbeat on your behalf, so a leaked one keeps a dead service looking alive with no alert raised. `url` on every other monitor type is a target address, not a secret, and is never redacted.
+
+The URL is composed from the monitor's `id` and `url`, where `url` carries the monitor's token rather than a target address. Set `UPTIMEROBOT_HEARTBEAT_URL` to point at a different host. The field is derived by the CLI, not returned by the API, so `--raw` does not include it.
+
 ## Validate before sending
 
 Inspect a monitor request contract or print a validated example without credentials or network access:
@@ -167,15 +198,29 @@ The exit code identifies the failure:
 | --------- | ----------------------------------------------------------------------------------- |
 | `0`       | Success                                                                             |
 | `1`       | Generic failure, including a bulk operation where every item failed (`BULK_FAILED`) |
-| `2`       | Invalid input                                                                       |
+| `2`       | Invalid input, rejected either locally or by the API (HTTP 400 or 422)              |
 | `3`       | Bulk operation where some items failed (`BULK_PARTIAL_FAILURE`)                     |
 | `4`       | Unauthenticated (HTTP 401)                                                          |
 | `5`       | Forbidden (HTTP 403)                                                                |
 | `6`       | Not found (HTTP 404)                                                                |
 | `7`       | Rate limited (HTTP 429)                                                             |
+| `8`       | Conflict with the current state (HTTP 409)                                          |
+
+Exit code `2` covers both a request the CLI rejected before sending and one the API rejected as invalid, so it always means the input is wrong. Along with `8`, it says the request will not succeed as sent and should be changed rather than repeated; `1` and `7` are the failures a plain retry may clear.
+
+The error envelope's `code` is `HTTP_<status>` whenever `status` is present, and a CLI symbol such as `INVALID_INPUT` or `AUTH_REQUIRED` otherwise, so `status` distinguishes a failure the API reported from one the CLI raised. When the API supplies an error code of its own it is passed through verbatim as `apiCode` and is never interpreted; it is not part of the CLI's contract, because the API does not currently document those codes:
+
+```sh
+uptimerobot monitors get 999999999 --json
+# {"error":{"apiCode":"000-004","code":"HTTP_404","message":"Monitor not found","status":404}}
+```
+
+Branch on `code` or `status`. Read `apiCode` only for diagnostics, and use `--raw` for the untouched API response.
 
 `monitors bulk pause`, `monitors bulk start`, and `monitors bulk update` report per-monitor outcomes in an HTTP 201 response, so a failure is only visible in the body. The CLI inspects it and exits non-zero, listing the failed entries in the error envelope's `details`.
 
+Those three commands report acceptance rather than completion. The API answers `success` for every matched monitor as soon as the write is accepted; it carries no operation id, and nothing in the response distinguishes queued from applied. Exit code `0` therefore means the request was accepted, not that the monitors have changed. A pipeline that pauses monitors before a deploy should confirm with `uptimerobot monitors get <id>` before it continues.
+
 ## Safety
 
 Destructive commands prompt in an interactive terminal. Agents and non-interactive processes must pass `--confirm` explicitly:

package/bin/run.js

@@ -13,6 +13,19 @@ if (!nodeVersionSupported) {
   process.exit(1);
 }
 
+/**
+ * Resolves when a reader closes stdout before the CLI is done writing to it,
+ * which is what `| head`, `| head -c`, and `| grep -q` do. Every later write
+ * then fails with EPIPE. Without this listener Node reports the stream error
+ * as unhandled; with it, the broken pipe is simply the end of the output.
+ */
+const stdoutClosedEarly = new Promise((resolve) => {
+  process.stdout.on('error', (error) => {
+    if (error.code === 'EPIPE') resolve();
+    else throw error;
+  });
+});
+
 const { flush, handle, run } = await import('@oclif/core');
 const { commandSuggestion } = await import('../dist/lib/command-suggestions.js');
 const { isUnknownCommandMessage, withConfiguredCommandId } =
@@ -20,11 +33,20 @@ const { isUnknownCommandMessage, withConfiguredCommandId } =
 const { errorEnvelope, exitCodeForError, machineOutputRequested, wasErrorHandled } =
   await import('../dist/lib/cli-errors.js');
 
+/**
+ * oclif's flush() waits for a `drain` that a broken pipe never emits, so on
+ * EPIPE it never settles: Node then printed `Detected unsettled top-level
+ * await` on stderr and exited 13. Racing the two keeps stderr meaningful and
+ * lets the normal exit path decide the status, which is 0 for a reader that
+ * stopped listening and unchanged for a command that had already failed.
+ */
+const flushOutput = () => Promise.race([flush(), stdoutClosedEarly]);
+
 try {
   await run(process.argv.slice(2), import.meta.url);
-  await flush();
+  await flushOutput();
 } catch (error) {
-  await flush();
+  await flushOutput();
   if (typeof error === 'object' && error !== null && isUnknownCommandMessage(error.message ?? '')) {
     // oclif names the command with its colon-joined internal id; report it the
     // way the CLI accepts it, so the message is a syntax the user can retype.

package/dist/api/errors.js

@@ -7,19 +7,38 @@ export function normalizeApiError(status, payload) {
             ? rawMessage
             : `UptimeRobot API request failed with HTTP ${status}.`;
     return {
-        code: typeof object.code === 'string' ? object.code : `HTTP_${status}`,
+        // Derived from the transport status, never from the body: an upstream code
+        // is optional, undocumented, and absent from openapi.yaml, so reporting it
+        // as `code` left the vocabulary depending on which endpoint answered. The
+        // raw value is kept beside it, verbatim and uninterpreted.
+        ...(typeof object.code === 'string' ? { apiCode: object.code } : {}),
+        code: `HTTP_${status}`,
         ...(object.details !== undefined ? { details: object.details } : {}),
         message,
         status,
     };
 }
+/**
+ * Maps an HTTP status onto the CLI's exit code contract. A request the server
+ * rejected as invalid exits 2, the same code locally caught invalid input
+ * produces, so a caller can tell "the request was wrong, do not retry it" from
+ * a generic failure that retrying may clear. Conflicts get their own code
+ * because the request is well formed and only the current server state refuses
+ * it, which a caller resolves differently.
+ */
 export function exitCodeFor(status) {
+    if (status === 400)
+        return 2;
     if (status === 401)
         return 4;
     if (status === 403)
         return 5;
     if (status === 404)
         return 6;
+    if (status === 409)
+        return 8;
+    if (status === 422)
+        return 2;
     if (status === 429)
         return 7;
     return 1;

package/dist/commands/version.js

@@ -0,0 +1,44 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../lib/base-command.js';
+import { detectInvocationMode } from '../lib/invocation.js';
+import { formatOutput } from '../output/renderer.js';
+import { resolveFormat } from '../output/resolve-format.js';
+export default class Version extends BaseCommand {
+    // The bare --version flag is handled by oclif core before any command runs,
+    // so it always prints one human sentence. This command reports the same
+    // facts as separate fields, which is what a version assertion in CI needs.
+    static description = 'Report the CLI version, the platform it runs on, and the Node.js runtime executing it. Unlike the --version flag, this command honours the output flags, so a caller can read the version as a field instead of parsing a sentence.';
+    static examples = ['<%= config.bin %> version --json'];
+    static flags = {
+        format: Flags.string({
+            description: 'Output format; json is normalized and jsonl emits one resource per line',
+            options: ['json', 'jsonl', 'table', 'plain'],
+        }),
+        json: Flags.boolean({
+            description: 'Shorthand for --format json; emit normalized structured JSON',
+        }),
+    };
+    static summary = 'Show the CLI version';
+    async run() {
+        const { flags } = await this.parse(Version);
+        if (flags.json === true && flags.format !== undefined) {
+            return this.fail({ code: 'INVALID_INPUT', message: '--json cannot be combined with --format.' }, 2);
+        }
+        const info = {
+            version: this.config.version,
+            platform: `${this.config.platform}-${this.config.arch}`,
+            node: process.versions.node,
+        };
+        const format = resolveFormat(flags, detectInvocationMode(false));
+        if (format === 'json' || format === 'jsonl') {
+            this.log(JSON.stringify(info));
+            return;
+        }
+        // A single record has no collection to render, so it is passed as a
+        // one-row collection to get the table headings and the tab-separated
+        // plain row every other command produces.
+        const output = formatOutput(format, [info]);
+        if (output !== undefined)
+            this.log(output);
+    }
+}

package/dist/generated/operations.js

@@ -354,6 +354,15 @@ export const operations = {
                 "example": "Investigating the issue...",
                 "maxLength": 10000,
                 "type": "string"
+            },
+            {
+                "flag": "publish-on-status-page",
+                "path": "publishOnStatusPage",
+                "required": false,
+                "default": false,
+                "description": "Whether the comment is published on the status page",
+                "example": true,
+                "type": "boolean"
             }
         ]
     },
@@ -472,6 +481,15 @@ export const operations = {
                 "example": "Issue has been identified and fix is in progress...",
                 "maxLength": 10000,
                 "type": "string"
+            },
+            {
+                "flag": "publish-on-status-page",
+                "path": "publishOnStatusPage",
+                "required": false,
+                "default": false,
+                "description": "Whether the comment is published on the status page",
+                "example": true,
+                "type": "boolean"
             }
         ]
     },

package/dist/lib/command-suggestions.js

@@ -12,6 +12,7 @@ export const HANDWRITTEN_COMMANDS = [
     'help',
     'monitors schema',
     'skills install',
+    'version',
 ];
 const commands = [
     ...Object.keys(operations).map((commandId) => commandId.replaceAll(':', ' ')),

package/dist/lib/help-curation.js

@@ -0,0 +1,25 @@
+/**
+ * The three bulk endpoints answer with a per-monitor `success` that reports
+ * acceptance, not application: there is no operation id to poll and nothing
+ * distinguishes queued from applied, so a caller treating exit 0 as "done" may
+ * act on monitors still in their old state. A stale-cache defect that made the
+ * gap tens of seconds wide was fixed in UPT-3557, so no duration is quoted —
+ * the absent completion signal is the part that is structural.
+ */
+const BULK_DELAY_NOTE = 'Reports acceptance, not completion. The API answers "success" for every matched monitor as soon as the write is accepted; it carries no operation id, and nothing in the response distinguishes queued from applied. Confirm with `uptimerobot monitors get <id>` before anything depends on the new state.';
+/**
+ * Editorial notes appended to a command's help description. `src/generated` is
+ * a projection of openapi/openapi.yaml and is rewritten by
+ * `pnpm openapi:generate`, so behaviour the published contract omits belongs
+ * here, alongside the request curation in request-curation.ts.
+ */
+const DESCRIPTION_NOTES = {
+    'monitors:bulk:pause': BULK_DELAY_NOTE,
+    'monitors:bulk:start': BULK_DELAY_NOTE,
+    'monitors:bulk:update': BULK_DELAY_NOTE,
+};
+export function curatedCommandDescription(operation) {
+    const description = operation.description ?? operation.summary;
+    const note = DESCRIPTION_NOTES[operation.commandId];
+    return note === undefined ? description : `${description}\n\n${note}`;
+}

package/dist/lib/operation-command.js

@@ -13,6 +13,8 @@ import { InputValidationError, validateInput } from '../runtime/validate-input.j
 import { AuthenticationError, resolveApiKey } from './auth.js';
 import { BaseCommand } from './base-command.js';
 import { flagName } from './flag-name.js';
+import { curatedCommandDescription } from './help-curation.js';
+import { withDerivedFields } from './response-curation.js';
 import { detectInvocationMode, isCI, requestConfirmation } from './invocation.js';
 import { enrichOperationParserError } from './operation-parser-error.js';
 import { redactSecrets } from './redact-secrets.js';
@@ -57,6 +59,7 @@ export function createOperationCommand(operation, options = {}) {
         }
         : {};
     const defaultColumns = columnsFor(operation.commandId);
+    const description = curatedCommandDescription(operation);
     const bodyFieldFlags = Object.fromEntries((operation.requestBodyFields ?? []).map((field) => [
         field.flag,
         flagForBodyField(curatedRequestBodyField(operation, field)),
@@ -102,10 +105,10 @@ export function createOperationCommand(operation, options = {}) {
     class OperationCommand extends BaseCommand {
         static args = commandArgs;
         static description = options.canonicalCommand
-            ? `${operation.description ?? operation.summary}
+            ? `${description}
 
 Canonical command: ${options.canonicalCommand}`
-            : (operation.description ?? operation.summary);
+            : description;
         static examples = examplesFor(operation);
         static flags = commandFlags;
         static summary = operation.summary;
@@ -254,7 +257,8 @@ Canonical command: ${options.canonicalCommand}`
                 const apiError = normalizeApiError(response.status, payload);
                 return this.fail(apiError, exitCodeFor(response.status));
             }
-            const normalized = flags.raw === true ? payload : normalizeResult(payload);
+            // --raw is the untouched API response, so derived fields stay out of it.
+            const normalized = flags.raw === true ? payload : withDerivedFields(normalizeResult(payload));
             // Redacted before rendering, so column selection, truncation, and JSONL
             // splitting all operate on the redacted values. --raw stays untouched.
             const redaction = flags.raw === true || flags['reveal-secrets'] === true

package/dist/lib/redact-secrets.js

@@ -17,15 +17,30 @@ function redactValue(value, path, redacted) {
     }
     if (!isRecord(value))
         return value;
+    const contextual = contextualSensitiveKeys(value);
     return Object.fromEntries(Object.entries(value).map(([key, child]) => {
         const childPath = [...path, key];
-        if (isSensitiveFieldName(key)) {
+        if (isSensitiveFieldName(key) || contextual.has(key)) {
             redacted.push(formatPath(childPath));
             return [key, REDACTED];
         }
         return [key, redactValue(child, childPath, redacted)];
     }));
 }
+const NO_KEYS = new Set();
+const HEARTBEAT_SECRET_KEYS = new Set(['pingUrl', 'url']);
+/**
+ * Fields that carry a secret because of the record they sit in rather than what
+ * they are called. A heartbeat monitor's `url` is the token its ping endpoint
+ * is built from, and `pingUrl` is that endpoint: anyone holding either can
+ * report the heartbeat, so a leak keeps a dead service looking alive with no
+ * alert and nothing on the monitor to show for it. Every other monitor type
+ * uses `url` for a target address, which is not a secret — hence the type
+ * check rather than a name added to sensitive-fields.ts.
+ */
+function contextualSensitiveKeys(record) {
+    return record.type === 'HEARTBEAT' ? HEARTBEAT_SECRET_KEYS : NO_KEYS;
+}
 function formatPath(segments) {
     return segments.reduce((path, segment) => /^\d+$/.test(segment) ? `${path}[${segment}]` : path ? `${path}.${segment}` : segment, '');
 }

package/dist/lib/request.js

@@ -44,13 +44,17 @@ export async function buildRequestBody(operation, flags, headers) {
         return undefined;
     }
     const objectBody = toObject(bodyValue);
+    const typedAssignments = new Map();
     for (const field of bodyFields) {
         const value = flags[field.flag];
-        if (value !== undefined)
-            assignPath(objectBody, field.path, parseBodyField(field, value));
+        if (value === undefined)
+            continue;
+        const parsed = parseBodyField(field, value);
+        assignPath(objectBody, field.path, parsed);
+        typedAssignments.set(field.path, { flag: field.flag, value: parsed });
     }
     for (const assignment of assignments)
-        assignValue(objectBody, assignment);
+        assignValue(objectBody, assignment, typedAssignments);
     for (const [path, value] of Object.entries(operation.requestBodyDefaults ?? {})) {
         const supplied = valueAtPath(objectBody, path);
         if (supplied !== undefined && supplied !== value) {
@@ -111,9 +115,41 @@ function toObject(value) {
     }
     return structuredClone(value);
 }
-function assignValue(target, assignment) {
+function assignValue(target, assignment, typedAssignments) {
     const [path, rawValue] = splitAssignment(assignment, '--set');
-    assignPath(target, path, parseValue(rawValue));
+    const value = parseValue(rawValue);
+    // --body is a base that both typed flags and --set layer onto, but those two
+    // are peers: when they name the same field nothing says which one was meant,
+    // so the old last-one-wins silently discarded the typed flag.
+    const typed = typedAssignments.get(path);
+    if (typed !== undefined && !sameValue(typed.value, value)) {
+        throw new RequestInputError(path, 'a single value', `${path} received conflicting values: --${typed.flag} ${describeValue(typed.value)} and --set ${path}=${describeValue(value)}. Pass only one.`);
+    }
+    assignPath(target, path, value);
+}
+/**
+ * Structural equality, so the same object written two ways is not a conflict:
+ * a typed flag carrying `{"a":1,"b":2}` and `--set` carrying `{"b":2,"a":1}`
+ * say the same thing, and refusing them would be a false positive on the very
+ * case the conflict check is meant to allow through.
+ */
+function sameValue(left, right) {
+    return canonicalJson(left) === canonicalJson(right);
+}
+function canonicalJson(value) {
+    return JSON.stringify(withSortedKeys(value ?? null));
+}
+function withSortedKeys(value) {
+    if (Array.isArray(value))
+        return value.map(withSortedKeys);
+    if (!isPlainRecord(value))
+        return value;
+    return Object.fromEntries(Object.keys(value)
+        .sort()
+        .map((key) => [key, withSortedKeys(value[key])]));
+}
+function describeValue(value) {
+    return typeof value === 'string' ? value : JSON.stringify(value);
 }
 function splitAssignment(value, flag) {
     const separator = value.indexOf('=');

package/dist/lib/response-curation.js

@@ -0,0 +1,43 @@
+import { isPlainRecord } from './objects.js';
+/**
+ * The heartbeat host the ping URL is built against. Overridable because the
+ * host is environment-specific and is not part of the published API contract.
+ */
+const DEFAULT_HEARTBEAT_HOST = 'https://heartbeat.uptimerobot.com';
+/**
+ * A heartbeat monitor is inert until something pings its URL, and the API
+ * returns the ingredients without ever naming the result: `url` carries the
+ * token and the ping endpoint is `<host>/m<id>-<token>`. That composition is
+ * how the dashboard builds the URL it shows, but it is documented nowhere, so
+ * an API consumer cannot discover it. Deriving it here lets a heartbeat be
+ * created and wired up without a trip to the dashboard.
+ *
+ * Derived rather than authoritative: UPT-3726 asks the API to return the URL
+ * itself, and this should give way to that field once it exists.
+ */
+export function withDerivedFields(payload, env = process.env) {
+    if (Array.isArray(payload))
+        return payload.map((item) => withDerivedFields(item, env));
+    if (!isPlainRecord(payload))
+        return payload;
+    if (Array.isArray(payload.items)) {
+        return { ...payload, items: payload.items.map((item) => withDerivedFields(item, env)) };
+    }
+    // An API-supplied value wins: this composition exists only while the contract
+    // has none, and must not shadow the real field when UPT-3726 lands.
+    if (typeof payload.pingUrl === 'string')
+        return payload;
+    const pingUrl = heartbeatPingUrl(payload, env);
+    return pingUrl === undefined ? payload : { ...payload, pingUrl };
+}
+function heartbeatPingUrl(monitor, env) {
+    if (monitor.type !== 'HEARTBEAT')
+        return undefined;
+    const { id, url } = monitor;
+    if (typeof url !== 'string' || url.length === 0)
+        return undefined;
+    if (typeof id !== 'number' && typeof id !== 'string')
+        return undefined;
+    const host = (env.UPTIMEROBOT_HEARTBEAT_URL ?? DEFAULT_HEARTBEAT_HOST).replace(/\/+$/, '');
+    return `${host}/m${id}-${url}`;
+}

package/openapi/openapi.yaml

@@ -2300,6 +2300,8 @@ components:
                 exclusiveMinimum: false
               comment:
                 type: string
+              publishOnStatusPage:
+                type: boolean
               created:
                 oneOf:
                   - {}
@@ -2317,6 +2319,7 @@ components:
             required:
               - id
               - comment
+              - publishOnStatusPage
               - created
               - user
       required:
@@ -2508,6 +2511,11 @@ components:
           maxLength: 10000
           description: Updated content of the comment
           example: Issue has been identified and fix is in progress...
+        publishOnStatusPage:
+          type: boolean
+          description: Whether the comment is published on the status page
+          example: true
+          default: false
       required:
         - content
     IncidentCommentDto:
@@ -2519,6 +2527,8 @@ components:
           exclusiveMinimum: false
         comment:
           type: string
+        publishOnStatusPage:
+          type: boolean
         created:
           oneOf:
             - {}
@@ -2536,6 +2546,7 @@ components:
       required:
         - id
         - comment
+        - publishOnStatusPage
         - created
         - user
     CreateIncidentCommentRequestDto:
@@ -2546,6 +2557,11 @@ components:
           maxLength: 10000
           description: Content of the comment
           example: Investigating the issue...
+        publishOnStatusPage:
+          type: boolean
+          description: Whether the comment is published on the status page
+          example: true
+          default: false
       required:
         - content
     CreateMonitorGroupDto:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uptimerobot/cli",
-  "version": "0.3.0",
+  "version": "1.0.0",
   "description": "Official UptimeRobot CLI — manage uptime monitors, incidents, status pages, and alert contacts from your terminal, scripts, or CI.",
   "keywords": [
     "uptimerobot",
@@ -109,7 +109,7 @@
         "description": "Manage monitors and statistics",
         "subtopics": {
           "bulk": {
-            "description": "Run bulk monitor actions"
+            "description": "Run bulk monitor actions\n\nPause, start, and update report acceptance, not completion: the API answers success as soon as the write is accepted and carries no operation id. Confirm with `uptimerobot monitors get <id>` before depending on the new state."
           },
           "create": {
             "description": "Create a monitor of a given type"