@kivel.io/cli 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @kivel.io/cli
 
+## 0.11.0
+
+### Minor Changes
+
+- e137d14: Add email search filters, resumable wait cursors and checkpoints before triggering new mail. Add message inspection, triage and email forwarding history.
+
+### Patch Changes
+
+- Updated dependencies [e137d14]
+    - @kivel.io/sdk@0.11.0
+
+## 0.10.1
+
+### Patch Changes
+
+- 10de14b: Publish releases to the npm latest tag, so `npm install @kivel.io/sdk` and `npm install --global @kivel.io/cli` install the newest version. Install instructions no longer need `@beta`.
+- Updated dependencies [10de14b]
+    - @kivel.io/sdk@0.10.1
+
 ## 0.10.0
 
 ### Minor Changes

package/README.md

@@ -3,13 +3,13 @@
 The command-line client for [Kivel](https://kivel.io). Requires Node.js
 22.13+. Commands share the HTTP API's access rules, plan limits and expiry.
 
-Install the current beta:
+Install the `kivel` command globally:
 
 ```sh
-npx --package=@kivel.io/cli@beta kivel --help
-# Or install the command:
-npm install --global @kivel.io/cli@beta
+npm install --global @kivel.io/cli
 kivel --version
+# Or run it once without installing:
+npx --package=@kivel.io/cli kivel --help
 ```
 
 For source development, run `pnpm build:packages` and `pnpm cli --help` from the

package/dist/agent-commands.js

@@ -9,7 +9,8 @@ export function needsInput(args) {
         (args[0] === 'credential' && ['save', 'update'].includes(args[1] ?? '')) ||
         (args[0] === 'approval' && args[1] === 'ask') ||
         (args[0] === 'monitor' && args[1] === 'create') ||
-        (args[0] === 'email' && ['draft-create', 'draft-submit'].includes(args[1] ?? '')) ||
+        (args[0] === 'email' &&
+            ['draft-create', 'draft-submit', 'message-update'].includes(args[1] ?? '')) ||
         (args[0] === 'event' && args[1] === 'wait') ||
         (['oauth', 'mock', 'mcp-server', 'status-page', 'job'].includes(args[0] ?? '') &&
             ['create', 'update'].includes(args[1] ?? '')) ||
@@ -54,6 +55,24 @@ export async function agentCommand(client, args, input) {
         allowed.add('--after');
         allowed.add('--timeout-seconds');
     }
+    if (group === 'email' && ['messages', 'wait'].includes(action ?? '')) {
+        for (const flag of [
+            '--from',
+            '--mail-from',
+            '--subject',
+            '--text',
+            '--has-code',
+            '--has-link',
+            '--has-attachment',
+            '--read',
+            '--label',
+            '--cursor',
+            '--limit',
+        ])
+            allowed.add(flag);
+        if (action === 'wait')
+            allowed.add('--checkpoint');
+    }
     if (group === 'email' && action === 'threads') {
         allowed.add('--cursor');
         allowed.add('--limit');
@@ -86,7 +105,7 @@ export async function agentCommand(client, args, input) {
             throw new Error(`Unknown option: ${value}`);
         if (flags.has(value))
             throw new Error(`Duplicate option: ${value}`);
-        if (value === '--persistent')
+        if (value === '--persistent' || value === '--checkpoint')
             flags.set(value, 'true');
         else {
             const next = tail[++i];
@@ -122,6 +141,28 @@ export async function agentCommand(client, args, input) {
     const idempotencyKey = take('--idempotency-key');
     const emailSettings = { activeDays: number('--active-days'), localPart: take('--local-part') };
     const threadPage = { cursor: take('--cursor'), limit: number('--limit') };
+    const boolean = (key) => {
+        const value = take(key);
+        if (value === undefined)
+            return undefined;
+        if (value === 'true' || value === 'false')
+            return value === 'true';
+        throw new Error(`Use true or false for ${key}.`);
+    };
+    const emailSearch = {
+        ...threadPage,
+        token,
+        from: take('--from'),
+        mailFrom: take('--mail-from'),
+        subject: take('--subject'),
+        text: take('--text'),
+        hasCode: boolean('--has-code'),
+        hasLink: boolean('--has-link'),
+        hasAttachment: boolean('--has-attachment'),
+        read: boolean('--read'),
+        label: take('--label'),
+    };
+    const checkpoint = boolean('--checkpoint');
     const approvalId = take('--approval-id');
     const passwordLength = number('--length');
     if (flags.size)
@@ -381,6 +422,8 @@ export async function agentCommand(client, args, input) {
             return client.inboxDeliveries(id(), token);
     }
     if (group === 'email') {
+        if (action === 'deliveries')
+            return client.emailDeliveries(id());
         if (action === 'threads') {
             if (positional.length > 1)
                 throw new Error('Provide at most one inbox ID.');
@@ -424,10 +467,17 @@ export async function agentCommand(client, args, input) {
             exact(0);
             return client.createEmailInbox(emailSettings);
         }
+        if (action === 'message' || action === 'message-update') {
+            exact(2);
+            const [inboxId, messageId] = positional;
+            return action === 'message'
+                ? client.emailMessage(inboxId, messageId, token)
+                : client.updateEmailMessage(inboxId, messageId, json());
+        }
         if (action === 'messages')
-            return client.emails(id(), token);
+            return client.emails(id(), emailSearch);
         if (action === 'wait')
-            return client.waitForEmail(id(), wait);
+            return client.waitForEmail(id(), { ...wait, ...emailSearch, checkpoint });
     }
     if (group === 'mock' || group === 'mcp-server') {
         if (action === 'create') {

package/dist/commands.d.ts

@@ -1,4 +1,4 @@
 export { needsInput } from './agent-commands.js';
 import type { Kivel } from '@kivel.io/sdk';
-export declare const help = "kivel tools | usage | resources\nkivel --version\nkivel plans | activity\nkivel agent login <name> [--client <client>]\nkivel agent token < login.json\nkivel agent trial <name> [--human-email <email>] [--client <client>]\nkivel agent list\nkivel authenticator add < authenticator.json\nkivel authenticator list|code|delete [id]\nkivel authenticator rename <id> <name>\nkivel email attachment|download-attachment <inbox-id> <message-id> <attachment-id>\nkivel email create [--active-days <1-7>] [--local-part <paid-address>]\nkivel email list\nkivel email clear <id>\nkivel email forward <id> [--token <token>] < forwarding.json\nkivel email send <id> --idempotency-key <unique-key> < message.json\nkivel event wait [--timeout-seconds <1-30>] < sources.json\nkivel test-wallet create|list|inspect|update|delete [id]\nkivel test-wallet balance|transactions <id>\nkivel test-wallet pay|top-up <id> < test-payment.json\nkivel test-paywall create|list|inspect|update|delete [id]\nkivel test-checkout create|list|inspect|update|delete [id]\nkivel test-checkout complete|confirm <id> < test-checkout.json\nTest payments use fake units only. Create/update read JSON from stdin. Agent keys cannot set wallet limits; only a human owner/admin can. Resume approval with the same payment idempotencyKey.\nkivel credential save < credential.json\nkivel credential list\nkivel credential inspect|delete <id>\nkivel credential update <id> < changes.json\nkivel credential reveal <id> [--approval-id <id>]\nkivel password generate [--length <n>]\nkivel email threads [inbox-id] [--cursor <cursor>] [--limit <n>]\nkivel email thread <inbox-id> <thread-id>\nkivel email drafts|rules <inbox-id>\nkivel email draft-create <inbox-id> < content.json\nkivel email draft-inspect|draft-delete <draft-id>\nkivel email draft-submit <draft-id> [< settings.json]\nkivel email messages|wait <id> [--token <token>] [--after <id>] [--timeout-seconds <n>]\nkivel memory set <namespace> <key> [--ttl-seconds <n>] < value.json\nkivel memory get|delete <namespace> <key>\nkivel memory list <namespace> [--prefix <prefix>]\nkivel monitor create < monitor.json\nkivel monitor list|inspect|pause|resume|delete [id]\nkivel monitor ping|fail <ping-token>\nkivel monitor accept-dns <id>\nkivel job create [--ttl-seconds <n>] < job.json\nkivel job list|inspect|cancel [id]\nkivel status-page create|update [id] < page.json\nkivel smtp create [--ttl-seconds <n>]\nkivel smtp rotate <id>\nkivel phone available [US-area-code]\nkivel phone create <E.164-number> --idempotency-key <unique-key>\nkivel phone list|release|messages|wait [id] [--after <id>] [--timeout-seconds <n>]\nkivel approval ask < question.json\nkivel approval list|pending|inspect|wait [id] [--timeout-seconds <n>]\nkivel inbox requests|wait|deliveries <id> [--token <token>]\nkivel inbox response|forward <id> [--token <token>] < settings.json\nkivel oauth create [--ttl-seconds <n>] < provider.json\nkivel oauth update <id> < provider.json\nkivel oauth list|inspect|calls|renew|delete [id]\nkivel mock create|update [id] < config.json\nkivel mock calls|reset <id> [--token <token>]\nkivel mcp-server create < config.json\nkivel inbox|email|mock|mcp-server|file inspect|delete|renew <id> [--token <token>]\nkivel inbox|mock|mcp-server|file sharing <id> --visibility private|public [--token <token>]\nkivel describe <tool-id>\nkivel run <tool-id> [--file <filename>] [--options '{\"action\":\"minify\"}'] < input.txt\nkivel inbox create [--visibility private|public]\nkivel listen <inbox-id> [--token <inspection-token>] [--forward http://localhost:3000] [--all]\nkivel api <GET|HEAD|OPTIONS|POST|PUT|PATCH|DELETE> /api/path-or-/mock/path [--token <resource-token>] < body.json\nkivel upload <filename> [--visibility private|public] [--max-downloads 1] < file.bin\nkivel download <file-id> [--access-token token] > file.bin\n\nSet KIVEL_URL and KIVEL_API_KEY. Commands output JSON; downloads output binary; help is plain text. Mutations are never retried. Authenticators are only for accounts your human asked you to create or operate. Attachment downloads output untrusted binary files; attachment links expire in two minutes.\nCreation also accepts --ttl-seconds <n> and --persistent. Webhook receiving is public by default; inspection always needs workspace credentials or the inspection token. Use inbox create --visibility private only when senders can add X-Access-Token. Other resources default to private.";
+export declare const help = "kivel tools | usage | resources\nkivel --version\nkivel plans | activity\nkivel agent login <name> [--client <client>]\nkivel agent token < login.json\nkivel agent trial <name> [--human-email <email>] [--client <client>]\nkivel agent list\nkivel authenticator add < authenticator.json\nkivel authenticator list|code|delete [id]\nkivel authenticator rename <id> <name>\nkivel email attachment|download-attachment <inbox-id> <message-id> <attachment-id>\nkivel email create [--active-days <1-7>] [--local-part <paid-address>]\nkivel email list\nkivel email clear <id>\nkivel email forward <id> [--token <token>] < forwarding.json\nkivel email send <id> --idempotency-key <unique-key> < message.json\nkivel event wait [--timeout-seconds <1-30>] < sources.json\nkivel test-wallet create|list|inspect|update|delete [id]\nkivel test-wallet balance|transactions <id>\nkivel test-wallet pay|top-up <id> < test-payment.json\nkivel test-paywall create|list|inspect|update|delete [id]\nkivel test-checkout create|list|inspect|update|delete [id]\nkivel test-checkout complete|confirm <id> < test-checkout.json\nTest payments use fake units only. Create/update read JSON from stdin. Agent keys cannot set wallet limits; only a human owner/admin can. Resume approval with the same payment idempotencyKey.\nkivel credential save < credential.json\nkivel credential list\nkivel credential inspect|delete <id>\nkivel credential update <id> < changes.json\nkivel credential reveal <id> [--approval-id <id>]\nkivel password generate [--length <n>]\nkivel email message <inbox-id> <message-id>\nkivel email message-update <inbox-id> <message-id> < update.json\nkivel email deliveries <inbox-id>\nkivel email threads [inbox-id] [--cursor <cursor>] [--limit <n>]\nkivel email thread <inbox-id> <thread-id>\nkivel email drafts|rules <inbox-id>\nkivel email draft-create <inbox-id> < content.json\nkivel email draft-inspect|draft-delete <draft-id>\nkivel email draft-submit <draft-id> [< settings.json]\nkivel email messages|wait <id> [--cursor <cursor>] [--limit <n>] [--from <address>] [--mail-from <address>] [--subject <text>] [--text <text>] [--has-code true|false] [--has-link true|false] [--has-attachment true|false] [--read true|false] [--label <label>]\nkivel email wait <id> [--checkpoint] [--after <id>] [--timeout-seconds <n>] [--token <token>]\nkivel memory set <namespace> <key> [--ttl-seconds <n>] < value.json\nkivel memory get|delete <namespace> <key>\nkivel memory list <namespace> [--prefix <prefix>]\nkivel monitor create < monitor.json\nkivel monitor list|inspect|pause|resume|delete [id]\nkivel monitor ping|fail <ping-token>\nkivel monitor accept-dns <id>\nkivel job create [--ttl-seconds <n>] < job.json\nkivel job list|inspect|cancel [id]\nkivel status-page create|update [id] < page.json\nkivel smtp create [--ttl-seconds <n>]\nkivel smtp rotate <id>\nkivel phone available [US-area-code]\nkivel phone create <E.164-number> --idempotency-key <unique-key>\nkivel phone list|release|messages|wait [id] [--after <id>] [--timeout-seconds <n>]\nkivel approval ask < question.json\nkivel approval list|pending|inspect|wait [id] [--timeout-seconds <n>]\nkivel inbox requests|wait|deliveries <id> [--token <token>]\nkivel inbox response|forward <id> [--token <token>] < settings.json\nkivel oauth create [--ttl-seconds <n>] < provider.json\nkivel oauth update <id> < provider.json\nkivel oauth list|inspect|calls|renew|delete [id]\nkivel mock create|update [id] < config.json\nkivel mock calls|reset <id> [--token <token>]\nkivel mcp-server create < config.json\nkivel inbox|email|mock|mcp-server|file inspect|delete|renew <id> [--token <token>]\nkivel inbox|mock|mcp-server|file sharing <id> --visibility private|public [--token <token>]\nkivel describe <tool-id>\nkivel run <tool-id> [--file <filename>] [--options '{\"action\":\"minify\"}'] < input.txt\nkivel inbox create [--visibility private|public]\nkivel listen <inbox-id> [--token <inspection-token>] [--forward http://localhost:3000] [--all]\nkivel api <GET|HEAD|OPTIONS|POST|PUT|PATCH|DELETE> /api/path-or-/mock/path [--token <resource-token>] < body.json\nkivel upload <filename> [--visibility private|public] [--max-downloads 1] < file.bin\nkivel download <file-id> [--access-token token] > file.bin\n\nSet KIVEL_URL and KIVEL_API_KEY. Commands output JSON; downloads output binary; help is plain text. Mutations are never retried. Authenticators are only for accounts your human asked you to create or operate. Attachment downloads output untrusted binary files; attachment links expire in two minutes.\nCreation also accepts --ttl-seconds <n> and --persistent. Webhook receiving is public by default; inspection always needs workspace credentials or the inspection token. Use inbox create --visibility private only when senders can add X-Access-Token. Other resources default to private.";
 export declare function command(client: Kivel, args: string[], input?: Uint8Array): Promise<unknown>;

package/dist/commands.js

@@ -31,13 +31,17 @@ kivel credential inspect|delete <id>
 kivel credential update <id> < changes.json
 kivel credential reveal <id> [--approval-id <id>]
 kivel password generate [--length <n>]
+kivel email message <inbox-id> <message-id>
+kivel email message-update <inbox-id> <message-id> < update.json
+kivel email deliveries <inbox-id>
 kivel email threads [inbox-id] [--cursor <cursor>] [--limit <n>]
 kivel email thread <inbox-id> <thread-id>
 kivel email drafts|rules <inbox-id>
 kivel email draft-create <inbox-id> < content.json
 kivel email draft-inspect|draft-delete <draft-id>
 kivel email draft-submit <draft-id> [< settings.json]
-kivel email messages|wait <id> [--token <token>] [--after <id>] [--timeout-seconds <n>]
+kivel email messages|wait <id> [--cursor <cursor>] [--limit <n>] [--from <address>] [--mail-from <address>] [--subject <text>] [--text <text>] [--has-code true|false] [--has-link true|false] [--has-attachment true|false] [--read true|false] [--label <label>]
+kivel email wait <id> [--checkpoint] [--after <id>] [--timeout-seconds <n>] [--token <token>]
 kivel memory set <namespace> <key> [--ttl-seconds <n>] < value.json
 kivel memory get|delete <namespace> <key>
 kivel memory list <namespace> [--prefix <prefix>]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kivel.io/cli",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "bin": {
     "kivel": "./bin/kivel.mjs"
@@ -18,7 +18,7 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@kivel.io/sdk": "0.10.0"
+    "@kivel.io/sdk": "0.11.0"
   },
   "devDependencies": {
     "@types/node": "^26.6.5",
@@ -42,13 +42,13 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
-    "tag": "beta"
+    "tag": "latest"
   },
   "main": "./dist/commands.js",
   "types": "./dist/commands.d.ts",
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist', {recursive:true,force:true})\" && tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "node --import tsx --test src/listen.test.ts"
+    "test": "node --import tsx --test src/listen.test.ts src/email.test.ts"
   }
 }