@pidgeon-ai/cli 2.1.0 → 2.4.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 2.4.0
+
+- `pidgeon agents rename <id> <name>`, `pidgeon agents revoke <id>`,
+  `pidgeon keys revoke <agent-id> <kid>` and `pidgeon pods list|create|remove`.
+- Lists that page (`agents`, `inboxes`, `mail list`, `search`, `threads
+list`, `events`) take `--limit` and `--cursor`, and end with
+  `More: --cursor <next>` when there is more; they were cut off silently.
+- `mail list` shows sent mail by who it went to, not the inbox's address.
+- `agents create` and `inboxes create` take `--pod`.
+- `keys proof` takes `--name`, so the key file names its agent.
+- Signed requests carry a nonce and cover the query (SDK 2.4.0).
+
+## 2.3.0
+
+- `pidgeon webhooks create --inbox <id>...` takes several inboxes.
+- `--days` must be a whole number of days; `abc` used to ask for 30.
+- The help lists `--cc` and `--bcc`, and that `drafts create` takes the
+  same options as `send`.
+
+## 2.2.0
+
+- `pidgeon webhooks create --inbox <id>`: the endpoint hears only that
+  inbox's events; `webhooks list` shows an endpoint's inboxes.
+
 ## 2.1.0
 
 - Email: `pidgeon mail list|read|wait`, `pidgeon search`, `pidgeon threads

package/README.md

@@ -17,6 +17,9 @@ or `PIDGEON_AGENT_KEY` (the file's `private_jwk`) and `PIDGEON_DIRECTORY`.
 
 ```sh
 pidgeon agents show <agent-id>        # its keys, and how websites see it
+pidgeon agents rename <agent-id> "Table agent"
+pidgeon keys revoke <agent-id> <kid>  # requests signed with it stop verifying
+pidgeon agents revoke <agent-id>      # it and every key; cannot be undone
 pidgeon inboxes create bookings --agent <agent-id>
 pidgeon send <inbox-id> --to ana@example.com --subject "Table for two" --text "Friday at 8?"
 pidgeon drafts create <inbox-id> --to ana@example.com --subject "…" --text "…"
@@ -28,10 +31,13 @@ pidgeon app-passwords create <inbox-id> "Apple Mail"
 pidgeon sites create Shop --redirect https://shop.example/callback
 pidgeon reports create <verification-id> --category spam --evidence "…"
 pidgeon events
+pidgeon pods list | create <name> | remove <pod-id>
 pidgeon api GET /v1/email/rules       # any /v1 call
 ```
 
 `pidgeon --help` lists every command; `--json` prints the API's own answer.
+A list prints a page at a time (`--limit`); when there is more, its last line
+is the `--cursor` that reads the next page.
 
 Signing in opens the browser once; the session is kept in
 `~/.config/pidgeon/credentials.json` and refreshed. On a machine with no

package/dist/cli.d.ts

@@ -1,4 +1,4 @@
-export declare const VERSION = "2.1.0";
+export declare const VERSION = "2.4.0";
 export type Io = {
     out: (line: string) => void;
     err: (line: string) => void;

package/dist/cli.js

@@ -9,7 +9,7 @@
 import { parseArgs } from 'node:util';
 import { PidgeonError } from '@pidgeon-ai/sdk';
 import { addAgentKey, baseUrlOf, clientFromEnvironment, listAgentKeys, makeKeyProof, readSession, setUpAgent, signIn, signOut, } from '@pidgeon-ai/sdk/node';
-export const VERSION = '2.1.0';
+export const VERSION = '2.4.0';
 const HELP = `pidgeon ${VERSION}: Pidgeon from a terminal.
 
 Signing in
@@ -19,14 +19,17 @@ Signing in
   Or set PIDGEON_API_KEY; it wins over a session. PIDGEON_BASE_URL points elsewhere.
 
 Agents (Passport)
-  pidgeon agents list
-  pidgeon agents create <name> [--purpose <text>]
+  pidgeon agents list [--limit <n>] [--cursor <cursor>]
+  pidgeon agents create <name> [--purpose <text>] [--pod <pod-id>]
       Registers the agent, makes its key on this machine, publishes the public
       half signed with it, and keeps the key here (pidgeon keys list).
   pidgeon agents show <agent-id>          its keys and its operator's reputation
