uptimer-cli 0.0.0-stage → 0.2.0

package/dist/help.js

@@ -0,0 +1,161 @@
+const example = (value) => JSON.stringify(value, null, 2)
+    .split('\n')
+    .map((line) => `    ${line}`)
+    .join('\n');
+const HTTP_MONITOR = example({
+    name: 'Production API',
+    type: 'http',
+    target: 'https://api.example.com/health',
+    interval_sec: 60,
+    timeout_ms: 5000,
+    http_method: 'GET',
+    expected_status_json: [200],
+});
+const TCP_MONITOR = example({
+    name: 'Database Port',
+    type: 'tcp',
+    target: 'db.example.com:5432',
+    interval_sec: 60,
+    timeout_ms: 5000,
+});
+const WEBHOOK_CHANNEL = example({
+    name: 'Operations Webhook',
+    type: 'webhook',
+    config_json: {
+        preset: 'custom',
+        url: 'https://hooks.example.com/uptimer',
+        method: 'POST',
+        payload_type: 'json',
+        payload_template: { text: '{{message}}' },
+    },
+});
+const TELEGRAM_CHANNEL = example({
+    name: 'Telegram Alerts',
+    type: 'webhook',
+    config_json: {
+        preset: 'telegram',
+        chat_id: '@status_channel',
+        bot_token_secret_ref: 'UPTIMER_TELEGRAM_BOT_TOKEN',
+    },
+});
+const STATUS_PAGE = example({
+    slug: 'public-status',
+    name: 'Public Status',
+    title: 'Service status',
+    is_public: true,
+    monitor_ids: [1, 2],
+});
+const SETTINGS = example({
+    site_timezone: 'Asia/Shanghai',
+    site_locale: 'en',
+    retention_check_results_days: 7,
+});
+const UPTIME_RATING = example({ uptime_rating_level: 4 });
+export function getHelpText() {
+    return `Uptimer Agent Configuration CLI (uptimer-cli)
+
+A CLI for coding agents and terminal automation to manage Uptimer
+configuration via existing Admin APIs.
+
+USAGE:
+  uptimer <resource> <command> [arguments...] [options...]
+
+ENVIRONMENT VARIABLES:
+  UPTIMER_URL          Instance origin URL (e.g. https://uptimer.workers.dev or http://localhost:8787).
+                       HTTPS required for remote origins. HTTP only allowed on loopback (localhost, 127.0.0.1, [::1]).
+                       Must be a root path without query, fragment, or userinfo.
+  UPTIMER_ADMIN_TOKEN  Bearer token for Admin API authentication.
+
+COMMANDS:
+  monitors
+    list [--limit N]                   List monitors (limit 1-200, default 50).
+    create --file <file|->             Create a new monitor from JSON payload.
+    update <id> --file <file|->        Update an existing monitor (PATCH semantics).
+    delete <id>                        Delete a monitor by ID.
+    pause <id>                         Pause monitoring for a monitor.
+    resume <id>                        Resume monitoring for a monitor.
+  monitors groups
+    reorder --file <file|->            Reorder monitor groups.
+    assign --file <file|->             Assign monitors to a group.
+
+  notification-channels
+    list [--limit N]                   List notification channels (limit 1-200, default 50).
+    create --file <file|->             Create a notification channel.
+    update <id> --file <file|->        Update a notification channel (PATCH semantics).
+    delete <id>                        Delete a notification channel by ID.
+
+  status-pages
+    list                               List all status pages.
+    create --file <file|->             Create a status page.
+    update <id> --file <file|->        Update a status page (PATCH semantics).
+    delete <id>                        Delete a status page by ID.
+
+  settings
+    get                                Retrieve current global settings.
+    update --file <file|->             Update global settings (PATCH semantics).
+  settings uptime-rating
+    get                                Retrieve uptime rating level (1-5).
+    update --file <file|->             Update uptime rating level (PUT).
+
+  skill
+    install [--dir <path>] [--force]   Install the agent skill locally (default dir: ./skills).
+
+OPTIONS:
+  --file <path|->     Path to a UTF-8 JSON file containing the payload object, or '-' for stdin.
+  --limit <number>    Max items to return for list operations (1-200, default 50).
+  --dir <path>        Base directory for "skill install"; the skill is written to <path>/uptimer-cli.
+  --force             Replace an existing "skill install" target.
+  --help, -h          Show this help text without requiring credentials.
+
+PAYLOAD FORMAT:
+  All payload inputs via --file must be valid UTF-8 JSON objects.
+  PATCH update operations preserve field values; explicit null, false, 0, [], and omissions are respected.
+  Each option may be given at most once.
+
+BOUNDED LIST INVENTORY:
+  List commands return up to --limit items (1-200, default 50).
+  These listings are explicitly bounded slices and do not claim to represent a complete inventory.
+
+PAYLOAD EXAMPLES:
+  HTTP Monitor:
+${HTTP_MONITOR}
+
+  TCP Monitor (target is host:port):
+${TCP_MONITOR}
+
+  Custom Webhook Channel:
+${WEBHOOK_CHANNEL}
+
+  Telegram Channel (type stays "webhook"):
+${TELEGRAM_CHANNEL}
+
+  Status Page:
+${STATUS_PAGE}
+
+  Global Settings:
+${SETTINGS}
+
+  Uptime Rating:
+${UPTIME_RATING}
+
+EXIT CODES & OUTPUT:
+  0: Success. Single JSON value printed to stdout followed by newline. (Help is the only human text).
+  1: Transport, HTTP, deadline, redirect, or response-contract failure. Emits JSON error envelope to stderr.
+  2: Usage, input, local validation, or environment configuration failure. Emits JSON error envelope to stderr.
+
+SECURITY & REDACTION:
+  Output is a sanitized/redacted management view: credentials, header/body blobs, and
+  notification channel URLs, headers, and payload templates are replaced with [REDACTED].
+  Returned configuration is administrative data and should not be published.
+`;
+}
+// Payload examples are contract surfaces; keep them valid against the server schemas.
+export const HELP_PAYLOAD_EXAMPLES = {
+    httpMonitor: HTTP_MONITOR,
+    tcpMonitor: TCP_MONITOR,
+    webhookChannel: WEBHOOK_CHANNEL,
+    telegramChannel: TELEGRAM_CHANNEL,
+    statusPage: STATUS_PAGE,
+    settings: SETTINGS,
+    uptimeRating: UPTIME_RATING,
+};

