@pingroom/cli 0.8.1 → 0.10.0

package/README.md

@@ -41,7 +41,7 @@ question), `list`, `cancel`, `handoff` (hand a decision to a specific human),
 `handoffs` (list open or recent Handoffs), `listen` (hear pings as they land),
 `live` (lock-screen progress card),
 `hook` (Claude Code), `mcp` (client setup), `activate` (send an optional test
-Question), `config`, and `logout`.
+Question), `pair` (connect a machine with no terminal), `config`, and `logout`.
 Run `pingroom --help` for the full reference.
 
 ## Connecting
@@ -66,6 +66,35 @@ Approving on the phone is the whole ceremony — connecting sends nothing else t
 your phone. The status line reflects the grant: `→ #Project X` for one room,
 `→ #Project X +2 more` for several, `→ all rooms` when you granted every room.
 
+### Headless pairing (daemons, containers, OpenClaw)
+
+A machine with no terminal cannot show a QR, so `pingroom pair` prints the
+approval link and waits for it instead. Nothing prompts, nothing draws, and an
+open stdin never holds it:
+
+```
+$ pingroom pair
+  Open: https://pingroom.io/app/agents/pair?token=…
+  Waiting for approval… ✓ Connected as @agt_ab12cd34ef → #Project X
+```
+
+Exit 0 once paired; exit 3 if the 15-minute link expired — run it again for a
+fresh one. It re-pairs too: when a credential already exists the new one is
+saved first, then the old one is revoked.
+
+For a supervisor that reads the link out of a log, `--json` makes stdout one
+JSON object per line (the credential is never printed):
+
+```
+$ pingroom pair --json
+{"event":"pair_url","pair_url":"https://…","expires_in":900,"poll_interval_ms":1500}
+{"event":"connected","handle":"agt_ab12cd34ef","room":{…},"room_access":"selected",…}
+```
+
+Give each service user its own `PINGROOM_HOME`; the credential is written
+`0600` at `$PINGROOM_HOME/credentials.json`. In CI, prefer `PINGROOM_TOKEN`
+over pairing — there is nobody to approve a link.
+
 ## Proving the round-trip (optional)
 
 ```bash
@@ -257,7 +286,12 @@ it **silently**, `end` closes it with one completion alert.
 The management nouns cover the rest of the agent surface (agent token required;
 `--room` where noted):
 
+Room `--icon` takes a v3 catalog id (`bell`, `globe`, `terminal`, …), never an
+emoji — the server rejects anything off-catalog. Browse ids with
+`pingroom rooms icons`. Quick-action `--icon` is the opposite: it takes an emoji.
+
 ```bash
+pingroom rooms icons                      # browse the v3 room-icon catalog
 pingroom rooms list                       # rooms this account belongs to
 pingroom rooms get GZNFB6BZGJIH
 pingroom rooms create -n "Deploys" --icon bell --color "#e33122"
@@ -652,6 +686,10 @@ See <https://pingroom.io/connect-mcp.md> for the complete MCP and OAuth guide.
 
 ## Agent skills
 