+  pidgeon agents rename <agent-id> <name> [--purpose <text>]
+  pidgeon agents revoke <agent-id>        it and every key it has; cannot be undone
   pidgeon keys create <agent-id>          a new key for it, made here
   pidgeon keys list                       the keys this machine keeps
-  pidgeon keys proof <agent-id> --directory <url> --url <publish-url>
+  pidgeon keys revoke <agent-id> <kid>    requests signed with it stop verifying
+  pidgeon keys proof <agent-id> --directory <url> --url <publish-url> [--name <agent name>]
       For the hosted MCP server: makes the key here, keeps it, and prints the
       public half and the signed proof that publishing needs. No sign-in.
 
@@ -41,19 +44,21 @@ Sign in with Pidgeon (Auth)
   pidgeon mandates request --agent <id> --client <client-id> --scope <scope> --description <text> [--days <n>]
 
 Email
-  pidgeon inboxes list
-  pidgeon inboxes create <name> [--kind agent|events] [--agent <id>] [--domain <your domain>]
+  pidgeon inboxes list [--limit <n>] [--cursor <cursor>]
+  pidgeon inboxes create <name> [--kind agent|events] [--agent <id>] [--domain <your domain>] [--pod <pod-id>]
   pidgeon inboxes remove <inbox-id>
-  pidgeon send <inbox-id> --to <address>... --subject <text> (--text <body> | --html <body>) [--reply-to <message-id>]
-  pidgeon drafts create <inbox-id> --to <address>... --subject <text> --text <body>
+  pidgeon send <inbox-id> --to <address>... [--cc <address>...] [--bcc <address>...] --subject <text>
+      (--text <body> | --html <body>) [--reply-to <message-id>]
+  pidgeon drafts create <inbox-id>       the same options as send
   pidgeon drafts show|remove <draft-id>
   pidgeon drafts send <draft-id> [--at <ISO time>]
   pidgeon drafts approval <draft-id>      hold it for a person to send or reject
-  pidgeon mail list <inbox-id>            the inbox's mail, newest first
+  pidgeon mail list <inbox-id> [--limit <n>] [--cursor <cursor>]   the inbox's mail, newest first
   pidgeon mail read <message-id> [--original]   cleaned by the Firewall unless --original
   pidgeon mail wait <inbox-id> [--since <time|message-id>] [--timeout <seconds>]
-  pidgeon search <words> [--inbox <inbox-id>]
+  pidgeon search <words> [--inbox <inbox-id>] [--limit <n>] [--cursor <cursor>]
   pidgeon threads list [--inbox <inbox-id>] [--folder inbox|archive|spam|trash]
+      [--limit <n>] [--cursor <cursor>]
   pidgeon threads show <thread-id>
   pidgeon threads file <thread-id> --folder inbox|archive|spam|trash
   pidgeon threads hand-over <thread-id>   to a person: owner human, status human_review
@@ -61,10 +66,14 @@ Email
   pidgeon app-passwords list <inbox-id> | revoke <app-password-id>
 
 The account
-  pidgeon events [--type <type>] [--limit <n>]
-  pidgeon webhooks list | create <url> --event <type>... | remove <webhook-id>
+  pidgeon events [--type <type>] [--limit <n>] [--cursor <cursor>]
+  pidgeon pods list | create <name> | remove <pod-id>
+  pidgeon webhooks list | create <url> --event <type>... [--inbox <id>...] | remove <webhook-id>
   pidgeon api <GET|POST|PATCH|DELETE> <path> [--data <json>]    any /v1 call
 
