@uptimerobot/cli 0.2.0 → 1.0.0

package/README.md

@@ -36,6 +36,23 @@ 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:
+
+```sh
+uptimerobot skills install
+```
+
+The CLI shows the exact external command and requires confirmation before handing the terminal to `npx skills`. `npx` may download and execute the third-party `skills` package, which can write skill files into your project or agent directories. The installer prompts for the skills, agents, and installation scope. In a non-interactive environment, run `npx skills add uptimerobot/ai` directly after reviewing it.
+
 ## Authentication
 
 [Create an API key](https://help.uptimerobot.com/en/articles/11620152-how-to-use-uptimerobot-s-api), then save it in your operating system's secure credential store:
@@ -101,6 +118,8 @@ uptimerobot monitors create keyword --help
 uptimerobot incidents comments create --help
 ```
 
+`uptimerobot help <command-or-topic>` is equivalent to the `--help` flag, so `uptimerobot help monitors create` and `uptimerobot monitors create --help` print the same page.
+
 Monitor creation commands expose only the fields relevant to their type and supply the API monitor type automatically. Command help includes accepted values, required fields, defaults, constraints, and examples from the packaged API contract.
 
 Typed flags cover normal use. Full API request bodies remain available when needed:
@@ -111,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:
@@ -132,19 +175,51 @@ Dry-run output contains the final method, path, content type, and body. Recogniz
 
 Interactive terminals use tables by default. Piped, redirected, and agent-driven commands use normalized JSON by default.
 
-| Option           | Output                           |
-| ---------------- | -------------------------------- |
-| `--json`         | Normalized JSON                  |
-| `--format jsonl` | One normalized resource per line |
-| `--format table` | Human-readable table             |
-| `--format plain` | Headerless, tab-separated rows   |
-| `--raw`          | Untouched API response as JSON   |
+| Option             | Output                               |
+| ------------------ | ------------------------------------ |
+| `--json`           | Normalized JSON                      |
+| `--format jsonl`   | One normalized resource per line     |
+| `--format table`   | Human-readable table                 |
+| `--format plain`   | Headerless, tab-separated rows       |
+| `--raw`            | Untouched API response as JSON       |
+| `--reveal-secrets` | Credential-like fields shown in full |
+
+Recognizable credential fields in a response, such as `httpPassword`, print as `[REDACTED]` in every format, and a stderr notice names what was hidden. Pass `--reveal-secrets` to print the values instead. `--raw` skips redaction along with the rest of normalization.
 
 Set `UPTIMEROBOT_OUTPUT` to `json`, `jsonl`, `table`, or `plain` to choose a default. Use `--agent` or `UPTIMEROBOT_AGENT=1` to identify agent execution explicitly. A truthy `CI` environment variable identifies CI execution independently.
 
 Normalized collection JSON contains `items` and `nextCursor`. The CLI does not follow pagination automatically; pass a returned cursor through `--cursor` for the next page. Collection commands also support `--columns` and `--all`. Column selection never changes JSON, JSONL, or raw output, and `--all` may expose sensitive API fields.
 
-Machine-readable failures are emitted as JSON on stderr while stdout remains empty.
+Machine-readable failures are emitted as JSON on stderr. Stdout remains empty, except for `monitors bulk` commands, which print their per-item results on stdout even when the operation failed.
+
+The exit code identifies the failure:
+
+| Exit code | Meaning                                                                             |
+| --------- | ----------------------------------------------------------------------------------- |
+| `0`       | Success                                                                             |
+| `1`       | Generic failure, including a bulk operation where every item failed (`BULK_FAILED`) |
+| `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
 

package/bin/run.js

@@ -13,24 +13,46 @@ 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 } =
+  await import('../dist/lib/command-id.js');
 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();