+Running under OpenClaw instead of Claude Code? See
+https://pingroom.io/connect-openclaw.md for the skill and headless pairing.
+
+
 Two ready-to-install [Claude Code skills](https://github.com/pingroom/skills)
 teach an agent when and how to reach a human — `pingroom-mcp` for conversational
 sessions, `pingroom-cli` for shells, CI, and hooks.

package/bin/pingroom.js

@@ -43,8 +43,8 @@ import { HELP } from '../lib/help.js';
 import { maybeNotifyUpdate } from '../lib/update-check.js';
 import {
   parseArgs, parseConfigArgs, parseHandoffArgs, parseHandoffsArgs, parseHookArgs,
-  parseLiveArgs, parseLogoutArgs, parseManageArgs, parseQArgs, parseReconnectArgs,
-  parseSkillsArgs,
+  parseLiveArgs, parseLogoutArgs, parseManageArgs, parsePairArgs, parseQArgs,
+  parseReconnectArgs, parseSkillsArgs,
 } from '../lib/parser.js';
 import { actions, approval, attachment, rooms, webhooks } from '../lib/commands/manage.js';
 import { ping } from '../lib/commands/ping.js';
@@ -55,7 +55,7 @@ import { live } from '../lib/commands/live.js';
 import { hook } from '../lib/commands/hook.js';
 import { mcp } from '../lib/commands/mcp.js';
 import { skills } from '../lib/commands/skills.js';
-import { activateStoredInbox, bare, reconnect } from '../lib/commands/connect.js';
+import { activateStoredInbox, bare, pair, reconnect } from '../lib/commands/connect.js';
 import { config, logout } from '../lib/commands/config.js';
 
 const COMMANDS = {
@@ -80,6 +80,7 @@ const COMMANDS = {
   attachment: (rest) => attachment(parseManageArgs(rest)),
   config: (rest) => config(parseConfigArgs(rest)),
   reconnect: (rest) => reconnect(parseReconnectArgs(rest)),
+  pair: (rest) => pair(parsePairArgs(rest)),
   logout: (rest) => logout(parseLogoutArgs(rest)),
 };
 

package/lib/commands/connect.js

@@ -24,6 +24,12 @@ import { CLI_SCOPES } from '../scopes.js';
 // What the human reads on the approval screen. A product name, not a package
 // id: the phone shows it verbatim ("PingRoom CLI wants to connect").
 const AGENT_LABEL = 'PingRoom CLI';
+// One NDJSON record per line on stdout, for `pair --json`. `listen --json`
+// already established the shape: a daemon reads stdout line by line, so nothing
+// else may be written there while it is on.
+function writeEvent(event) {
+  process.stdout.write(`${JSON.stringify(event)}\n`);
+}
 // A connect command should prove the phone round-trip, but it must not hold a
 // terminal for the onboarding Question's full 24-hour server TTL. The Question
 // remains answerable after this local deadline and the credential is already
@@ -446,7 +452,7 @@ export async function activateStoredInbox(args) {
  * token, renders it, then polls until the human approves. Returns a credential
  * object, or null when the pairing lapsed and the user declined a fresh one.
  */
-async function connectByPairing(apiBase, ask) {
+async function connectByPairing(apiBase, ask, { qr = true, json: jsonOut = false } = {}) {
   for (;;) {
     const preClaim = await registerAnonymous(apiBase);
     const headers = { Authorization: `Bearer ${preClaim}` };
@@ -473,11 +479,24 @@ async function connectByPairing(apiBase, ask) {
     // collecting 429s instead of the approval.
     const lifetimeMs = Math.max(1, Number(start.json.expires_in) || 900) * 1000;
     const intervalMs = Math.min(Math.max(Number(start.json.poll_interval_ms) || 1500, 1000), 10_000);
-    const deadline = Date.now() + lifetimeMs;
-
-    const drew = await renderQr(pairUrl);
-    process.stdout.write(`${drew ? '  Or open' : '  Open'}: ${pairUrl}\n`);
-    process.stdout.write('  Waiting for approval… ');
+    const startedAt = Date.now();
+    const deadline = startedAt + lifetimeMs;
+
+    // `qr: false` (headless) forces the QR off rather than leaning on COLUMNS:
+    // an unset width reads as "wide enough" in renderQr, so a daemon with no
+    // terminal would otherwise get block art written into its log pipe.
+    const drew = qr ? await renderQr(pairUrl) : false;
+    if (jsonOut) {
+      writeEvent({
+        event: 'pair_url',
+        pair_url: pairUrl,
+        expires_in: Math.round(lifetimeMs / 1000),
+        poll_interval_ms: intervalMs,
+      });
+    } else {
+      process.stdout.write(`${drew ? '  Or open' : '  Open'}: ${pairUrl}\n`);
+      process.stdout.write('  Waiting for approval… ');
+    }
 
     // A transient failure must not end a wait the human is mid-way through.
     // Network errors, 5xx and 429 are the load balancer / rate limiter talking,
@@ -504,7 +523,10 @@ async function connectByPairing(apiBase, ask) {
         // output cannot tell a slow approval from a broken endpoint.
         if (transientRun === 3 && !warnedTransient) {
           warnedTransient = true;
-          process.stdout.write(`\n  (still trying — ${lastTransient}) `);
+          // stdout stays pure NDJSON in json mode, so progress chatter goes to
+          // stderr, where a daemon's log still shows it.
+          if (jsonOut) process.stderr.write(`pingroom: still trying — ${lastTransient}\n`);
+          else process.stdout.write(`\n  (still trying — ${lastTransient}) `);
         }
         // Ride out a short blip at the normal cadence, then back off
         // geometrically so a real outage is not also a thundering herd. Never
@@ -516,8 +538,29 @@ async function connectByPairing(apiBase, ask) {
 
       transientRun = 0;
 
+      // A 401/403/404 is terminal either way — retrying can only spin — but it
+      // means two different things depending on WHEN it lands, and the user
+      // needs to be told the right one.
+      //
+      // Late: the pre-claim credential this loop authenticates with has the
+      // same 900s TTL as the pairing token (agent_auth.ttl), so once the window
+      // is mostly gone an unapproved pairing 401s instead of returning
+      // {"status":"expired"}. That is the ordinary "nobody tapped it" ending,
+      // and reporting it as an auth error sent people to fix a credential that
+      // was working fine (observed live 2026-09-02).
+      //
+      // Early: the credential was minted seconds ago, so a rejection means the
+      // request is genuinely wrong — a bad --api, a server that is not
+      // PingRoom. Calling that "expired" would hide a real fault behind a
+      // retry the user can never win.
+      if (res.status === 401 || res.status === 403 || res.status === 404) {
+        if (Date.now() - startedAt >= lifetimeMs / 2) break;
+        if (!jsonOut) process.stdout.write('\n');
+        fail(`pairing failed: ${apiDetail(res, json)}`);
+      }
+
       if (!res.ok) {
-        process.stdout.write('\n');
+        if (!jsonOut) process.stdout.write('\n');
         const detail = apiDetail(res, json);
         fail(`pairing failed: ${detail}`);
       }
@@ -528,7 +571,7 @@ async function connectByPairing(apiBase, ask) {
         // every later command reads a credential file that exists but cannot
         // authenticate — a far more confusing failure than stopping here.
         if (typeof json.credential !== 'string' || json.credential === '') {
-          process.stdout.write('\n');
+          if (!jsonOut) process.stdout.write('\n');
           fail('pairing succeeded but the server returned no credential');
         }
         const cred = {
@@ -542,7 +585,21 @@ async function connectByPairing(apiBase, ask) {
           apiBase,
         };
         saveCredential(cred);
-        process.stdout.write(`${connectedLine(cred)}\n`);
+        if (jsonOut) {
+          // No token: this line lands in daemon logs. Everything here is
+          // already visible to the human who just approved the pairing.
+          writeEvent({
+            event: 'connected',
+            handle: cred.handle ?? null,
+            room: cred.room ?? null,
+            room_access: cred.roomAccess,
+            rooms: cred.rooms,
+            scopes: cred.scopes ?? [],
+            api_url: apiBase,
+          });
+        } else {
+          process.stdout.write(`${connectedLine(cred)}\n`);
+        }
         // Connecting deliberately sends nothing to the human's phone. The
         // approval they just tapped IS the round-trip; a test Question on top of
         // it was one more thing to answer before the tool could be used, and it
@@ -555,7 +612,13 @@ async function connectByPairing(apiBase, ask) {
       await sleep(intervalMs);
     }
 
-    if (transientRun > 0) {
+    if (jsonOut) {
+      writeEvent({
+        event: 'expired',
+        reason: transientRun > 0 ? 'server_unavailable' : 'expired',
+        last_error: lastTransient,
+      });
+    } else if (transientRun > 0) {
       process.stdout.write(`\n  Gave up waiting — the server kept failing (last: ${lastTransient}).\n`);
     } else {
       process.stdout.write(`\n  That code expired.\n`);
@@ -566,6 +629,11 @@ async function connectByPairing(apiBase, ask) {
     // means "take the default: yes"), restart the for(;;), mint another
     // anonymous registration, and do it again — a Ctrl-D or a piped stdin turns
     // a single pairing attempt into thousands of registrations against the API.
+    // `ask === null` is the headless contract: one round, no prompt, no retry.
+    // Distinct from ask() returning null at EOF just below — both stop here,
+    // and neither may loop the for(;;) into minting more registrations.
+    if (!ask) return null;
+
     const again = await ask('  Show a fresh QR code? [Y/n]: ');
     if (again === null) { process.stdout.write('\n'); return null; }
     const answer = again.trim().toLowerCase();
@@ -643,7 +711,7 @@ async function connectByEmail(apiBase, ask) {
 export async function connect(args) {
   if (!isInteractive()) {
     fail(
-      'not connected, and this is not an interactive terminal. Set PINGROOM_TOKEN (CI, pipes), or run "pingroom" from a terminal to pair.',
+      'not connected, and this is not an interactive terminal. Set PINGROOM_TOKEN (CI, pipes), run "pingroom pair" to pair without a terminal, or run "pingroom" from a terminal.',
       EXIT.USAGE,
     );
   }
@@ -705,7 +773,7 @@ export async function bare(args) {
   }
 
   if (!isInteractive()) {
-    process.stderr.write('pingroom: not connected. Set PINGROOM_TOKEN, or run "pingroom" from an interactive terminal to pair.\n');
+    process.stderr.write('pingroom: not connected. Set PINGROOM_TOKEN, run "pingroom pair" to pair without a terminal, or run "pingroom" from an interactive terminal.\n');
     process.stdout.write(`${HELP}\n`);
     return EXIT.OK;
   }
@@ -757,7 +825,7 @@ export async function reconnect(args) {
   }
 
   if (!isInteractive()) {
-    fail('reconnect needs an interactive terminal to show the QR code.', EXIT.USAGE);
+    fail('reconnect needs an interactive terminal to show the QR code. Run "pingroom pair" instead — it prints the approval link and waits.', EXIT.USAGE);
   }
 
   const apiBase = resolveApiBase(args);
@@ -768,10 +836,7 @@ export async function reconnect(args) {
   // live production credential to an arbitrary host.
   requireStoredCredentialOrigin(args, apiBase);
 
-  process.stdout.write('  Reconnecting updates the permissions this CLI holds.\n');
-  process.stdout.write('  Your current connection keeps working until the new one is approved,\n');
-  process.stdout.write('  and is then revoked — any other machine or CI job using that same\n');
-  process.stdout.write('  credential will stop working.\n\n');
+  printReplaceNotice();
 
   const prompter = createPrompter();
   const ask = (question) => prompter.ask(question);
@@ -789,8 +854,19 @@ export async function reconnect(args) {
     return EXIT.EXPIRED;
   }
 
-  // The new credential is already durable (connectByPairing saved it). From
-  // here on, failing to revoke is untidy, not dangerous.
+  return revokePrevious(apiBase, stored);
+}
+
+/**
+ * Step 4 of the reconnect contract, shared with `pair`: revoke the credential
+ * the new one replaces, using the OLD bearer.
+ *
+ * Only ever called after connectByPairing has already written the replacement,
+ * so a failure here is untidy rather than dangerous — it leaves a stale-but-
+ * harmless registration the human can remove from Connected Agents, which is
+ * why it returns EXIT.OK either way.
+ */
+async function revokePrevious(apiBase, stored, { json: jsonOut = false } = {}) {
   const { res, json, error } = await httpJson('POST', `${apiBase}/api/agent/auth/revoke`, {
     headers: { Authorization: `Bearer ${stored.token}` },
     body: {},
@@ -798,11 +874,86 @@ export async function reconnect(args) {
   });
   if (error || !res || !res.ok) {
     const detail = error ? error.message : apiDetail(res, json);
-    process.stdout.write(`  Note: the previous connection could not be revoked (${detail}).\n`);
-    process.stdout.write('  Remove it from PingRoom → Settings → Connected Agents when convenient.\n');
+    if (jsonOut) {
+      writeEvent({ event: 'previous_connection', revoked: false, detail });
+    } else {
+      process.stdout.write(`  Note: the previous connection could not be revoked (${detail}).\n`);
+      process.stdout.write('  Remove it from PingRoom → Settings → Connected Agents when convenient.\n');
+    }
     return EXIT.OK;
   }
 
-  process.stdout.write('  Previous connection revoked.\n');
+  if (jsonOut) writeEvent({ event: 'previous_connection', revoked: true });
+  else process.stdout.write('  Previous connection revoked.\n');
+  return EXIT.OK;
+}
+
+/** The four lines a human sees before re-pairing replaces a live credential. */
+function printReplaceNotice() {
+  process.stdout.write('  Reconnecting updates the permissions this CLI holds.\n');
+  process.stdout.write('  Your current connection keeps working until the new one is approved,\n');
+  process.stdout.write('  and is then revoked — any other machine or CI job using that same\n');
+  process.stdout.write('  credential will stop working.\n\n');
+}
+
+// --- pair -------------------------------------------------------------------
+
+/**
+ * Pairing for machines with no terminal: print the approval link, wait once,
+ * save, and (when replacing a stored credential) revoke the old one.
+ *
+ * Deliberately a separate command rather than a flag or a non-TTY fallback.
+ * AGENT_PAIRING_SPEC.md § CLI behaviour requires that a non-interactive
+ * `pingroom` keep exiting 0 with the PINGROOM_TOKEN hint — `pingroom | head`
+ * is a normal thing to do, and silently starting a 15-minute poll there would
+ * mint a registration from any stray pipe. Asking for `pair` is the consent.
+ *
+ * Differences from the interactive path, all of them deliberate:
+ *   - never renders a QR (nothing can scan a log pipe);
+ *   - never prompts, and never constructs a prompter, so an open stdin cannot
+ *     hold the process open and a closed one cannot end it early;
+ *   - exactly one round — an expired link exits 3 rather than offering another,
+ *     because there is no human at this terminal to answer the offer.
+ */
+export async function pair(args) {
+  if (args.help) { process.stdout.write(`${commandHelp('pair')}\n`); return EXIT.OK; }
+  if (args._ && args._.length > 0) {
+    fail('usage: pingroom pair [--api <url>] [--json]', EXIT.USAGE);
+  }
+
+  // Same reasoning as reconnect: an env token is not ours to replace, and
+  // pairing into a credential that PINGROOM_TOKEN immediately shadows would
+  // look like it worked while every later command used the other one.
+  if (process.env.PINGROOM_TOKEN) {
+    fail(
+      'PINGROOM_TOKEN is set, and it would shadow whatever this pairing stores.\n'
+      + '  Unset it and run "pingroom pair" again, or keep using the token as-is.',
+      EXIT.USAGE,
+    );
+  }
+
+  const jsonOut = Boolean(args.json);
+  const apiBase = resolveApiBase(args);
+  requireSafeUrl('--api', apiBase);
+
+  // Re-pairing sends the stored credential to `apiBase` in the revoke below, so
+  // it is bound by the same origin rule as every other stored-bearer command.
+  const stored = readStoredCredential();
+  if (stored) {
+    requireStoredCredentialOrigin(args, apiBase);
+    if (!jsonOut) printReplaceNotice();
+  }
+
+  const cred = await connectByPairing(apiBase, null, { qr: false, json: jsonOut });
+
+  if (!cred) {
+    if (!jsonOut) {
+      process.stdout.write('  Run "pingroom pair" again for a fresh link.\n');
+      if (stored) process.stdout.write('  Kept your current connection.\n');
+    }
+    return EXIT.EXPIRED;
+  }
+
+  if (stored) return revokePrevious(apiBase, stored, { json: jsonOut });
   return EXIT.OK;
 }

package/lib/commands/manage.js

@@ -38,9 +38,21 @@ function printJsonOr(args, text, lines) {
 
 export async function rooms(args) {
   if (args.help) { process.stdout.write(`${commandHelp('rooms')}\n`); return EXIT.OK; }
-  const action = sub(args, ['list', 'get', 'create', 'join'], 'rooms');
+  const action = sub(args, ['list', 'get', 'create', 'join', 'icons'], 'rooms');
   const { token, apiBase } = agentContext(args);
 
+  if (action === 'icons') {
+    const { text, json } = await requireOk(
+      httpJson('GET', `${apiBase}/api/agent/room-icons`, { headers: auth(token) }),
+      'rooms icons',
+    );
+    if (args.json) { process.stdout.write(`${text}\n`); return EXIT.OK; }
+    const categories = Array.isArray(json.categories) ? json.categories : [];
+    const lines = categories.map((c) => `${c.label ?? c.id}: ${(c.icons ?? []).join(' ')}`);
+    process.stdout.write(`${lines.join('\n') || '(no icons)'}\n`);
+    return EXIT.OK;
+  }
+
   if (action === 'list') {
     const { text, json } = await requireOk(
       httpJson('GET', `${apiBase}/api/agent/rooms`, { headers: auth(token) }),
@@ -69,17 +81,18 @@ export async function rooms(args) {
       httpJson('POST', `${apiBase}/api/agent/rooms/join`, { headers: auth(token), body: { invite_code: code } }),
       'rooms join',
     );
-    printJsonOr(args, text, `joined ${json.room?.name ?? code}`);
+    // The server returns the room flat, so `json.room` is never set and the
+    // name always fell back to the invite code.
+    printJsonOr(args, text, `joined ${json.room?.name ?? json.name ?? code}`);
     return EXIT.OK;
   }
 
   // create — private by default; --public requires --handle and uses the
   // dedicated consent scope on the server.
   if (!args.name) fail('rooms create needs --name', EXIT.USAGE);
-  if (!args.icon || !args.color) fail('rooms create needs --icon and --color (see "pingroom rooms list-icons" via the app, e.g. --icon bell --color "#e33122")', EXIT.USAGE);
+  if (!args.icon || !args.color) fail('rooms create needs --icon and --color. --icon is a v3 catalog id, not an emoji — run "pingroom rooms icons" to browse, e.g. --icon bell --color "#e33122"', EXIT.USAGE);
 
   const body = { name: args.name, icon: args.icon, color: args.color };
-  if (args.description) body.description = args.description;
 
   let url = `${apiBase}/api/agent/rooms`;
   if (args.public) {
@@ -88,6 +101,17 @@ export async function rooms(args) {
     url = `${apiBase}/api/agent/rooms/public`;
   }
 
+  // The ordinary rooms:write scope creates a MINIMAL private room: the server
+  // marks description (with is_public, handle, category, actions and friends)
+  // `prohibited` there and answers 422. Only the public create carries them.
+  // Say so here rather than posting a request that cannot succeed.
+  if (args.description !== undefined) {
+    if (!args.public) {
+      fail('--description is only accepted on a public room (add --public --handle <handle>). A private agent room is created minimal; set its description from the app.', EXIT.USAGE);
+    }
+    body.description = args.description;
+  }
+
   const { text, json } = await requireOk(httpJson('POST', url, { headers: auth(token), body }), 'rooms create');
   printJsonOr(args, text, `created ${json.room?.invite_code ?? json.invite_code ?? ''} ${args.name}`.trim());
   return EXIT.OK;
@@ -128,7 +152,13 @@ export async function webhooks(args) {
     if (!body.name) fail('webhooks create needs --name', EXIT.USAGE);
     const { text, json } = await requireOk(httpJson('POST', base, { headers: auth(token), body }), 'webhooks create');
     // The trigger URL carries the webhook secret — print it once, like the app.
-    printJsonOr(args, text, `created ${json.webhook?.id ?? ''}\n${json.webhook?.url ?? json.url ?? ''}`.trim());
+    // The server answers with the webhook FLAT plus `webhook_url`; the nested
+    // shapes are only kept as fallbacks. Reading `json.webhook.*` alone printed
+    // a bare "created" and swallowed the one credential this command exists to
+    // hand over.
+    const created = json.webhook ?? json;
+    const url = created.webhook_url ?? created.url ?? json.webhook_url ?? json.url ?? '';
+    printJsonOr(args, text, `created ${created.id ?? ''}\n${url}`.trim());
     return EXIT.OK;
   }
 
@@ -169,7 +199,12 @@ export async function actions(args) {
     return EXIT.OK;
   }
 
-  if (!args.label || !args.icon) fail('actions set needs --label and --icon', EXIT.USAGE);
+  // A Ping's title is optional — its emoji can be the whole name — so
+  // `--label ""` is a deliberate value, not a missing flag. The emoji is the
+  // half that must be there.
+  if (args.label === undefined || !args.icon) {
+    fail('actions set needs --label (may be empty) and --icon', EXIT.USAGE);
+  }
   const body = { label: args.label, icon: args.icon };
   if (args.sound !== undefined) body.sound = args.sound;
   if (args.require_ack) body.requires_ack = true;

package/lib/commands/skills.js

@@ -65,6 +65,8 @@ Or by hand:
   git clone ${SKILLS_CLONE_URL} /tmp/pingroom-skills
 ${SKILLS.map((s) => `  cp -r /tmp/pingroom-skills/${s.source.join('/')} ${claudeSkillsDir()}`).join('\n')}
 
+OpenClaw (headless agents): https://pingroom.io/connect-openclaw.md
+
 Only "pingroom skills install" writes anything; this listing does not.
 `);
   return EXIT.OK;

package/lib/config.js

@@ -173,7 +173,7 @@ export function agentContext(args, { needRoom = false } = {}) {
   const token = resolveToken(args);
   if (!token) {
     fail(
-      'an agent token is required (--token or PINGROOM_TOKEN). Run "pingroom" in an interactive terminal to connect this machine; in CI set PINGROOM_TOKEN.',
+      'an agent token is required (--token or PINGROOM_TOKEN). Run "pingroom" in an interactive terminal to connect this machine, or "pingroom pair" where there is no terminal; in CI set PINGROOM_TOKEN.',
       EXIT.USAGE,
     );
   }

package/lib/help.js

@@ -32,13 +32,15 @@ Commands:
            Claude Desktop
   skills   List the PingRoom agent skills, or install them for Claude Code
   activate Retry Agent Inbox activation with the saved QR-paired credential
-  rooms    List, inspect, create, or join rooms (rooms list|get|create|join)
+  rooms    List, inspect, create, or join rooms; browse the icon catalog
+           (rooms list|get|create|join|icons)
   webhooks Manage a room's incoming webhooks (webhooks list|create|update|delete)
   actions  List, configure, or trigger a room's quick actions (actions list|set|trigger)
   approval Send an approve/deny request; with --wait, block on the decision
   attachment Download or delete an attachment by id (attachment get|delete)
   config   Read/write local settings (config list | get <key> | set <key> <val>)
   reconnect Re-approve this CLI so it holds every permission it needs
+  pair     Pair without a terminal: print the approval link and wait
   logout   Forget the stored credential`;
 
 export const HELP_PING = `ping options:
@@ -217,7 +219,8 @@ export const HELP_TAIL = `Connecting:
   intentionally, provide that host's token with --token or PINGROOM_TOKEN.
 
   Non-interactive shells (CI, pipes) never prompt and never draw a QR: set
-  PINGROOM_TOKEN there instead.
+  PINGROOM_TOKEN there, or run "pingroom pair" to pair a machine that has no
+  terminal (it prints the approval link and waits).
 
 Examples:
   pingroom ping -w "$PINGROOM_WEBHOOK_URL" -m "Deploy succeeded ✅"
@@ -313,10 +316,14 @@ export const COMMAND_HELP_SECTIONS = {
   rooms: `rooms (agent token required):
   pingroom rooms list               List the rooms this account belongs to
   pingroom rooms get <code>         Show one room
+  pingroom rooms icons              Browse the v3 room-icon catalog
   pingroom rooms create -n <name> --icon <id> --color <hex>
-                                    Create a private room (add --description);
+                                    Create a minimal private room.
+                                    --icon is a v3 catalog id from "rooms icons"
+                                    (e.g. bell), NOT an emoji;
                                     --public --handle <handle> creates a public
-                                    room under its own consent scope
+                                    room under its own consent scope, and is
+                                    the only create that takes --description
   pingroom rooms join <code>        Join a room by invite code`,
   webhooks: `webhooks (agent token + --room required):
   pingroom webhooks list --room <code>
@@ -329,6 +336,7 @@ export const COMMAND_HELP_SECTIONS = {
   actions: `actions (agent token + --room required):
   pingroom actions list --room <code>
   pingroom actions set <1-4> --room <code> --label <text> --icon <emoji>
+                                          (--label "" makes an emoji-only Ping)
                                     Optional: --sound, --require-ack
   pingroom actions trigger <1-4> --room <code>`,
   approval: `approval (agent token + --room required):
@@ -345,6 +353,21 @@ export const COMMAND_HELP_SECTIONS = {
                                     Download; bytes go to --out or stdout
   pingroom attachment delete <id>   Delete an unclaimed upload`,
   config: HELP_CONFIG,
+  pair: `pair (no terminal required):
+  pingroom pair                     Print a PingRoom approval link, wait for the
+                                    human to approve it on their phone, and save
+                                    the credential. For daemons, containers, and
+                                    agent runtimes with no TTY.
+                                    Re-pairs when a credential already exists:
+                                    the new one is saved first, then the old one
+                                    is revoked.
+                                    Exits 0 once paired, 3 if the link expired
+                                    (run it again for a fresh one).
+      --api <url>            API base URL (default https://api.pingroom.io)
+      --json                 One JSON object per line on stdout:
+                             {"event":"pair_url","pair_url":…,"expires_in":…}
+                             first, then {"event":"connected","handle":…}.
+                             The credential is never printed.`,
   reconnect: `reconnect:
   pingroom reconnect                Re-approve this CLI with the permissions the
                                     current version needs, then revoke the old
@@ -376,6 +399,9 @@ export const COMMAND_HELP_FOOTERS = {
   // with the credential it is about to replace.
   reconnect: `Shared:
   -h, --help             Show this help`,
+  // pair writes the stored credential, so --token is meaningless here too.
+  pair: `Shared:
+  -h, --help             Show this help`,
   // `skills` reaches GitHub, never the PingRoom API, so the shared credential
   // and --json flags would all be lies here.
   skills: `Shared:

package/lib/http.js

@@ -35,7 +35,13 @@ export function apiDetail(res, json) {
   const base = stripControlChars(
     (json && (json.message || json.error || json.code)) || `HTTP ${res ? res.status : 'error'}`,
   );
-  const hint = json && typeof json.code === 'string' ? API_HINTS[json.code] : undefined;
+  let hint = json && typeof json.code === 'string' ? API_HINTS[json.code] : undefined;
+  // A 401 means the stored credential is dead (revoked in the app, or the
+  // pairing was cleaned up). Without this line the CLI prints a bare
+  // "Unauthenticated." and leaves the user to guess the remedy.
+  if (!hint && res && res.status === 401) {
+    hint = 'This credential is no longer valid — run "pingroom reconnect" to pair again.';
+  }
   return hint ? `${base}\n  ${hint}` : base;
 }
 

package/lib/parser.js

@@ -214,6 +214,15 @@ export const parseReconnectArgs = makeParser({
   bareDashIsPositional: true,
 });
 
+// pair is reconnect's headless twin and takes no --token for the same reason:
+// the credential it writes is the one on disk. --json makes stdout an NDJSON
+// stream a daemon can read the approval link out of.
+export const parsePairArgs = makeParser({
+  aliases: { '--api': 'api', '--json': 'json', '-h': 'help', '--help': 'help' },
+  booleans: ['json', 'help'],
+  bareDashIsPositional: true,
+});
+
 export const parseLogoutArgs = makeParser({
   aliases: { '-h': 'help', '--help': 'help' },
   booleans: ['help'],

package/lib/scopes.js

@@ -75,7 +75,11 @@ export const COMMAND_SCOPES = {
   skills: [],
   config: [],
   logout: [],
+  // reconnect and pair mint their OWN pre-claim credential and only touch the
+  // unscoped pair/start, pair/status and revoke routes, so they request nothing
+  // here. What they ask the human to approve is CLI_SCOPES above.
   reconnect: [],
+  pair: [],
 };
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pingroom/cli",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Send PingRoom Pings and wait for human decisions from CI, scripts, and agents.",
   "type": "module",
   "bin": {