+A list prints a page at a time; when there is more, its last line is the
+--cursor that reads the next page.
+
 Add --json to any command for the API's own JSON.`;
 const OPTIONS = {
     json: { type: 'boolean' },
@@ -92,7 +101,7 @@ const OPTIONS = {
     original: { type: 'boolean' },
     since: { type: 'string' },
     timeout: { type: 'string' },
-    inbox: { type: 'string' },
+    inbox: { type: 'string', multiple: true },
     folder: { type: 'string' },
     event: { type: 'string', multiple: true },
     method: { type: 'string' },
@@ -104,6 +113,8 @@ const OPTIONS = {
     client: { type: 'string' },
     description: { type: 'string' },
     days: { type: 'string' },
+    name: { type: 'string' },
+    cursor: { type: 'string' },
 };
 class Usage extends Error {
 }
@@ -148,6 +159,18 @@ function need(value, what) {
         throw new Usage(`Say which ${what}.`);
     return value;
 }
+/** An option given at most once. */
+function one(values, flag) {
+    if (values && values.length > 1)
+        throw new Usage(`Give ${flag} once here.`);
+    return values?.[0];
+}
+function wholeDays(value) {
+    const days = Number(value);
+    if (!Number.isInteger(days) || days < 1)
+        throw new Usage('--days is a whole number of days.');
+    return days;
+}
 function message(values) {
     if (!values.to?.length)
         throw new Usage('Send it to someone: --to <address>.');
@@ -176,6 +199,10 @@ async function dispatch(positionals, values, io) {
             for (const line of plain())
                 io.out(line);
     };
+    /** A page's lines, and how to read the next page when there is one. */
+    const paged = (page, lines) => page.next_cursor ? [...lines, `More: --cursor ${page.next_cursor}`] : lines;
+    const cursor = values.cursor;
+    const limit = values.limit ? Number(values.limit) : undefined;
     switch (command) {
         case 'login': {
             const scope = (values.scope ?? 'admin');
@@ -222,14 +249,14 @@ async function dispatch(positionals, values, io) {
         case 'agents': {
             const pidgeon = client();
             if (sub === 'list') {
-                const page = await pidgeon.agents.list();
+                const page = await pidgeon.agents.list({ cursor, limit });
                 show(page, () => page.data.length
-                    ? page.data.map((a) => `${a.id}  ${a.status.padEnd(7)}  ${a.name}`)
+                    ? paged(page, page.data.map((a) => `${a.id}  ${a.status.padEnd(7)}  ${a.name}`))
                     : ['No agents yet: pidgeon agents create <name>.']);
             }
             else if (sub === 'create') {
                 const name = need(arg, 'name to give the agent');
-                const made = await setUpAgent(pidgeon, { name, purpose: values.purpose }, io.env);
+                const made = await setUpAgent(pidgeon, { name, purpose: values.purpose, podId: values.pod }, io.env);
                 show({ agent: made.agent, kid: made.kid, key_file: made.keyFile }, () => [
                     `Registered ${made.agent.name} (${made.agent.id}) and published its key ${made.kid}.`,
                     `Its private key is in ${made.keyFile}, on this machine only.`,
@@ -250,8 +277,25 @@ async function dispatch(positionals, values, io) {
                     ...(agent.reputation.next ? [agent.reputation.next] : []),
                 ]);
             }
+            else if (sub === 'rename') {
+                const id = need(arg, 'agent (its id)');
+                const name = positionals.slice(3).join(' ') || undefined;
+                if (!name && values.purpose === undefined)
+                    throw new Usage('pidgeon agents rename <agent-id> <name> [--purpose <text>]');
+                const agent = await pidgeon.agents.update(id, { name, purpose: values.purpose });
+                show(agent, () => [
+                    `${agent.name} (${agent.id})${agent.purpose ? `: ${agent.purpose}` : ''}`,
+                ]);
+            }
+            else if (sub === 'revoke') {
+                const id = need(arg, 'agent (its id)');
+                await pidgeon.agents.revoke(id);
+                show({ revoked: id }, () => [
+                    'Revoked, with every key it had. No request it signs verifies again.',
+                ]);
+            }
             else
-                throw new Usage('pidgeon agents list | create <name> | show <id>');
+                throw new Usage('pidgeon agents list | create <name> | show <id> | rename <id> <name> | revoke <id>');
             return;
         }
         case 'keys': {
@@ -271,20 +315,26 @@ async function dispatch(positionals, values, io) {
                 const agentId = need(arg, 'agent (its id)');
                 const directory = need(values.directory, 'directory (--directory)');
                 const publishUrl = values.url ?? `${baseUrl}/v1/agents/${encodeURIComponent(agentId)}/keys`;
-                const proof = await makeKeyProof({ agentId, directory, publishUrl }, io.env);
+                const proof = await makeKeyProof({ agentId, directory, publishUrl, name: values.name }, io.env);
                 // Always JSON: it is for a coding agent to hand to publish_agent_key.
                 io.out(JSON.stringify(proof, null, 2));
             }
+            else if (sub === 'revoke') {
+                const agentId = need(arg, 'agent (its id)');
+                const kid = need(positionals[3], 'key (its kid: pidgeon agents show <agent-id>)');
+                await client().agents.revokeKey(agentId, kid);
+                show({ revoked: kid }, () => [`Revoked ${kid}. Requests signed with it stop verifying.`]);
+            }
             else
-                throw new Usage('pidgeon keys create <agent-id> | list | proof <agent-id>');
+                throw new Usage('pidgeon keys create <agent-id> | list | proof <agent-id> | revoke <agent-id> <kid>');
             return;
         }
         case 'inboxes': {
             const pidgeon = client();
             if (sub === 'list') {
-                const page = await pidgeon.inboxes.list();
+                const page = await pidgeon.inboxes.list({ cursor, limit });
                 show(page, () => page.data.length
-                    ? page.data.map((i) => `${i.id}  ${i.kind.padEnd(6)}  ${i.address}`)
+                    ? paged(page, page.data.map((i) => `${i.id}  ${i.kind.padEnd(6)}  ${i.address}`))
                     : ['No inboxes yet.']);
             }
             else if (sub === 'create') {
@@ -294,6 +344,7 @@ async function dispatch(positionals, values, io) {
                     kind,
                     agentId: values.agent,
                     domain: values.domain,
+                    podId: values.pod,
                 });
                 show(inbox, () => [`Made ${inbox.address} (${inbox.id}).`]);
             }
@@ -430,7 +481,7 @@ async function dispatch(positionals, values, io) {
                     clientId: need(values.client, 'site (--client, its client_id)'),
                     scope: need(values.scope, 'scope (--scope)'),
                     description: need(values.description, 'what for (--description)'),
-                    days: values.days ? Number(values.days) : undefined,
+                    days: values.days === undefined ? undefined : wholeDays(values.days),
                 });
                 show(made, () => [`Send the person this link to allow or decline: ${made.consent_url}`]);
             }
@@ -444,10 +495,12 @@ async function dispatch(positionals, values, io) {
         }
         case 'mail': {
             const pidgeon = client();
-            const line = (m) => `${m.id}  ${m.created_at.slice(0, 16)}  ${m.direction === 'in' ? '←' : '→'} ${m.from.address}  ${m.is_held ? '[held for a person]' : (m.subject ?? '')}${m.direction === 'in' && !m.seen ? '  (unread)' : ''}`;
+            const line = (m) => 
+            // Received mail names who sent it; sent mail, who it went to.
+            `${m.id}  ${m.created_at.slice(0, 16)}  ${m.direction === 'in' ? `← ${m.from.address}` : `→ ${m.to.join(', ')}`}  ${m.is_held ? '[held for a person]' : (m.subject ?? '')}${m.direction === 'in' && !m.seen ? '  (unread)' : ''}`;
             if (sub === 'list') {
-                const page = await pidgeon.messages.list(need(arg, 'inbox (its id)'));
-                show(page, () => (page.data.length ? page.data.map(line) : ['No mail yet.']));
+                const page = await pidgeon.messages.list(need(arg, 'inbox (its id)'), { cursor, limit });
+                show(page, () => (page.data.length ? paged(page, page.data.map(line)) : ['No mail yet.']));
             }
             else if (sub === 'read') {
                 const m = await pidgeon.messages.get(need(arg, 'message (its id)'), {
@@ -487,10 +540,12 @@ async function dispatch(positionals, values, io) {
         case 'search': {
             const words = positionals.slice(1).join(' ');
             const page = await client().messages.search(need(words || undefined, 'words to look for'), {
-                inboxId: values.inbox,
+                inboxId: one(values.inbox, '--inbox'),
+                cursor,
+                limit,
             });
             show(page, () => page.data.length
-                ? page.data.map((m) => `${m.id}  ${m.created_at.slice(0, 10)}  ${m.from.address}  ${m.subject ?? ''}`)
+                ? paged(page, page.data.map((m) => `${m.id}  ${m.created_at.slice(0, 10)}  ${m.from.address}  ${m.subject ?? ''}`))
                 : ['Nothing found.']);
             return;
         }
@@ -501,11 +556,13 @@ async function dispatch(positionals, values, io) {
                 if (values.folder && !folders.includes(values.folder))
                     throw new Usage('--folder is inbox, archive, spam or trash.');
                 const page = await pidgeon.threads.list({
-                    inboxId: values.inbox,
+                    inboxId: one(values.inbox, '--inbox'),
                     folder: values.folder,
+                    cursor,
+                    limit,
                 });
                 show(page, () => page.data.length
-                    ? page.data.map((t) => `${t.id}  ${t.folder.padEnd(7)}  ${t.unread_count ? `${t.unread_count} unread  ` : ''}${t.subject ?? '(held)'}`)
+                    ? paged(page, page.data.map((t) => `${t.id}  ${t.folder.padEnd(7)}  ${t.unread_count ? `${t.unread_count} unread  ` : ''}${t.subject ?? '(held)'}`))
                     : ['No conversations.']);
             }
             else if (sub === 'show') {
@@ -562,13 +619,15 @@ async function dispatch(positionals, values, io) {
             if (sub === 'list') {
                 const list = await pidgeon.webhooks.list();
                 show(list, () => list.data.length
-                    ? list.data.map((h) => `${h.id}  ${h.url}  ${h.events.join(', ')}`)
+                    ? list.data.map((h) => `${h.id}  ${h.url}  ${h.events.join(', ')}${h.inbox_ids ? `  (inboxes: ${h.inbox_ids.join(', ')})` : ''}`)
                     : ['No webhooks.']);
             }
             else if (sub === 'create') {
                 const made = await pidgeon.webhooks.create({
                     url: need(arg, 'url (https)'),
-                    events: values.event ?? [],
+                    // The API refuses, by name, an event webhooks do not carry.
+                    events: (values.event ?? []),
+                    ...(values.inbox?.length ? { inboxIds: values.inbox } : {}),
                 });
                 show(made, () => [`Made ${made.id}. Secret, shown once: ${made.secret}`]);
             }
@@ -577,19 +636,38 @@ async function dispatch(positionals, values, io) {
                 show({ removed: arg }, () => ['Removed.']);
             }
             else
-                throw new Usage('pidgeon webhooks list | create <url> --event <type>... | remove <id>');
+                throw new Usage('pidgeon webhooks list | create <url> --event <type>... [--inbox <id>...] | remove <id>');
             return;
         }
         case 'events': {
             const page = await client().events.list({
                 type: values.type,
-                limit: values.limit ? Number(values.limit) : undefined,
+                limit,
+                cursor,
             });
             show(page, () => page.data.length
-                ? page.data.map((e) => `${e.created_at}  ${e.type}`)
+                ? paged(page, page.data.map((e) => `${e.created_at}  ${e.type}`))
                 : ['Nothing has happened yet.']);
             return;
         }
+        case 'pods': {
+            const pidgeon = client();
+            if (sub === 'list') {
+                const list = await pidgeon.pods.list();
+                show(list, () => list.data.map((p) => `${p.id}  ${p.name}${p.default ? '  (default)' : ''}`));
+            }
+            else if (sub === 'create') {
+                const pod = await pidgeon.pods.create(need(positionals.slice(2).join(' ') || undefined, 'name'));
+                show(pod, () => [`Made ${pod.name} (${pod.id}).`]);
+            }
+            else if (sub === 'remove') {
+                await pidgeon.pods.remove(need(arg, 'pod (its id)'));
+                show({ removed: arg }, () => ['Removed.']);
+            }
+            else
+                throw new Usage('pidgeon pods list | create <name> | remove <pod-id>');
+            return;
+        }
         case 'api': {
             const method = (sub ?? '').toUpperCase();
             if (!['GET', 'POST', 'PATCH', 'DELETE'].includes(method) || !arg?.startsWith('/v1/'))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pidgeon-ai/cli",
-  "version": "2.1.0",
+  "version": "2.4.0",
   "description": "Pidgeon from a terminal: sign in, set agents up with keys made on your machine, and send from their inboxes.",
   "license": "Apache-2.0",
   "type": "module",
@@ -36,7 +36,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@pidgeon-ai/sdk": "^2.1.1"
+    "@pidgeon-ai/sdk": "^2.4.0"
   },
   "devDependencies": {
     "@types/node": "^24.10.1",