@blackasteroid/kuma-cli 1.2.0 → 1.2.1

package/README.md

@@ -1,6 +1,6 @@
 # kuma-cli
 
-> CLI for managing [Uptime Kuma](https://github.com/louislam/uptime-kuma) via its native Socket.IO API. No more clicking through the web panel — manage monitors, status pages, and heartbeats directly from your terminal.
+> CLI for managing [Uptime Kuma](https://github.com/louislam/uptime-kuma) via its native Socket.IO API. No more clicking through the web panel — manage monitors, status pages, and heartbeats from your terminal.
 
 ## Install
 
@@ -14,7 +14,7 @@ Or use without installing:
 npx @blackasteroid/kuma-cli login https://kuma.example.com
 ```
 
-## Quick Start
+## Quick start
 
 ```bash
 # 1. Authenticate
@@ -23,8 +23,8 @@ kuma login https://kuma.example.com
 # 2. List monitors
 kuma monitors list
 
-# 3. Add a monitor
-kuma monitors add --name "My API" --type http --url https://api.example.com
+# 3. Create a monitor
+kuma monitors create --name "My API" --type http --url https://api.example.com
 ```
 
 ## Commands
@@ -43,46 +43,90 @@ kuma monitors add --name "My API" --type http --url https://api.example.com
 |---------|-------------|
 | `kuma monitors list` | List all monitors with status + uptime |
 | `kuma monitors list --json` | Output raw JSON (for scripting) |
+| `kuma monitors list --status down --json` | Filter by status |
+| `kuma monitors list --tag <tag> --json` | Filter by tag |
 | `kuma monitors add` | Add a monitor interactively |
 | `kuma monitors add --name <n> --type http --url <url>` | Add non-interactively |
+| `kuma monitors create --type http --name <n> --url <url>` | Create monitor non-interactively (pipeline-safe) |
+| `kuma monitors create --type push --name <n> --json` | Create push monitor, returns pushToken |
 | `kuma monitors update <id>` | Update name/url/interval of a monitor |
 | `kuma monitors delete <id>` | Delete a monitor (with confirmation) |
 | `kuma monitors delete <id> --force` | Delete without confirmation prompt |
 | `kuma monitors pause <id>` | Pause a monitor |
 | `kuma monitors resume <id>` | Resume a paused monitor |
+| `kuma monitors bulk-pause --tag <tag>` | Pause all monitors matching tag |
+| `kuma monitors bulk-pause --tag <tag> --dry-run` | Preview without touching anything |
+| `kuma monitors bulk-resume --tag <tag>` | Resume all monitors matching tag |
+| `kuma monitors set-notification <id> --notification-id <id>` | Assign notification to monitor |
 
-#### `monitors add` flags
-
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--name <name>` | Monitor name | (prompted) |
-| `--type <type>` | Monitor type: `http`, `tcp`, `ping`, `dns`, `push`, ... | (prompted) |
-| `--url <url>` | URL or hostname to monitor | (prompted) |
-| `--interval <seconds>` | Check interval | `60` |
-
-#### `monitors update` flags
+### Heartbeats
 
-| Flag | Description |
-|------|-------------|
-| `--name <name>` | New monitor name |
-| `--url <url>` | New URL or hostname |
-| `--interval <seconds>` | New check interval |
+| Command | Description |
+|---------|-------------|
+| `kuma heartbeat view <monitor-id>` | View last 20 heartbeats |
+| `kuma heartbeat view <monitor-id> --limit 50` | Show last N heartbeats |
+| `kuma heartbeat view <monitor-id> --json` | Output raw JSON |
+| `kuma heartbeat send <push-token>` | Send push heartbeat (no auth needed) |
+| `kuma heartbeat send <push-token> --status down --msg "text"` | Send with status/message |
 
-### Heartbeats
+### Notifications
 
 | Command | Description |
 |---------|-------------|
-| `kuma heartbeat <monitor-id>` | View last 20 heartbeats for a monitor |
-| `kuma heartbeat <monitor-id> --limit 50` | Show last N heartbeats |
-| `kuma heartbeat <monitor-id> --json` | Output raw JSON |
+| `kuma notifications list` | List all notification channels |
+| `kuma notifications create --type discord --name <n> --url <webhook>` | Create Discord notification channel |
 
-### Status Pages
+### Status pages
 
 | Command | Description |
 |---------|-------------|
 | `kuma status-pages list` | List all status pages |
 | `kuma status-pages list --json` | Output raw JSON |
 
+## Using with AI agents
+
+kuma-cli works well in agent and automation contexts. Every command supports `--json` output and exits non-zero on errors, so you can parse results reliably and short-circuit on failure.
+
+Set `KUMA_JSON=1` to force JSON output on all commands — useful when you don't control the call site.
+
+**Check what's down:**
+```bash
+kuma monitors list --status down --json
+```
+
+**Pause/resume around a deploy:**
+```bash
+kuma monitors bulk-pause --tag Production --dry-run   # preview first
+kuma monitors bulk-pause --tag Production
+./deploy.sh
+kuma monitors bulk-resume --tag Production
+```
+
+**Create a monitor and wire up a notification in one shot:**
+```bash
+MONITOR_ID=$(kuma monitors create --type http --name "my-service" \
+  --url https://my-service.com --tag Production --json | jq -r '.data.id')
+kuma monitors set-notification $MONITOR_ID --notification-id 1
+```
+
+**Push monitor for a GitHub Actions runner:**
+```bash
+# Create the monitor, capture the token
+TOKEN=$(kuma monitors create --type push --name "runner-aang" --json | jq -r '.data.pushToken')
+
+# In the workflow:
+- name: Heartbeat
+  run: kuma heartbeat send ${{ secrets.RUNNER_PUSH_TOKEN }}
+```
+
+**Connect a notification channel to all production monitors:**
+```bash
+NOTIF_ID=$(kuma notifications create --type discord --name "alerts" \
+  --url $WEBHOOK --json | jq -r '.data.id')
+kuma monitors list --tag Production --json | jq -r '.[].id' | \
+  xargs -I{} kuma monitors set-notification {} --notification-id $NOTIF_ID
+```
+
 ## Config
 
 After login, your session is saved automatically — you won't need to re-authenticate on every command:

package/dist/index.js

@@ -30366,6 +30366,17 @@ ${source_default.dim("Notes:")}
     const json = isJsonMode(opts);
     try {
       const normalizedUrl = url2.replace(/\/$/, "");
+      if (!normalizedUrl.startsWith("https://")) {
+        if (json) {
+          console.log(JSON.stringify({
+            warning: "Connecting over HTTP. Credentials will be transmitted in cleartext. Use HTTPS in production."
+          }));
+        } else {
+          console.warn(source_default.yellow(
+            "\u26A0\uFE0F  Warning: connecting over HTTP. Your credentials will be sent in cleartext.\n   Use https:// in production environments."
+          ));
+        }
+      }
       const answers = await prompt([
         {
           type: "input",
@@ -31067,9 +31078,13 @@ ${source_default.dim("Examples:")}
     const config = getConfig();
     if (!config) requireAuth(opts);
     const json = isJsonMode(opts);
+    const parsedMonitorId = parseInt(monitorId, 10);
+    if (isNaN(parsedMonitorId) || parsedMonitorId <= 0) {
+      handleError(new Error(`Invalid monitor ID: "${monitorId}". Must be a positive integer.`), opts);
+    }
     try {
       const client = await createAuthenticatedClient(config.url, config.token);
-      const heartbeats = await client.getHeartbeatList(parseInt(monitorId, 10));
+      const heartbeats = await client.getHeartbeatList(parsedMonitorId);
       client.disconnect();
       const limit = parseInt(opts.limit ?? "20", 10);
       const recent = heartbeats.slice(-limit).reverse();
@@ -31119,6 +31134,12 @@ ${source_default.dim("Finding your push token:")}
 `
   ).action(async (pushToken, opts) => {
     const json = isJsonMode(opts);
+    if (!/^[a-zA-Z0-9_-]+$/.test(pushToken)) {
+      const msg = `Invalid push token format. Tokens must contain only alphanumeric characters, hyphens, and underscores.`;
+      if (json) jsonError(msg, EXIT_CODES.GENERAL);
+      console.error(source_default.red(`\u274C ${msg}`));
+      process.exit(EXIT_CODES.GENERAL);
+    }
     const VALID_STATUSES = ["up", "down", "maintenance"];
     const statusKey = (opts.status ?? "up").toLowerCase();
     if (!VALID_STATUSES.includes(statusKey)) {
@@ -31324,7 +31345,7 @@ ${source_default.bold(`Upgrading kuma-cli`)} ${source_default.dim(`v${current}`)
       );
     }
     try {
-      (0, import_child_process.execSync)("npm install -g @blackasteroid/kuma-cli@latest", {
+      (0, import_child_process.execSync)(`npm install -g @blackasteroid/kuma-cli@${latest}`, {
         stdio: json ? "pipe" : "inherit"
       });
     } catch (err) {
@@ -31357,6 +31378,27 @@ ${source_default.bold(`Upgrading kuma-cli`)} ${source_default.dim(`v${current}`)
 }
 
 // src/commands/notifications.ts
+function resolveSecret(value2) {
+  if (value2 === void 0) return void 0;
+  if (value2.startsWith("$")) {
+    const varName = value2.slice(1);
+    const resolved = process.env[varName];
+    if (!resolved) {
+      return void 0;
+    }
+    return resolved;
+  }
+  if (value2 === "-") {
+    try {
+      const buf = Buffer.alloc(4096);
+      const n = require("fs").readSync(0, buf, 0, buf.length, null);
+      return buf.toString("utf8", 0, n).trim();
+    } catch {
+      return void 0;
+    }
+  }
+  return value2;
+}
 function notificationsCommand(program3) {
   const notifications = program3.command("notifications").description("Manage notification channels (Discord, Telegram, webhook, ...)").addHelpText(
     "after",
@@ -31423,14 +31465,18 @@ ${list.length} notification channel(s)`);
       handleError(err, opts);
     }
   });
-  notifications.command("create").description("Create a new notification channel").requiredOption("--type <type>", "Notification type: discord, telegram, slack, webhook, ...").requiredOption("--name <name>", "Friendly name for this notification channel").option("--discord-webhook <url>", "Discord webhook URL (required for --type discord)").option("--discord-username <name>", "Discord bot display name (optional)").option("--telegram-token <token>", "Telegram bot token (required for --type telegram)").option("--telegram-chat-id <id>", "Telegram chat ID (required for --type telegram)").option("--slack-webhook <url>", "Slack webhook URL (required for --type slack)").option("--webhook-url <url>", "Webhook URL (required for --type webhook)").option("--webhook-content-type <type>", "Webhook content type (default: application/json)", "application/json").option("--default", "Enable this notification by default on all new monitors").option("--apply-existing", "Apply this notification to all existing monitors immediately").option("--json", "Output as JSON ({ ok, data })").addHelpText(
+  notifications.command("create").description("Create a new notification channel").requiredOption("--type <type>", "Notification type: discord, telegram, slack, webhook, ...").requiredOption("--name <name>", "Friendly name for this notification channel").option("--discord-webhook <url|$VAR>", "Discord webhook URL \u2014 pass value or env var name like '$DISCORD_WEBHOOK'").option("--discord-username <name>", "Discord bot display name (optional)").option("--telegram-token <token|$VAR>", "Telegram bot token \u2014 pass value or env var name like '$TELEGRAM_TOKEN'").option("--telegram-chat-id <id>", "Telegram chat ID (required for --type telegram)").option("--slack-webhook <url|$VAR>", "Slack webhook URL \u2014 pass value or env var name like '$SLACK_WEBHOOK'").option("--webhook-url <url|$VAR>", "Webhook URL \u2014 pass value or env var name like '$WEBHOOK_URL'").option("--webhook-content-type <type>", "Webhook content type (default: application/json)", "application/json").option("--default", "Enable this notification by default on all new monitors").option("--apply-existing", "Apply this notification to all existing monitors immediately").option("--json", "Output as JSON ({ ok, data })").addHelpText(
     "after",
     `
 ${source_default.dim("Examples:")}
-  ${source_default.cyan('kuma notifications create --type discord --name "Alerts" --discord-webhook https://discord.com/api/webhooks/...')}
-  ${source_default.cyan('kuma notifications create --type telegram --name "TG" --telegram-token 123:ABC --telegram-chat-id -100...')}
-  ${source_default.cyan('kuma notifications create --type webhook --name "My Hook" --webhook-url https://example.com/hook')}
-  ${source_default.cyan('kuma notifications create --type discord --name "Default" --discord-webhook $URL --default --apply-existing')}
+  ${source_default.cyan(`kuma notifications create --type discord --name "Alerts" --discord-webhook '$DISCORD_WEBHOOK'`)}
+  ${source_default.cyan(`kuma notifications create --type telegram --name "TG" --telegram-token '$TELEGRAM_TOKEN' --telegram-chat-id -100...`)}
+  ${source_default.cyan(`kuma notifications create --type webhook --name "My Hook" --webhook-url '$WEBHOOK_URL'`)}
+  ${source_default.cyan(`kuma notifications create --type discord --name "Default" --discord-webhook '$DISCORD_WEBHOOK' --default --apply-existing`)}
+
+${source_default.dim("\u26A0\uFE0F  Security: never pass secrets as literal flag values \u2014 use env vars:")}
+  ${source_default.cyan("export DISCORD_WEBHOOK=https://discord.com/api/webhooks/...")}
+  ${source_default.cyan(`kuma notifications create --type discord --name "Alerts" --discord-webhook '\\$DISCORD_WEBHOOK'`)}
 
 ${source_default.dim("Supported types:")}
   discord, telegram, slack, webhook, gotify, ntfy, pushover, matrix, mattermost, teams ...
@@ -31447,32 +31493,36 @@ ${source_default.dim("Supported types:")}
       active: true,
       applyExisting: opts.applyExisting ?? false
     };
+    const discordWebhook = resolveSecret(opts.discordWebhook);
+    const telegramToken = resolveSecret(opts.telegramToken);
+    const slackWebhook = resolveSecret(opts.slackWebhook);
+    const webhookUrl = resolveSecret(opts.webhookUrl);
     switch (opts.type.toLowerCase()) {
       case "discord":
-        if (!opts.discordWebhook) {
-          handleError(new Error("--discord-webhook is required for --type discord"), opts);
+        if (!discordWebhook) {
+          handleError(new Error("--discord-webhook is required for --type discord (pass value or '$ENV_VAR_NAME')"), opts);
         }
-        payload.discordWebhookUrl = opts.discordWebhook;
+        payload.discordWebhookUrl = discordWebhook;
         if (opts.discordUsername) payload.discordUsername = opts.discordUsername;
         break;
       case "telegram":
-        if (!opts.telegramToken || !opts.telegramChatId) {
+        if (!telegramToken || !opts.telegramChatId) {
           handleError(new Error("--telegram-token and --telegram-chat-id are required for --type telegram"), opts);
         }
-        payload.telegramBotToken = opts.telegramToken;
+        payload.telegramBotToken = telegramToken;
         payload.telegramChatID = opts.telegramChatId;
         break;
       case "slack":
-        if (!opts.slackWebhook) {
-          handleError(new Error("--slack-webhook is required for --type slack"), opts);
+        if (!slackWebhook) {
+          handleError(new Error("--slack-webhook is required for --type slack (pass value or '$ENV_VAR_NAME')"), opts);
         }
-        payload.slackwebhookURL = opts.slackWebhook;
+        payload.slackwebhookURL = slackWebhook;
         break;
       case "webhook":
-        if (!opts.webhookUrl) {
-          handleError(new Error("--webhook-url is required for --type webhook"), opts);
+        if (!webhookUrl) {
+          handleError(new Error("--webhook-url is required for --type webhook (pass value or '$ENV_VAR_NAME')"), opts);
         }
-        payload.webhookURL = opts.webhookUrl;
+        payload.webhookURL = webhookUrl;
         payload.webhookContentType = opts.webhookContentType ?? "application/json";
         break;
       default:
@@ -31508,8 +31558,8 @@ ${source_default.dim("Examples:")}
     if (!config) requireAuth(opts);
     const json = isJsonMode(opts);
     const notifId = parseInt(id, 10);
-    if (isNaN(notifId)) {
-      handleError(new Error(`Invalid notification ID: ${id}`), opts);
+    if (isNaN(notifId) || notifId <= 0) {
+      handleError(new Error(`Invalid notification ID: "${id}". Must be a positive integer.`), opts);
     }
     if (!opts.force && !json) {
       const enquirer3 = await Promise.resolve().then(() => __toESM(require_enquirer()));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blackasteroid/kuma-cli",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "CLI for managing Uptime Kuma via Socket.IO API",
   "bin": {
     "kuma": "dist/index.js"