package/dist/index.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { parseArgs, executeCommand } from "./commands.js";
+import { CliError, formatErrorEnvelope } from "./errors.js";
+import { getHelpText } from "./help.js";
+export async function run(argvOrOptions, envParam, ioParam, fetchParam, timeoutParam) {
+    let argv;
+    let env;
+    let stdout;
+    let stderr;
+    let stdin;
+    let fetchFn;
+    let timeoutMs;
+    if (Array.isArray(argvOrOptions)) {
+        argv = argvOrOptions;
+        env = envParam ?? process.env;
+        stdout = ioParam?.stdout ?? process.stdout;
+        stderr = ioParam?.stderr ?? process.stderr;
+        stdin = ioParam?.stdin ?? process.stdin;
+        fetchFn = fetchParam;
+        timeoutMs = timeoutParam;
+    }
+    else {
+        argv = argvOrOptions.argv;
+        env = argvOrOptions.env ?? process.env;
+        stdout = argvOrOptions.stdout ?? process.stdout;
+        stderr = argvOrOptions.stderr ?? process.stderr;
+        stdin = argvOrOptions.stdin ?? process.stdin;
+        fetchFn = argvOrOptions.fetchFn ?? argvOrOptions.fetch;
+        timeoutMs = argvOrOptions.timeoutMs;
+    }
+    try {
+        const parsed = parseArgs(argv);
+        if (parsed.isHelp || (parsed.positionals.length === 1 && parsed.positionals[0] === 'help')) {
+            stdout.write(getHelpText());
+            return 0;
+        }
+        const result = await executeCommand(parsed, { env, fetchFn, timeoutMs }, stdin);
+        stdout.write(JSON.stringify(result) + '\n');
+        return 0;
+    }
+    catch (err) {
+        const exitCode = err instanceof CliError ? err.exitCode : 1;
+        const envelope = formatErrorEnvelope(err, env.UPTIMER_ADMIN_TOKEN);
+        stderr.write(JSON.stringify(envelope) + '\n');
+        return exitCode;
+    }
+}
+// Auto-run if executed directly as script
+const currentFile = fileURLToPath(import.meta.url);
+const entryFile = process.argv[1] ? realpathSync(process.argv[1]) : '';
+if (entryFile === currentFile) {
+    run(process.argv.slice(2)).then((code) => {
+        process.exit(code);
+    });
+}