-  const suggestion = commandSuggestion(process.argv.slice(2));
-  if (
-    suggestion &&
-    typeof error === 'object' &&
-    error !== null &&
-    /^command .+ not found$/.test(error.message ?? '')
-  ) {
-    error.suggestions = [`uptimerobot ${suggestion}`];
+  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.
+    error.message = withConfiguredCommandId(error.message);
+    const suggestion = commandSuggestion(process.argv.slice(2));
+    if (suggestion) error.suggestions = [`uptimerobot ${suggestion}`];
   }
   if (wasErrorHandled(error)) {
     process.exitCode = exitCodeForError(error);

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/help.js

@@ -1,14 +1,26 @@
+import { Args } from '@oclif/core';
 import { loadHelpClass } from '@oclif/core/help';
 import { BaseCommand } from '../lib/base-command.js';
 export default class Help extends BaseCommand {
-    static description = 'Print the command overview, identical to running uptimerobot --help';
+    // A topic is spelled with spaces (`help monitors bulk`), so the subject is
+    // variadic. Declaring an argument at all is what stops oclif from folding the
+    // words into the command id, which is what made `help monitors` fail as
+    // `command help:monitors not found`.
+    static args = {
+        command: Args.string({
+            description: 'Command or topic to describe; omit for the command overview',
+            multiple: true,
+            required: false,
+        }),
+    };
+    static description = 'With no argument, print the command overview, identical to running uptimerobot --help';
     static summary = 'Display help for uptimerobot';
     async run() {
-        await this.parse(Help);
+        const { args } = await this.parse(Help);
         // Loaded the way --help loads it, so both paths honour a custom help class
         // and render the same output.
         const HelpClass = await loadHelpClass(this.config);
         const help = new HelpClass(this.config, this.config.pjson.oclif.helpOptions);
-        await help.showHelp([]);
+        await help.showHelp(args.command ?? []);
     }
 }

package/dist/commands/skills/install.js

@@ -0,0 +1,38 @@
+import { BaseCommand } from '../../lib/base-command.js';
+import { confirmationAvailable, detectInvocationMode, requestConfirmation, } from '../../lib/invocation.js';
+import { runSkillsInstaller, SKILLS_INSTALL_COMMAND } from '../../lib/skills-installer.js';
+export default class SkillsInstall extends BaseCommand {
+    static description = `Run the external skills installer for the UptimeRobot AI skill collection. After confirmation, ${SKILLS_INSTALL_COMMAND} controls the terminal and prompts for skills, agents, and installation scope.`;
+    static summary = 'Install UptimeRobot AI skills';
+    async run() {
+        await this.parse(SkillsInstall);
+        const mode = detectInvocationMode(false);
+        if (!confirmationAvailable(mode)) {
+            return this.fail({
+                code: 'CONFIRMATION_REQUIRED',
+                message: `Interactive confirmation is required. Run ${SKILLS_INSTALL_COMMAND} directly in a terminal.`,
+            }, 2);
+        }
+        const confirmed = await requestConfirmation(`Run ${SKILLS_INSTALL_COMMAND}`, mode);
+        if (!confirmed) {
+            this.logToStderr('Installation cancelled.');
+            return;
+        }
+        try {
+            const exitCode = await runSkillsInstaller();
+            if (exitCode !== 0)
+                process.exitCode = exitCode;
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                'code' in error &&
+                error.code === 'ENOENT') {
+                return this.fail({
+                    code: 'INSTALLER_NOT_FOUND',
+                    message: 'Could not start npx. Install npm and ensure npx is available on PATH.',
+                }, 1);
+            }
+            throw error;
+        }
+    }
+}

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/base-command.js

@@ -1,7 +1,14 @@
 import { Command } from '@oclif/core';
 import { CliFailure, errorEnvelope, exitCodeForError, machineOutputRequested, markErrorHandled, } from './cli-errors.js';
