agentalarm 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AChub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,32 @@
-# Temporary Holding Version
+# agentalarm
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Alerts on your iPhone from scripts, CI and AI agents, through [AgentAlarm](https://alarm.achub.net). Without a time an
+alert is a notification, now (the app's Notifications feed); with `--at` it is a reminder (the Reminders list). Quiet by
+default; `--ring` makes it a call that rings your phone like an alarm, through Silent and Focus, until you tap Done or
+Snooze. It is never a phone call. Node 18+, no dependencies.
+
+```bash
+npx agentalarm login "<the text copied from the app>"   # Settings > Connected Agents > Connect
+npx agentalarm "Backup finished"
+npx agentalarm "Deploy failed" --ring --color red
+npx agentalarm "Stand-up" --at 2026-10-28T09:00
+```
+
+| Command | |
+|---|---|
+| `agentalarm "text" [-r] [--at <time>] [-b <body>] [-c <color>] [-i <icon>] [-l <location>] [-s <sound>] [--json]` | Send a notification now; `--at` makes a reminder, `-r` / `--ring` (or `-u`) rings. |
+| `agentalarm login "<text or link>"` | Redeem the app's one-time link; the key goes to `~/.config/agentalarm/config.json` (600). |
+| `agentalarm key "<text>" [--name CI] \| gh secret set AGENTALARM_KEY` | A separate key for CI, printed only into a pipe. |
+| `agentalarm setup`, `agentalarm config [set <option> <value>]` | When agent hooks alert you. |
+| `agentalarm test` (a test call), `status`, `pause [1h]`, `resume`, `logout` | |
+| `agentalarm hook <claude-code\|cursor\|codex>` | Agent hook: reads the event on stdin, alerts without spam, always exits 0. |
+| `agentalarm mcp` | Local stdio MCP server that forwards to AgentAlarm with the saved key. |
+
+`AGENTALARM_KEY` in the environment wins over the saved key. Exit codes: 0 sent, 1 network or server error, 2 usage,
+3 not logged in or key rejected, 4 refused by the server (its message is printed).
+
+Hook settings, the Claude Code and Cursor plugins, Codex hooks and CI examples:
+https://github.com/achubnet/agentalarm-plugins#readme
+
+Works with AI agents that support MCP, for example Claude Code, Codex, Cursor, VS Code, Windsurf and Grok-based bots.
+AgentAlarm is not affiliated with Anthropic, OpenAI, Anysphere, Microsoft or xAI.

package/bin/agentalarm.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from '../src/cli.js';
+
+process.exitCode = await main(process.argv.slice(2));

package/package.json

@@ -1,6 +1,30 @@
 {
   "name": "agentalarm",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Let AI agents, scripts and CI ring your iPhone through AgentAlarm: urgent alerts ring through Silent and Focus.",
+  "keywords": ["agentalarm", "alarm", "iphone", "notifications", "claude-code", "cursor", "codex", "hooks", "mcp", "ai-agents"],
+  "homepage": "https://alarm.achub.net",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/achubnet/agentalarm-plugins.git",
+    "directory": "cli"
+  },
+  "license": "MIT",
+  "author": "AgentAlarm",
+  "type": "module",
+  "bin": {
+    "agentalarm": "bin/agentalarm.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  }
+}

package/src/api.js

@@ -0,0 +1,116 @@
+import { randomUUID } from 'node:crypto';
+import { CliError, EXIT } from './errors.js';
+import { DEFAULT_BASE_URL } from './config.js';
+import { checkUrl, isLoopback, request } from './http.js';
+
+const CODE = /([A-Z2-9]{4}-[A-Z2-9]{4})/;
+const SETUP_LINK = /(https?:\/\/[^\s"'<>()]+?)\/api\/setup\/([A-Za-z2-9]{4}-[A-Za-z2-9]{4})(?![A-Za-z0-9-])/;
+
+function serverUrl(value) {
+  const url = checkUrl(value);
+  if (url.username || url.password) {
+    throw new CliError(`Refusing ${url.protocol}//${url.host}: a server address must not contain a user name or password.`, EXIT.USAGE);
+  }
+  return url;
+}
+
+/**
+ * Finds the one-time setup link in what the user copied from the app (the whole text, the link alone, or the bare
+ * code) and returns `<origin>/api/setup/<CODE>`. Null when there is none. A link to any server but AgentAlarm's (or
+ * a loopback one, for development) is refused unless `server` names that origin: pasted text could carry a lookalike
+ * host that would receive the redeem request and later every alert.
+ */
+export function extractSetupUrl(text, { server } = {}) {
+  if (typeof text !== 'string') return null;
+  const allowed = server ? serverUrl(server).origin : null;
+  const link = text.match(SETUP_LINK);
+  if (link) {
+    const url = serverUrl(link[1]);
+    if (url.origin !== DEFAULT_BASE_URL && url.origin !== allowed && !isLoopback(url)) {
+      throw new CliError(
+        `The link points to ${url.origin}, not ${DEFAULT_BASE_URL}. Only if you run that AgentAlarm server yourself, add --server ${url.origin}.`,
+        EXIT.USAGE,
+      );
+    }
+    return `${url.origin}/api/setup/${link[2].toUpperCase()}`;
+  }
+  const code = text.trim().toUpperCase().match(new RegExp(`^${CODE.source}$`));
+  return code ? `${allowed ?? DEFAULT_BASE_URL}/api/setup/${code[1]}` : null;
+}
+
+function serverMessage(res) {
+  const message = res.json && typeof res.json.message === 'string' ? res.json.message.trim() : '';
+  return message.slice(0, 500);
+}
+
+/** Maps a failed response to a CliError with the server's own message where it has one. */
+export function errorFrom(res) {
+  const message = serverMessage(res);
+  if (res.status === 401) {
+    return new CliError('AgentAlarm rejected the key (revoked or expired). Run "agentalarm login" with a new link from the app.', EXIT.AUTH);
+  }
+  if (res.status === 403) {
+    return new CliError('This key cannot create alerts (read-only). Connect again from the app without "read only".', EXIT.AUTH);
+  }
+  if (res.status === 422) {
+    return new CliError(message || 'AgentAlarm refused the alert.', EXIT.REFUSED);
+  }
+  if (res.status === 429) {
+    return new CliError('Too many requests. Wait a minute and try again.', EXIT.FAILURE);
+  }
+  return new CliError(`AgentAlarm answered HTTP ${res.status}${message ? `: ${message}` : '.'}`, EXIT.FAILURE);
+}
+
+/**
+ * Opens the key page once (`?format=json`): the server creates the key named `name` and returns it.
+ * The key must come from the same server as the link.
+ */
+export async function redeemSetup(setupUrl, name) {
+  const url = new URL(`${setupUrl}/key`);
+  url.searchParams.set('format', 'json');
+  url.searchParams.set('name', name);
+  const res = await request('GET', url.toString());
+
+  if (res.status === 404) {
+    throw new CliError(serverMessage(res) || 'This setup link is invalid, expired or already used. Create a new one in the AgentAlarm app.', EXIT.USAGE);
+  }
+  if (res.status !== 200) throw errorFrom(res);
+
+  const data = res.json;
+  if (!data || typeof data.key !== 'string' || !/^\d+\|\S{10,200}$/.test(data.key)) {
+    throw new CliError('The setup page did not return a key. Update agentalarm ("npx agentalarm@latest") and try a new link.', EXIT.FAILURE);
+  }
+  return {
+    key: data.key,
+    name: typeof data.name === 'string' ? data.name : name,
+    readOnly: data.read_only === true,
+    baseUrl: new URL(setupUrl).origin,
+  };
+}
+
+function authHeaders(creds) {
+  if (!creds.key) {
+    throw new CliError('Not logged in. Run: npx agentalarm login "<the text copied from the AgentAlarm app>" (or set AGENTALARM_KEY).', EXIT.AUTH);
+  }
+  return { Authorization: `Bearer ${creds.key}` };
+}
+
+/** POST /api/alarms with a client-made id, so a retried create never makes a second alert. */
+export async function createAlarm(creds, alarm) {
+  const body = { id: randomUUID(), ...alarm };
+  const res = await request('POST', `${creds.baseUrl}/api/alarms`, { headers: authHeaders(creds), body });
+  if (res.status !== 200 && res.status !== 201) throw errorFrom(res);
+  return res.json ?? {};
+}
+
+export async function me(creds) {
+  const res = await request('GET', `${creds.baseUrl}/api/me`, { headers: authHeaders(creds) });
+  if (res.status !== 200) throw errorFrom(res);
+  return res.json ?? {};
+}
+
+/** Revokes the key that makes the request (only that one). */
+export async function revokeKey(creds) {
+  const res = await request('POST', `${creds.baseUrl}/api/auth/logout`, { headers: authHeaders(creds) });
+  if (res.status !== 200 && res.status !== 401) throw errorFrom(res);
+}

package/src/cli.js

@@ -0,0 +1,453 @@
+import { spawn } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import { createAlarm, extractSetupUrl, me, redeemSetup, revokeKey } from './api.js';
+import {
+  HOOK_DEFAULTS,
+  HOOK_ENV_NAMES,
+  configPath,
+  credentials,
+  hookSettings,
+  loadConfig,
+  parseHookOption,
+  saveConfig,
+  stateDir,
+  updateConfig,
+} from './config.js';
+import { CliError, EXIT } from './errors.js';
+import { AGENTS, SessionStore, handleHook, hookOutput } from './hook.js';
+import { idleMs } from './idle.js';
+import { runMcpProxy } from './mcp.js';
+import { askHookSettings } from './setup.js';
+import { VERSION } from './version.js';
+
+const BIN = fileURLToPath(new URL('../bin/agentalarm.js', import.meta.url));
+
+const HELP = `agentalarm ${VERSION}: alerts on your iPhone from scripts, CI and AI agents (https://alarm.achub.net)
+
+Usage:
+  agentalarm "text" [options]       Send a notification now (the app's Notifications feed).
+    -r, --ring, -u, --urgent        A call: rings like an alarm, through Silent and Focus, until Done or Snooze.
+    --at <time>                     A reminder at that time instead (the app's Reminders list), e.g. 2026-10-28T09:00
+                                    (your timezone in the app) or with an offset.
+    -b, --body <text>               Details; line breaks and links are kept.
+    -c, --color <name>              blue, red, orange, green or purple.
+    -i, --icon <name>               bell, checkmark.circle, exclamationmark.triangle, calendar, sportscourt, gift,
+                                    cart, airplane, heart or briefcase.
+    -l, --location <text>           An address or place; the app opens it in Maps.
+    -s, --sound <id>                Ring sound (with --ring), e.g. loudalarm, urgentpulse, calmpiano.
+    --json                          Print the created alert as JSON.
+
+  agentalarm login "<text from the app>"   Connect: paste the text (or link) from AgentAlarm > Connect an agent.
+                                    Links to another server need --server <origin> (self-hosted only).
+  agentalarm key "<text from the app>" [--name CI] | gh secret set AGENTALARM_KEY
+                                    Redeem a link for CI: prints the new key into a pipe, never to a terminal.
+  agentalarm setup [--defaults]     Choose when agent hooks alert you.
+  agentalarm config [set <option> <value> | unset <option>]   Show or change one hook option.
+  agentalarm test                   Send a test call (it rings).
+  agentalarm status                 Show the connection and hook settings.
+  agentalarm pause [30m|1h|2d]      Pause hook alerts (default 1h). Direct alerts still go out.
+  agentalarm resume                 Resume hook alerts.
+  agentalarm logout                 Revoke this computer's key and forget it.
+  agentalarm hook <claude-code|cursor|codex>   Run as an agent hook (reads the event JSON on stdin).
+  agentalarm mcp                    Local MCP server (stdio) that forwards to AgentAlarm with your key.
+
+Environment: AGENTALARM_KEY (a key, for CI), AGENTALARM_<OPTION> for hook options (see the README).
+Exit codes: 0 ok, 1 network or server error, 2 usage, 3 not logged in or key rejected, 4 refused by the server.`;
+
+const VALUE_OPTIONS = {
+  '--name': 'name', '--server': 'server', '--at': 'at', '--body': 'body', '-b': 'body', '--color': 'color', '-c': 'color',
+  '--sound': 'sound', '-s': 'sound', '--icon': 'icon', '-i': 'icon', '--location': 'location', '-l': 'location',
+};
+const FLAG_OPTIONS = {
+  '--urgent': 'urgent', '-u': 'urgent', '--ring': 'urgent', '-r': 'urgent',
+  '--json': 'json', '--defaults': 'defaults', '--local': 'local', '--no-setup': 'noSetup',
+};
+
+export function parseArgs(argv) {
+  const positional = [];
+  const options = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--') {
+      positional.push(...argv.slice(i + 1));
+      break;
+    }
+    const [flag, inline] = arg.startsWith('--') && arg.includes('=') ? [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)] : [arg, undefined];
+    if (VALUE_OPTIONS[flag]) {
+      const value = inline ?? argv[++i];
+      if (value === undefined) throw new CliError(`${flag} needs a value.`, EXIT.USAGE);
+      options[VALUE_OPTIONS[flag]] = value;
+    } else if (FLAG_OPTIONS[flag] && inline === undefined) {
+      options[FLAG_OPTIONS[flag]] = true;
+    } else if (arg === '-h' || arg === '--help') {
+      options.help = true;
+    } else if (arg === '-v' || arg === '--version') {
+      options.version = true;
+    } else if (arg.startsWith('-') && arg.length > 1) {
+      throw new CliError(`Unknown option ${flag}. See "agentalarm --help".`, EXIT.USAGE);
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { positional, options };
+}
+
+/** "30m", "1h", "2d", "90" (minutes) → ms; null when invalid. */
+export function parseDuration(text) {
+  const m = String(text).trim().toLowerCase().match(/^(\d+(?:\.\d+)?)\s*(m|min|mins|minutes?|h|hours?|d|days?)?$/);
+  if (!m) return null;
+  const unit = (m[2] || 'm')[0];
+  const ms = Number(m[1]) * { m: 60_000, h: 3_600_000, d: 86_400_000 }[unit];
+  return ms > 0 && ms <= 30 * 86_400_000 ? ms : null;
+}
+
+function readStdin(stdin, { limit = 1_000_000, timeoutMs = 2000 } = {}) {
+  if (stdin.isTTY) return Promise.resolve('');
+  return new Promise((resolve) => {
+    let data = '';
+    const done = () => {
+      clearTimeout(timer);
+      stdin.removeAllListeners('data');
+      stdin.pause();
+      resolve(data);
+    };
+    const timer = setTimeout(done, timeoutMs);
+    stdin.setEncoding('utf8');
+    stdin.on('data', (chunk) => {
+      data += chunk;
+      if (data.length > limit) done();
+    });
+    stdin.on('end', done);
+    stdin.on('error', done);
+  });
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+// Hook log: why each hook did or did not alert. No keys, no prompts, no code.
+
+const LOG_MAX_BYTES = 256 * 1024;
+
+export function logHook(env, line) {
+  try {
+    const dir = stateDir(env);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const file = path.join(dir, 'hook.log');
+    try {
+      if (fs.statSync(file).size > LOG_MAX_BYTES) fs.renameSync(file, `${file}.1`);
+    } catch {
+      // No log yet.
+    }
+    fs.appendFileSync(file, `${new Date().toISOString()} ${line}\n`, { mode: 0o600 });
+  } catch {
+    // Logging must never break a hook.
+  }
+}
+
+/** Sends from a detached process, so the hook exits at once and the agent never waits for the network. */
+function deliverInBackground(alarm, env) {
+  const child = spawn(process.execPath, [BIN, '__deliver'], {
+    detached: true,
+    stdio: 'ignore',
+    windowsHide: true,
+    env: { ...env, AGENTALARM_DELIVERY: JSON.stringify(alarm) },
+  });
+  child.unref();
+}
+
+async function deliver(alarm, env) {
+  const creds = credentials(loadConfig(env), env);
+  try {
+    await createAlarm(creds, alarm);
+    logHook(env, `delivered ${alarm.type}: ${alarm.title}`);
+  } catch (error) {
+    logHook(env, `delivery failed: ${error.message}`);
+  }
+}
+
+async function runHook(agent, { stdin, stdout, env }) {
+  if (!AGENTS[agent]) {
+    logHook(env, `unknown agent "${agent}" (use ${Object.keys(AGENTS).join(', ')})`);
+    return EXIT.OK;
+  }
+  const raw = await readStdin(stdin);
+  let payload = {};
+  try {
+    payload = JSON.parse(raw || '{}');
+  } catch {
+    logHook(env, `${agent}: hook input is not JSON`);
+  }
+  stdout.write(hookOutput(agent, payload));
+
+  try {
+    let config = {};
+    try {
+      config = loadConfig(env);
+    } catch (error) {
+      logHook(env, `${agent}: ${error.message}`);
+    }
+    const result = await handleHook(agent, payload, {
+      store: new SessionStore(stateDir(env)),
+      now: () => new Date(),
+      settings: hookSettings(config, env),
+      pausedUntil: config.pausedUntil ?? null,
+      hasKey: Boolean(credentials(config, env).key),
+      idle: () => idleMs(),
+      deliver: (alarm) => (env.AGENTALARM_HOOK_SYNC === '1' ? deliver(alarm, env) : deliverInBackground(alarm, env)),
+    });
+    logHook(env, `${agent} ${payload.hook_event_name ?? '?'}: ${result.sent ? 'alert' : 'skip'} (${result.reason})`);
+  } catch (error) {
+    logHook(env, `${agent}: hook error: ${error.message}`);
+  }
+  return EXIT.OK;
+}
+
+// ---------------------------------------------------------------------------------------------------------------
+
+function hostLabel() {
+  return os.hostname().split('.')[0].slice(0, 30) || 'this computer';
+}
+
+/** No --at: a notification now (a call with --ring). --at: a reminder at that time (the server's rule). */
+function describeAlarm(alarm, requested) {
+  const rings = requested.type === 'urgent';
+  if (requested.fire_at) {
+    const when = alarm.rings_at ? ` for ${alarm.rings_at}` : '';
+    return `Reminder set${when}${rings ? ' (rings)' : ''}: ${requested.title}`;
+  }
+  return `${rings ? 'Call sent (rings now)' : 'Notification sent'}: ${requested.title}`;
+}
+
+async function send(title, options, io) {
+  if (!title) throw new CliError('Nothing to send. Usage: agentalarm "text" [--ring] [--at <time>]', EXIT.USAGE);
+  if (options.at !== undefined && !Number.isFinite(Date.parse(options.at))) {
+    throw new CliError(`--at: "${options.at}" is not a date and time like 2026-10-28T09:00.`, EXIT.USAGE);
+  }
+  const alarm = { type: options.urgent ? 'urgent' : 'normal', title };
+  for (const field of ['body', 'color', 'sound', 'icon', 'location']) if (options[field] !== undefined) alarm[field] = options[field];
+  if (options.at !== undefined) alarm.fire_at = options.at;
+
+  const created = await createAlarm(credentials(loadConfig(io.env), io.env), alarm);
+  io.stdout.write(options.json ? `${JSON.stringify(created, null, 2)}\n` : `${describeAlarm(created, alarm)}\n`);
+  return EXIT.OK;
+}
+
+function interactive(io) {
+  return Boolean(io.stdin.isTTY && io.stdout.isTTY);
+}
+
+async function withPrompt(io, fn) {
+  const rl = readline.createInterface({ input: io.stdin, output: io.stdout });
+  try {
+    return await fn((question) => rl.question(question));
+  } finally {
+    rl.close();
+  }
+}
+
+async function setup(options, io) {
+  const config = loadConfig(io.env);
+  let hooks;
+  if (options.defaults) {
+    hooks = { ...HOOK_DEFAULTS };
+  } else if (!interactive(io)) {
+    throw new CliError('Run "agentalarm setup" in a terminal, or "agentalarm setup --defaults".', EXIT.USAGE);
+  } else {
+    hooks = await withPrompt(io, (ask) => askHookSettings(ask, hookSettings(config, {}), (line) => io.stdout.write(`${line}\n`)));
+  }
+  saveConfig({ ...config, hooks }, io.env);
+  io.stdout.write(`Saved to ${configPath(io.env)}:\n${JSON.stringify(hooks, null, 2)}\n`);
+  return EXIT.OK;
+}
+
+async function setupUrlFrom(positional, options, io, announce) {
+  let text = positional.join(' ');
+  if (!text && !io.stdin.isTTY) text = await readStdin(io.stdin, { limit: 64_000, timeoutMs: 10_000 });
+  const setupUrl = extractSetupUrl(text, { server: options.server });
+  if (!setupUrl) {
+    throw new CliError('No AgentAlarm setup link found. In the app: Settings > Connected Agents > Connect, then: agentalarm login "<the copied text>"', EXIT.USAGE);
+  }
+  announce(`Redeeming the one-time link at ${new URL(setupUrl).origin} ...\n`);
+  return setupUrl;
+}
+
+/** A key for CI secrets: written only into a pipe, so it does not land in the terminal's scrollback. */
+async function printKey(positional, options, io) {
+  if (io.stdout.isTTY) {
+    throw new CliError('The key is printed only into a pipe, e.g.: agentalarm key "<text>" | gh secret set AGENTALARM_KEY', EXIT.USAGE);
+  }
+  // stdout is the pipe that receives the key, so the origin goes to stderr.
+  const setupUrl = await setupUrlFrom(positional, options, io, (line) => io.stderr.write(line));
+  const redeemed = await redeemSetup(setupUrl, options.name || `agentalarm CI key from ${hostLabel()}`);
+  io.stdout.write(redeemed.key);
+  io.stderr.write(`Created the key "${redeemed.name}". Revoke it in the app under Connected Agents.\n`);
+  return EXIT.OK;
+}
+
+async function login(positional, options, io) {
+  const setupUrl = await setupUrlFrom(positional, options, io, (line) => io.stdout.write(line));
+  const redeemed = await redeemSetup(setupUrl, options.name || `agentalarm CLI on ${hostLabel()}`);
+  updateConfig((config) => ({ ...config, key: redeemed.key, keyName: redeemed.name, baseUrl: redeemed.baseUrl }), io.env);
+
+  const out = (line = '') => io.stdout.write(`${line}\n`);
+  out(`Connected as "${redeemed.name}". The key is saved in ${configPath(io.env)} (readable only by you).`);
+  if (redeemed.readOnly) out('Note: this key is read-only, so it cannot send alerts. Connect again without "read only".');
+  if (io.env.AGENTALARM_KEY) out('Note: AGENTALARM_KEY is set in this shell and wins over the saved key.');
+
+  if (!options.noSetup && interactive(io)) {
+    const answer = await withPrompt(io, (ask) => ask('Choose when agent hooks alert you now? [Y/n] '));
+    if (!/^n/i.test(answer.trim())) return setup({}, io);
+  }
+  out('Next: "agentalarm setup" chooses when hooks alert you; "agentalarm test" sends a test alert.');
+  return EXIT.OK;
+}
+
+async function status(io) {
+  const config = loadConfig(io.env);
+  const creds = credentials(config, io.env);
+  const out = (line = '') => io.stdout.write(`${line}\n`);
+  out(`Config: ${configPath(io.env)}`);
+  out(`Server: ${creds.baseUrl}`);
+  if (!creds.key) {
+    out('Not logged in. Run: npx agentalarm login "<the text copied from the AgentAlarm app>"');
+    return EXIT.AUTH;
+  }
+  const info = await me(creds);
+  const keyName = info.key && info.key.name ? info.key.name : config.keyName;
+  out(`Connected: key "${keyName}"${creds.fromEnv ? ' (from AGENTALARM_KEY)' : ''}, timezone ${info.timezone ?? 'unknown'}`);
+  if (info.push_registered === false) out('Warning: no iPhone registered for pushes yet. Open the AgentAlarm app once.');
+  const paused = Date.parse(config.pausedUntil ?? '');
+  out(Number.isFinite(paused) && paused > Date.now() ? `Hooks: paused until ${new Date(paused).toLocaleString()}` : 'Hooks: active');
+  out(`Hook settings: ${JSON.stringify(hookSettings(config, io.env))}`);
+  return EXIT.OK;
+}
+
+async function logout(options, io) {
+  const config = loadConfig(io.env);
+  if (!config.key) {
+    io.stdout.write('Not logged in on this computer.\n');
+    return EXIT.OK;
+  }
+  let revoked = false;
+  if (!options.local) {
+    try {
+      await revokeKey({ key: config.key, baseUrl: credentials(config, {}).baseUrl });
+      revoked = true;
+    } catch (error) {
+      io.stderr.write(`Could not revoke the key on the server (${error.message}). Revoke "${config.keyName ?? 'agentalarm CLI'}" in the app.\n`);
+    }
+  }
+  const { key, keyName, ...rest } = config;
+  saveConfig(rest, io.env);
+  io.stdout.write(`Logged out: the key is ${revoked ? 'revoked and ' : ''}removed from this computer.\n`);
+  return EXIT.OK;
+}
+
+function configCommand(args, io) {
+  const [action, name, ...value] = args;
+  const out = (line) => io.stdout.write(`${line}\n`);
+  if (action === undefined) {
+    out(JSON.stringify(hookSettings(loadConfig(io.env), io.env), null, 2));
+    return EXIT.OK;
+  }
+  const names = Object.keys(HOOK_DEFAULTS);
+  if (!['set', 'unset'].includes(action) || !names.includes(name) || (action === 'set' && value.length === 0)) {
+    throw new CliError(`Usage: agentalarm config set <option> <value> | unset <option>. Options: ${names.join(', ')}.`, EXIT.USAGE);
+  }
+  if (action === 'unset') {
+    updateConfig((config) => {
+      const { [name]: removed, ...hooks } = config.hooks ?? {};
+      return { ...config, hooks };
+    }, io.env);
+    out(`${name} is back to the default (${JSON.stringify(HOOK_DEFAULTS[name])}).`);
+    return EXIT.OK;
+  }
+  const parsed = parseHookOption(name, value.join(' '));
+  if (parsed === undefined) throw new CliError(`Invalid value for ${name}: "${value.join(' ')}".`, EXIT.USAGE);
+  updateConfig((config) => ({ ...config, hooks: { ...(config.hooks ?? {}), [name]: parsed } }), io.env);
+  out(`${name} = ${JSON.stringify(parsed)}${io.env[HOOK_ENV_NAMES[name]] !== undefined ? ` (note: ${HOOK_ENV_NAMES[name]} is set and wins)` : ''}`);
+  return EXIT.OK;
+}
+
+function pause(positional, io) {
+  const ms = parseDuration(positional[0] ?? '1h');
+  if (ms === null) throw new CliError('Usage: agentalarm pause [30m|1h|2d] (at most 30 days).', EXIT.USAGE);
+  const until = new Date(Date.now() + ms).toISOString();
+  updateConfig((config) => ({ ...config, pausedUntil: until }), io.env);
+  io.stdout.write(`Hook alerts paused until ${new Date(until).toLocaleString()}. "agentalarm resume" ends the pause.\n`);
+  return EXIT.OK;
+}
+
+function resume(io) {
+  updateConfig(({ pausedUntil, ...config }) => config, io.env);
+  io.stdout.write('Hook alerts resumed.\n');
+  return EXIT.OK;
+}
+
+async function deliverFromEnv(io) {
+  try {
+    await deliver(JSON.parse(io.env.AGENTALARM_DELIVERY || ''), io.env);
+  } catch (error) {
+    logHook(io.env, `delivery failed: ${error.message}`);
+  }
+  return EXIT.OK;
+}
+
+export async function main(argv, io = { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr, env: process.env }) {
+  try {
+    const [command, ...rest] = argv;
+    // Hooks never fail the agent: no option parsing, no error exit.
+    if (command === 'hook') return await runHook(rest[0], io);
+    if (command === '__deliver') return await deliverFromEnv(io);
+    if (command === 'mcp') {
+      await runMcpProxy({ creds: credentials(loadConfig(io.env), io.env), input: io.stdin, output: io.stdout });
+      return EXIT.OK;
+    }
+
+    const { positional, options } = parseArgs(argv);
+    if (options.version) {
+      io.stdout.write(`${VERSION}\n`);
+      return EXIT.OK;
+    }
+    if (options.help || argv.length === 0 || command === 'help') {
+      io.stdout.write(`${HELP}\n`);
+      return argv.length === 0 ? EXIT.USAGE : EXIT.OK;
+    }
+
+    const [name, ...args] = positional;
+    switch (name) {
+      case 'login':
+        return await login(args, options, io);
+      case 'key':
+        return await printKey(args, options, io);
+      case 'logout':
+        return await logout(options, io);
+      case 'status':
+        return await status(io);
+      case 'setup':
+        return await setup(options, io);
+      case 'config':
+        return configCommand(args, io);
+      case 'pause':
+        return pause(args, io);
+      case 'resume':
+        return resume(io);
+      case 'test':
+        return await send('AgentAlarm test: your agents can reach you', { ...options, urgent: true, body: 'Sent by "agentalarm test". Tap Done to stop the ring.' }, io);
+      case 'send':
+        return await send(args.join(' ').trim(), options, io);
+      default:
+        return await send(positional.join(' ').trim(), options, io);
+    }
+  } catch (error) {
+    if (error instanceof CliError) {
+      io.stderr.write(`agentalarm: ${error.message}\n`);
+      return error.exitCode;
+    }
+    io.stderr.write(`agentalarm: unexpected error: ${error.message}\n`);
+    return EXIT.FAILURE;
+  }
+}