package/dist/input.js

@@ -0,0 +1,49 @@
+import * as fs from 'node:fs/promises';
+import { CliError } from "./errors.js";
+export async function readJsonPayload(filePath, stdin) {
+    let content = '';
+    if (filePath === '-') {
+        if (!stdin) {
+            throw new CliError(2, 'INVALID_ARGUMENT', 'No stdin stream available to read payload');
+        }
+        const chunks = [];
+        try {
+            for await (const chunk of stdin) {
+                if (typeof chunk === 'string') {
+                    chunks.push(Buffer.from(chunk, 'utf8'));
+                }
+                else {
+                    chunks.push(chunk);
+                }
+            }
+            content = Buffer.concat(chunks).toString('utf8');
+        }
+        catch {
+            throw new CliError(2, 'INVALID_ARGUMENT', 'Failed to read payload from stdin');
+        }
+    }
+    else {
+        try {
+            content = await fs.readFile(filePath, 'utf8');
+        }
+        catch (err) {
+            // Report the OS error code only; messages can embed path or input details.
+            const code = err?.code;
+            const reason = typeof code === 'string' ? ` (${code})` : '';
+            throw new CliError(2, 'INVALID_ARGUMENT', `Failed to read payload file "${filePath}"${reason}`);
+        }
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (err) {
+        // `JSON.parse` messages quote the offending input, which can hold secrets.
+        const position = /at position (\d+)/.exec(err instanceof Error ? err.message : '')?.[1];
+        throw new CliError(2, 'INVALID_ARGUMENT', `Malformed JSON in payload${position ? ` at position ${position}` : ''}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new CliError(2, 'INVALID_ARGUMENT', 'Payload body must be a JSON object');
+    }
+    return parsed;
+}

package/dist/redact.js

@@ -0,0 +1,49 @@
+const SENSITIVE_KEYS = new Set([
+    'authorization',
+    'proxy-authorization',
+    'cookie',
+    'set-cookie',
+    'bot_token',
+    'bot_token_encrypted',
+    'password',
+    'token',
+    'secret',
+    'api_key',
+]);
+// Monitor config blobs: arbitrary header/body values can carry credentials.
+const REDACT_ENTIRE_VALUE_KEYS = new Set(['http_headers', 'http_headers_json', 'http_body']);
+// Notification channel payloads arrive as `config_json` with the same shape as `config`.
+const CONFIG_CONTAINER_KEYS = new Set(['config', 'config_json']);
+const CONFIG_SENSITIVE_KEYS = new Set(['headers', 'url', 'payload_template']);
+function withoutToken(value, adminToken) {
+    return adminToken && adminToken.length > 0 ? value.split(adminToken).join('[REDACTED]') : value;
+}
+export function redactCredentials(value, adminToken, inConfig = false) {
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value === 'string') {
+        return withoutToken(value, adminToken);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => redactCredentials(item, adminToken, inConfig));
+    }
+    if (typeof value === 'object') {
+        const result = {};
+        for (const [rawKey, rawValue] of Object.entries(value)) {
+            // Keys are attacker-controlled too: a reflected token can arrive as a key.
+            const key = withoutToken(rawKey, adminToken);
+            const lower = key.toLowerCase();
+            if (REDACT_ENTIRE_VALUE_KEYS.has(lower) ||
+                SENSITIVE_KEYS.has(lower) ||
+                (inConfig && CONFIG_SENSITIVE_KEYS.has(lower))) {
+                result[key] = '[REDACTED]';
+            }
+            else {
+                result[key] = redactCredentials(rawValue, adminToken, CONFIG_CONTAINER_KEYS.has(lower));
+            }
+        }
+        return result;
+    }
+    return value;
+}

package/dist/skill.js

@@ -0,0 +1,42 @@
+import { copyFile, mkdir, readdir, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { CliError } from "./errors.js";
+const SKILL_NAME = 'uptimer-cli';
+async function isFile(path) {
+    try {
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+// A repository checkout owns the source at the repo root; packaged installs carry `skill/`.
+// Checkout first so a stale build copy never shadows the edited skill.
+async function resolveSkillSource() {
+    const candidates = [
+        fileURLToPath(new URL('../../../skills/uptimer-cli', import.meta.url)),
+        fileURLToPath(new URL('../skill', import.meta.url)),
+    ];
+    for (const candidate of candidates) {
+        if (await isFile(join(candidate, 'SKILL.md')))
+            return candidate;
+    }
+    throw new CliError(1, 'SKILL_NOT_FOUND', 'Bundled uptimer-cli skill files are missing from this installation');
+}
+export async function installSkill(input) {
+    const source = await resolveSkillSource();
+    const target = join(input.dir, SKILL_NAME);
+    if (!input.force && (await isFile(join(target, 'SKILL.md')))) {
+        throw new CliError(2, 'SKILL_ALREADY_INSTALLED', `Skill already installed at ${target}; pass --force to replace it`);
+    }
+    const references = await readdir(join(source, 'references'))
+        .then((names) => names.filter((name) => name.endsWith('.md')))
+        .catch(() => []);
+    await mkdir(join(target, 'references'), { recursive: true });
+    const files = ['SKILL.md', ...references.map((name) => join('references', name))];
+    for (const file of files) {
+        await copyFile(join(source, file), join(target, file));
+    }
+    return { installed: true, skill: SKILL_NAME, path: target, files };
+}

package/dist/transport.js

@@ -0,0 +1,171 @@
+import { z } from 'zod';
+import { CliError } from "./errors.js";
+import { redactCredentials } from "./redact.js";
+export function validateEnvironment(env = process.env) {
+    const rawUrl = env.UPTIMER_URL?.trim();
+    if (!rawUrl) {
+        throw new CliError(2, 'CONFIGURATION_ERROR', 'UPTIMER_URL environment variable is required');
+    }
+    let parsedUrl;
+    try {
+        parsedUrl = new URL(rawUrl);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new CliError(2, 'INVALID_ARGUMENT', `Invalid UPTIMER_URL: ${msg}`);
+    }
+    if (parsedUrl.username || parsedUrl.password) {
+        throw new CliError(2, 'INVALID_ARGUMENT', 'UPTIMER_URL must not contain userinfo');
+    }
+    if (parsedUrl.search) {
+        throw new CliError(2, 'INVALID_ARGUMENT', 'UPTIMER_URL must not contain query parameters');
+    }
+    if (parsedUrl.hash) {
+        throw new CliError(2, 'INVALID_ARGUMENT', 'UPTIMER_URL must not contain URL fragments');
+    }
+    if (parsedUrl.pathname !== '' && parsedUrl.pathname !== '/') {
+        throw new CliError(2, 'INVALID_ARGUMENT', 'UPTIMER_URL must be a root path without subpaths');
+    }
+    const hostname = parsedUrl.hostname.toLowerCase();
+    const protocol = parsedUrl.protocol.toLowerCase();
+    if (protocol === 'https:') {
+        // HTTPS is allowed everywhere
+    }
+    else if (protocol === 'http:') {
+        const isLoopback = hostname === 'localhost' ||
+            hostname === '127.0.0.1' ||
+            hostname === '[::1]' ||
+            hostname === '::1';
+        if (!isLoopback) {
+            throw new CliError(2, 'INVALID_ARGUMENT', 'Insecure HTTP origins are only permitted for loopback addresses (localhost, 127.0.0.1, [::1])');
+        }
+    }
+    else {
+        throw new CliError(2, 'INVALID_ARGUMENT', `Unsupported URL protocol: "${protocol}"`);
+    }
+    const adminToken = env.UPTIMER_ADMIN_TOKEN?.trim();
+    if (!adminToken) {
+        throw new CliError(2, 'CONFIGURATION_ERROR', 'UPTIMER_ADMIN_TOKEN environment variable is required');
+    }
+    return {
+        origin: parsedUrl.origin,
+        adminToken,
+    };
+}
+// Transport failures keep their stable error code and drop the message, which can
+// embed request detail; the CLI must never echo transport text verbatim.
+function networkError(err, action) {
+    const code = err?.code;
+    const reason = typeof code === 'string' ? ` (${code})` : '';
+    return new CliError(1, 'NETWORK_ERROR', `${action}${reason}`);
+}
+function discardBody(response) {
+    // Fire-and-forget: a stream whose cancellation never settles must not block exit.
+    void response.body?.cancel().catch(() => { });
+}
+// Read the body ourselves so a deadline can cancel the stream; `response.text()`
+// would keep the reader locked and leak a stalled body.
+async function readBody(response, deadline) {
+    if (!response.body) {
+        return await Promise.race([response.text(), deadline]);
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let text = '';
+    try {
+        for (;;) {
+            const { done, value } = await Promise.race([reader.read(), deadline]);
+            if (done)
+                break;
+            if (value)
+                text += decoder.decode(value, { stream: true });
+        }
+        return text + decoder.decode();
+    }
+    catch (err) {
+        void reader.cancel().catch(() => { });
+        throw err;
+    }
+}
+export async function executeApiRequest(method, path, payload, envelopeSchema, options = {}) {
+    const { origin, adminToken } = validateEnvironment(options.env);
+    const fetchFn = options.fetchFn ?? globalThis.fetch;
+    const timeoutMs = options.timeoutMs ?? 30000;
+    const url = `${origin}/api/v1/admin${path}`;
+    const controller = new AbortController();
+    // One deadline covers the request and the whole response body; the injected
+    // fetch may ignore the signal, so the body read races this promise too.
+    let timer;
+    const deadline = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new CliError(1, 'TIMEOUT', 'Request deadline exceeded'));
+        }, timeoutMs);
+    });
+    deadline.catch(() => {
+        // The race may settle on another branch first; keep the deadline rejection handled.
+    });
+    try {
+        let response;
+        try {
+            const headers = {
+                Authorization: `Bearer ${adminToken}`,
+            };
+            const body = payload === undefined ? undefined : JSON.stringify(payload);
+            const init = { method, headers, redirect: 'manual', signal: controller.signal };
+            if (body !== undefined) {
+                headers['Content-Type'] = 'application/json';
+                init.body = body;
+            }
+            response = await Promise.race([fetchFn(url, init), deadline]);
+        }
+        catch (err) {
+            if (err instanceof CliError)
+                throw err;
+            throw networkError(err, 'Network request failed');
+        }
+        if (response.type === 'opaqueredirect' || (response.status >= 300 && response.status < 400)) {
+            discardBody(response);
+            throw new CliError(1, 'REDIRECT_REJECTED', 'HTTP redirects are not allowed', response.status);
+        }
+        let text;
+        try {
+            text = await readBody(response, deadline);
+        }
+        catch (err) {
+            if (err instanceof CliError)
+                throw err;
+            throw networkError(err, 'Failed reading response body');
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            if (response.status >= 400) {
+                throw new CliError(1, 'HTTP_ERROR', response.statusText || `HTTP ${response.status}`, response.status);
+            }
+            throw new CliError(1, 'INVALID_RESPONSE', 'Response body is not valid JSON', response.status);
+        }
+        if (response.status >= 400) {
+            const errorBody = parsed?.error;
+            if (errorBody && typeof errorBody === 'object') {
+                const code = typeof errorBody.code === 'string' ? errorBody.code : 'HTTP_ERROR';
+                const message = typeof errorBody.message === 'string'
+                    ? errorBody.message
+                    : response.statusText || `HTTP ${response.status}`;
+                throw new CliError(1, code, message, response.status);
+            }
+            throw new CliError(1, 'HTTP_ERROR', response.statusText || `HTTP ${response.status}`, response.status);
+        }
+        const envelopeResult = envelopeSchema.safeParse(parsed);
+        if (!envelopeResult.success) {
+            throw new CliError(1, 'INVALID_RESPONSE', 'Unexpected response envelope from server', response.status);
+        }
+        return redactCredentials(envelopeResult.data, adminToken);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "uptimer-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Manage Uptimer configuration from coding agents and the terminal",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22.14.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nexttylabs/Uptimer.git",
+    "directory": "apps/cli"
+  },
+  "bin": {
+    "uptimer": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "skill",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node --experimental-strip-types src/index.ts",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "prepack": "pnpm build && node scripts/prepare-skill.mjs",
+    "test:package": "pnpm prepack && node --experimental-strip-types --test test/package.test.ts",
+    "test": "node --experimental-strip-types --test test/entry.test.ts test/resources.test.ts test/transport.test.ts test/skill.test.ts",
+    "lint": "pnpm -w exec eslint --config eslint.config.mjs apps/cli",
+    "typecheck": "pnpm -w exec tsc -p apps/cli/tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: uptimer-cli
+description: Install and use the Uptimer CLI to inspect or change monitors, notification channels, status pages, and global settings on an existing Uptimer instance.
+---
+
+# Uptimer CLI
+
+The npm package is `uptimer-cli`; the executable is `uptimer`. This skill configures an existing Uptimer instance through its Admin API.
+
+## 1. Select a working CLI
+
+Run `uptimer --help` if the executable is installed. If installation is requested and an npm release is available, use `npm install --global uptimer-cli`. For a requested pinned release, use `npx --yes uptimer-cli@<version>` in place of `uptimer`, substituting an actual published version.
+
+If npm returns 404 before the first release, use a checkout of `nexttylabs/Uptimer` containing `apps/cli`:
+
+```sh
+pnpm install --frozen-lockfile
+pnpm --silent --filter uptimer-cli start --help
+```
+
+For later commands in that checkout, replace `uptimer` with `pnpm --silent --filter uptimer-cli start`. CLI support starts at Node 22.14.0. The separate Skills installer requires Node 22.20 or newer; Node 24 supports both.
+
+Continue when help exits 0 and lists the expected resource commands. Help covers command syntax and payload examples for every resource; [commands.md](references/commands.md) adds field detail and edge cases.
+
+When this skill has been installed once, `uptimer skill install --dir <dir> --force` refreshes it from the installed CLI package; the default directory is `./skills`.
+
+## 2. Connect to the intended instance
+
+Use `UPTIMER_URL` and `UPTIMER_ADMIN_TOKEN` from the invoking process environment or the host's credential configuration. Ask for a missing instance URL; have the administrator inject a missing token through the host's secret mechanism, rather than posting it in chat. The CLI does not load `.env` automatically or store a login profile.
+
+The URL is an HTTPS origin, without `/api/v1`, userinfo, query, fragment, or subpath. Explicit loopback HTTP origins, such as `http://localhost:8787`, are supported for development.
+
+Run `uptimer settings get` to check connectivity and authentication. Output is redacted, but returned configuration is still administrative data: report only the non-secret fields relevant to the request instead of pasting whole resource payloads.
+
+Continue when the configured instance returns a successful JSON response. An HTTP 401 requires correcting the supplied credential; it is not a reason to change the instance or authentication settings.
+
+## 3. Perform the requested operation
+
+Read the relevant resource section in [commands.md](references/commands.md) before constructing a payload. Use actual IDs returned by the selected instance, and keep changes within the user's authorized resource and fields. An unchanged authorization needs no second confirmation.
+
+For a write, provide one UTF-8 JSON object through exactly one `--file path.json` or `--file -`. Keep omitted PATCH fields omitted; use `null` only where that field supports clearing. Validate JSON locally before invoking the CLI to catch syntax errors early; the CLI reports only a parse position. Keep credential-bearing payload files private and remove task-created temporary files when finished.
+
+List commands for monitors and notification channels return at most 50 records by default, or 200 with `--limit 200`. A resource missing from a bounded list is not proof that it does not exist. The CLI has no cursor, per-ID get command, or complete export.
+
+A 409 conflict is a request to explain the conflicting state. Unlink or delete other resources only when that additional change is authorized. This CLI does not provision Worker secrets, deploy Cloudflare resources, manage incidents or maintenance windows, or synchronize a declarative configuration file.
+
+## 4. Verify and report
+
+Check the exit status and JSON result, then query the affected list or settings resource and compare the requested fields. If the item is outside the bounded listing, report that readback could not be completed rather than claiming it was verified.
+
+- Exit 0: success; stdout is JSON, except for help.
+- Exit 2: local input, usage, or environment problem; correct it before retrying.
+- Exit 1: HTTP, transport, deadline, or response-contract failure. A write may already have succeeded. Query its state before considering a retry, especially after interruption or timeout; never automatically repeat a mutation.
+
+A response body that stops streaming is cut off at the deadline, and the CLI exits without retrying the write. Treat an externally interrupted write as uncertain even when the CLI reports a timeout.
+
+Finish with the instance, operation, resource IDs, changed non-secret fields, and readback outcome. Name any conflict, incomplete verification, or uncertain write result explicitly.