+import { isUnknownCommandMessage, withConfiguredCommandId } from './command-id.js';
 export class BaseCommand extends Command {
     async catch(error) {
+        // The other boundary that turns an error into output. `help <unknown topic>`
+        // raises its unknown-command error inside the command, so it never reaches
+        // the rewrite in bin/run.js and would keep oclif's colon-joined id.
+        if (isUnknownCommandMessage(error.message)) {
+            error.message = withConfiguredCommandId(error.message);
+        }
         const failure = error instanceof CliFailure;
         const machineOutput = machineOutputRequested(this.argv);
         if (!failure && !machineOutput) {

package/dist/lib/command-id.js

@@ -0,0 +1,50 @@
+import { readFileSync } from 'node:fs';
+import { isPlainRecord } from './objects.js';
+/**
+ * oclif builds command ids by joining topics with a colon and reports an
+ * unknown command with that internal spelling, so `uptimerobot monitors lst`
+ * fails with `command monitors:lst not found`. This CLI sets
+ * `oclif.topicSeparator` to a space, so the colon form is a syntax it does not
+ * accept, and echoing it back teaches the wrong thing.
+ *
+ * Two spellings reach the user:
+ *
+ * - `command <id> not found`  — Config#runCommand, for an unroutable argv
+ * - `Command <id> not found.` — Help#showHelp, for an unknown help subject
+ *
+ * Only the id is rewritten. Replacing every colon in the message would also
+ * rewrite colons that belong to the prose, such as a URL or a `min: 5` bound,
+ * so the id is captured on its own and substituted in place. The capture is
+ * narrowed to the characters a command id can contain, which keeps a
+ * URL-shaped argument intact. A message that is not one of the two forms is
+ * returned untouched.
+ */
+const UNKNOWN_COMMAND = /^([Cc]ommand )([\w:-]+)( not found\.?)$/;
+export function isUnknownCommandMessage(message) {
+    return UNKNOWN_COMMAND.test(message);
+}
+export function withConfiguredCommandId(message) {
+    return message.replace(UNKNOWN_COMMAND, (_full, prefix, id, suffix) => `${prefix}${id.replaceAll(':', topicSeparator())}${suffix}`);
+}
+let cachedSeparator;
+/**
+ * The `oclif.topicSeparator` the CLI is configured with, read from the same
+ * manifest oclif itself reads so the two can never disagree. Falls back to
+ * oclif's own default, which leaves the id unchanged.
+ */
+function topicSeparator() {
+    if (cachedSeparator !== undefined)
+        return cachedSeparator;
+    cachedSeparator = ':';
+    try {
+        const manifest = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+        const oclif = isPlainRecord(manifest) ? manifest.oclif : undefined;
+        const separator = isPlainRecord(oclif) ? oclif.topicSeparator : undefined;
+        if (typeof separator === 'string' && separator.length > 0)
+            cachedSeparator = separator;
+    }
+    catch {
+        // An unreadable manifest must not replace the error being reported.
+    }
+    return cachedSeparator;
+}

package/dist/lib/command-suggestions.js

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

package/dist/lib/form-body.js

@@ -0,0 +1,55 @@
+/**
+ * The multipart encoder, used only when a request carries a `--file` upload.
+ * Every other request is sent as JSON, which preserves types, nesting, and
+ * empty arrays that multipart cannot express.
+ *
+ * The API decodes multipart bodies with multer, whose `append-field` parser
+ * dictates each rule below. Keeping all of them here means there is a single
+ * place to change if the API ever documents a different wire format.
+ *
+ *   - Arrays are appended once per item under a `key[]` name. The bracket
+ *     suffix makes the parser build an array even for one item; a bare
+ *     repeated `key` only becomes an array from the second occurrence onwards,
+ *     so a single `monitorIds` would arrive as a string and be rejected.
+ *   - Nested objects are flattened to dotted paths (`customSettings.page.theme`)
+ *     rather than bracketed ones. A dotted name stays a literal key on the
+ *     request body and is reassembled by the API; bracket notation would build
+ *     a real nested object and change which validators run against it.
+ *   - Scalars are sent as `String(value)`, because multipart has no types.
+ *   - `null` and `undefined` are dropped; multipart cannot represent them.
+ *   - Empty arrays are rejected. `key[]=` decodes to `['']`, and for a numeric
+ *     ID list that becomes `[0]` — the API's "every monitor" sentinel, which is
+ *     the opposite of clearing the list.
+ */
+import { isPlainRecord } from './objects.js';
+import { RequestInputError } from './request-input-error.js';
+export function encodeFormBody(body, files = []) {
+    const form = new FormData();
+    appendValue(form, '', body);
+    for (const file of files)
+        form.append(file.field, file.content, file.filename);
+    return form;
+}
+function appendValue(form, path, value) {
+    if (value === undefined || value === null)
+        return;
+    if (Array.isArray(value)) {
+        if (value.length === 0) {
+            throw new RequestInputError(path, 'a non-empty array', `${path} cannot be cleared in a request that uploads a file. ` +
+                `Re-run without --file to send an empty ${path}, or split this into two commands.`);
+        }
+        for (const item of value)
+            form.append(`${path}[]`, stringifyFormValue(item));
+        return;
+    }
+    if (isPlainRecord(value)) {
+        for (const [key, child] of Object.entries(value)) {
+            appendValue(form, path === '' ? key : `${path}.${key}`, child);
+        }
+        return;
+    }
+    form.append(path, stringifyFormValue(value));
+}
+function stringifyFormValue(value) {
+    return typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value);
+}

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/invocation.js

@@ -19,12 +19,15 @@ export function agentEnvironmentDetected(env = process.env) {
 export function detectInvocationMode(agentFlag, env = process.env) {
     return agentFlag || agentEnvironmentDetected(env) ? 'agent' : 'human';
 }
-export async function requestConfirmation(operation, mode) {
-    if (mode === 'agent' || !process.stdin.isTTY || !process.stdout.isTTY)
+export function confirmationAvailable(mode) {
+    return mode === 'human' && process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
+export async function requestConfirmation(summary, mode) {
+    if (!confirmationAvailable(mode))
         return false;
     const reader = createInterface({ input: process.stdin, output: process.stderr });
     try {
-        const answer = await reader.question(`${operation.summary}. Continue? [y/N] `);
+        const answer = await reader.question(`${summary}. Continue? [y/N] `);
         return /^(y|yes)$/i.test(answer.trim());
     }
     finally {

package/dist/lib/operation-command.js

@@ -1,6 +1,7 @@
 import { Args, Flags } from '@oclif/core';
 import { createApiClient } from '../api/client.js';
 import { exitCodeFor, normalizeApiError } from '../api/errors.js';
+import { bulkFailure, bulkFailureError, bulkFailureExitCode } from '../output/bulk-failure.js';
 import { columnsFor, parseColumnsFlag } from '../output/columns.js';
 import { normalizeResult } from '../output/normalize-result.js';
 import { paginationNotice } from '../output/pagination-notice.js';
@@ -12,11 +13,15 @@ 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';
 import { curatedRequestBodyField, curatedRequestExampleBody } from './request-curation.js';
 import { synthesizedRequestExample } from './request-example.js';
-import { buildRequestBody, buildUrl, RequestInputError } from './request.js';
+import { buildRequestBody, buildUrl } from './request.js';
+import { RequestInputError } from './request-input-error.js';
 import { redactRequestPreview } from './request-preview.js';
 export function createOperationCommand(operation, options = {}) {
     const pathParameters = operation.parameters.filter((parameter) => parameter.in === 'path');
@@ -31,13 +36,12 @@ export function createOperationCommand(operation, options = {}) {
                 description: 'JSON request body, @file, or - for stdin',
                 helpValue: '<json|@file|->',
             }),
-            ...(operation.contentTypes.includes('application/json')
-                ? {
-                    'dry-run': Flags.boolean({
-                        description: 'Compile and validate the request as JSON without authentication or networking',
-                    }),
-                }
-                : {}),
+            // Every operation with a request body compiles that body as JSON
+            // unless --file forces multipart, so --dry-run is always offered
+            // here; the guard in run() rejects the multipart case.
+            'dry-run': Flags.boolean({
+                description: 'Compile and validate the request as JSON without authentication or networking',
+            }),
             ...(operation.contentTypes.includes('multipart/form-data')
                 ? {
                     file: Flags.string({
@@ -55,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)),
@@ -90,6 +95,9 @@ export function createOperationCommand(operation, options = {}) {
         raw: Flags.boolean({
             description: 'Emit the untouched API response as JSON; implies --format json',
         }),
+        'reveal-secrets': Flags.boolean({
+            description: 'Show credential-like response fields instead of redacting them',
+        }),
         ...requestBodyFlags,
         ...bodyFieldFlags,
         ...Object.fromEntries(optionParameters.map((parameter) => [flagName(parameter.name), flagForParameter(parameter)])),
@@ -97,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;
@@ -201,7 +209,7 @@ Canonical command: ${options.canonicalCommand}`
                 return;
             }
             if (operation.destructive && flags.confirm !== true) {
-                const confirmed = await requestConfirmation(operation, mode);
+                const confirmed = await requestConfirmation(operation.summary, mode);
                 if (!confirmed) {
                     const error = {
                         code: 'CONFIRMATION_REQUIRED',
@@ -249,20 +257,41 @@ 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);
-            const output = formatOutput(outputFormat, normalized, {
+            // --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
+                ? undefined
+                : redactSecrets(normalized);
+            const presented = redaction === undefined ? normalized : redaction.value;
+            const output = formatOutput(outputFormat, presented, {
                 allColumns: flags.all === true,
                 columns: requestedColumns ?? (flags.all === true ? undefined : defaultColumns),
             });
             if (output !== undefined)
                 this.log(output);
-            const notice = paginationNotice(outputFormat, normalized);
+            // Reported after the results are on stdout, so callers keep the per-item detail.
+            const failure = bulkFailure(payload);
+            if (failure)
+                return this.fail(bulkFailureError(failure), bulkFailureExitCode(failure));
+            const notice = paginationNotice(outputFormat, presented);
             if (notice)
                 this.logToStderr(notice.message);
+            if (redaction !== undefined && redaction.redacted.length > 0) {
+                this.logToStderr(redactionNotice(redaction.redacted));
+            }
         }
     }
     return OperationCommand;
 }
+const NOTICE_PATH_LIMIT = 3;
+function redactionNotice(paths) {
+    const shown = paths.slice(0, NOTICE_PATH_LIMIT);
+    const remainder = paths.length - shown.length;
+    const list = remainder > 0 ? `${shown.join(', ')}, and ${remainder} more` : shown.join(', ');
+    return `Redacted credential-like response fields: ${list}. Re-run with --reveal-secrets to show them.`;
+}
 function flagForBodyField(field) {
     const options = {
         ...(field.aliases ? { aliases: [...field.aliases] } : {}),

package/dist/lib/redact-secrets.js

@@ -0,0 +1,46 @@
+import { isRecord } from './objects.js';
+import { isSensitiveFieldName } from './sensitive-fields.js';
+const REDACTED = '[REDACTED]';
+/**
+ * Replaces credential-like fields anywhere in a value, recursing through both
+ * objects and arrays. Deliberately shape-agnostic: the same pass covers dry-run
+ * request bodies and normalized API responses, whose resources nest under
+ * `items[]`.
+ */
+export function redactSecrets(value) {
+    const redacted = [];
+    return { value: redactValue(value, [], redacted), redacted };
+}
+function redactValue(value, path, redacted) {
+    if (Array.isArray(value)) {
+        return value.map((item, index) => redactValue(item, [...path, String(index)], 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) || 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-input-error.js

@@ -0,0 +1,16 @@
+/**
+ * Raised while compiling a request body, before anything is sent. Carries the
+ * offending field path so the CLI can report it as a machine-readable error.
+ */
+export class RequestInputError extends Error {
+    path;
+    expected;
+    code = 'INVALID_INPUT';
+    exitCode = 2;
+    constructor(path, expected, message = `Invalid ${path}: expected ${expected}.`) {
+        super(message);
+        this.path = path;
+        this.expected = expected;
+        this.name = 'RequestInputError';
+    }
+}

package/dist/lib/request-preview.js

@@ -1,25 +1,6 @@
-import { isRecord } from './objects.js';
-import { isSensitiveFieldName } from './sensitive-fields.js';
-const REDACTED = '[REDACTED]';
+import { redactSecrets } from './redact-secrets.js';
+/** Dry-run view of a compiled request body, with credential fields replaced. */
 export function redactRequestPreview(body) {
-    const redacted = [];
-    return { body: redactValue(body, [], redacted), redacted };
-}
-function redactValue(value, path, redacted) {
-    if (Array.isArray(value)) {
-        return value.map((item, index) => redactValue(item, [...path, String(index)], redacted));
-    }
-    if (!isRecord(value))
-        return value;
-    return Object.fromEntries(Object.entries(value).map(([key, child]) => {
-        const childPath = [...path, key];
-        if (isSensitiveFieldName(key)) {
-            redacted.push(formatPath(childPath));
-            return [key, REDACTED];
-        }
-        return [key, redactValue(child, childPath, redacted)];
-    }));
-}
-function formatPath(segments) {
-    return segments.reduce((path, segment) => /^\d+$/.test(segment) ? `${path}[${segment}]` : path ? `${path}.${segment}` : segment, '');
+    const { redacted, value } = redactSecrets(body);
+    return { body: value, redacted };
 }

package/dist/lib/request.js

@@ -1,19 +1,9 @@
 import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
+import { encodeFormBody } from './form-body.js';
 import { assignPath, isPlainRecord, valueAtPath } from './objects.js';
 import { cliRequestDefaults, curatedRequestBodyFields, requestCurationIssue, } from './request-curation.js';
-export class RequestInputError extends Error {
-    path;
-    expected;
-    code = 'INVALID_INPUT';
-    exitCode = 2;
-    constructor(path, expected, message = `Invalid ${path}: expected ${expected}.`) {
-        super(message);
-        this.path = path;
-        this.expected = expected;
-        this.name = 'RequestInputError';
-    }
-}
+import { RequestInputError } from './request-input-error.js';
 export function buildUrl(operation, input, apiUrl) {
     let path = operation.path;
     for (const parameter of operation.parameters.filter((candidate) => candidate.in === 'path')) {
@@ -54,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) {
@@ -70,19 +64,21 @@ export async function buildRequestBody(operation, flags, headers) {
     }
     applyRequestCuration(operation, objectBody);
     validateBodyFields(bodyFields, objectBody);
-    if (operation.contentTypes.includes('multipart/form-data')) {
-        const form = new FormData();
-        appendFormValues(form, objectBody);
-        for (const file of files) {
-            const [field, path] = splitAssignment(file, '--file');
-            const bytes = await readFile(path);
-            form.append(field, new Blob([bytes]), basename(path));
-        }
-        return form;
-    }
+    // Multipart exists only to carry file uploads. The operations that document
+    // it accept JSON too, and JSON is the only encoding that keeps numeric types,
+    // nested objects, and empty arrays intact — so it is the default.
+    if (files.length > 0)
+        return encodeFormBody(objectBody, await readFileParts(files));
     headers.set('content-type', 'application/json');
     return JSON.stringify(objectBody);
 }
+async function readFileParts(files) {
+    return Promise.all(files.map(async (file) => {
+        const [field, path] = splitAssignment(file, '--file');
+        const bytes = await readFile(path);
+        return { content: new Blob([bytes]), field, filename: basename(path) };
+    }));
+}
 function applyRequestCuration(operation, body) {
     for (const [path, value] of Object.entries(cliRequestDefaults(operation))) {
         if (valueAtPath(body, path) === undefined)
@@ -92,17 +88,6 @@ function applyRequestCuration(operation, body) {
     if (issue)
         throw new RequestInputError(issue.path, issue.expected);
 }
-function appendFormValues(form, values) {
-    for (const [key, value] of Object.entries(values)) {
-        if (Array.isArray(value))
-            value.forEach((item) => form.append(key, stringifyFormValue(item)));
-        else if (value !== undefined && value !== null)
-            form.append(key, stringifyFormValue(value));
-    }
-}
-function stringifyFormValue(value) {
-    return typeof value === 'object' ? JSON.stringify(value) : String(value);
-}
 async function readBodyFlag(value) {
     const source = value === '-'
         ? await readStandardInput()
@@ -130,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/dist/lib/skills-installer.js

@@ -0,0 +1,19 @@
+import { spawn } from 'node:child_process';
+import { constants } from 'node:os';
+const SKILLS_INSTALL_ARGS = ['skills', 'add', 'uptimerobot/ai'];
+export const SKILLS_INSTALL_COMMAND = ['npx', ...SKILLS_INSTALL_ARGS].join(' ');
+export async function runSkillsInstaller() {
+    return new Promise((resolve, reject) => {
+        const windows = process.platform === 'win32';
+        const executable = windows ? (process.env.ComSpec ?? 'cmd.exe') : 'npx';
+        const args = windows
+            ? ['/d', '/s', '/c', 'npx.cmd', ...SKILLS_INSTALL_ARGS]
+            : SKILLS_INSTALL_ARGS;
+        const child = spawn(executable, args, { stdio: 'inherit' });
+        child.once('error', reject);
+        child.once('close', (exitCode, signal) => {
+            const signalNumber = signal === null ? undefined : constants.signals[signal];
+            resolve(exitCode ?? (signalNumber === undefined ? 1 : 128 + signalNumber));
+        });
+    });
+}

package/dist/output/bulk-failure.js

@@ -0,0 +1,42 @@
+import { isPlainRecord } from '../lib/objects.js';
+/**
+ * Detects a wholly or partially failed bulk operation. Bulk endpoints answer
+ * HTTP 201 even when every item failed, so the response body is the only
+ * signal that the command did not do what was asked. Returns undefined when
+ * the payload is not a bulk response or when nothing failed, so any returned
+ * value is a failure the caller must report.
+ */
+export function bulkFailure(payload) {
+    if (!isPlainRecord(payload))
+        return undefined;
+    const results = payload.results;
+    if (!Array.isArray(results))
+        return undefined;
+    const items = results.filter((item) => isPlainRecord(item) && item.status === 'error');
+    // totalError is optional in practice, so per-item statuses stay authoritative.
+    const reported = typeof payload.totalError === 'number' ? payload.totalError : 0;
+    const failed = Math.max(reported, items.length);
+    if (failed === 0)
+        return undefined;
+    return {
+        failed,
+        items,
+        succeeded: typeof payload.totalSuccess === 'number'
+            ? payload.totalSuccess
+            : results.length - items.length,
+    };
+}
+export function bulkFailureError(failure) {
+    const counts = `${failure.failed} failed, ${failure.succeeded} succeeded`;
+    const total = failure.succeeded === 0;
+    return {
+        code: total ? 'BULK_FAILED' : 'BULK_PARTIAL_FAILURE',
+        details: failure.items,
+        message: total
+            ? `The bulk operation failed for every item (${counts}).`
+            : `The bulk operation partially failed (${counts}).`,
+    };
+}
+export function bulkFailureExitCode(failure) {
+    return failure.succeeded === 0 ? 1 : 3;
+}

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.2.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,13 +109,24 @@
         "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"
           },
           "stats": {
-            "description": "Query monitor statistics"
+            "description": "Query monitor statistics",
+            "subtopics": {
+              "response-time": {
+                "description": "Query response time statistics overall or by region"
+              }
+            }
           }
         }
       },
+      "skills": {
+        "description": "Install UptimeRobot AI skills"
+      },
       "status-pages": {
         "description": "Manage public status pages",
         "subtopics": {