zele 0.3.17 → 0.3.21

package/src/commands/mail-actions.ts

@@ -1,11 +1,19 @@
-// Mail action commands: star, unstar, archive, trash, untrash, mark read/unread, spam, unspam, label modify.
+// Mail action commands: star, unstar, archive, trash, untrash, mark read/unread,
+// spam, unspam, label modify, unsubscribe.
 // Bulk operations on threads — cache invalidation is handled by the client methods.
 
-import type { Goke } from 'goke'
+import type { ZeleCli } from '../cli-types.js'
 import { z } from 'zod'
+import * as errore from 'errore'
 import { getClient } from '../auth.js'
-import type { GmailClient } from '../gmail-client.js'
+import type { GmailClient, ParsedMessage } from '../gmail-client.js'
 import type { ImapSmtpClient } from '../imap-smtp-client.js'
+import { UnsubscribeUnavailableError, UnsubscribeFailedError } from '../api-utils.js'
+import {
+  planUnsubscribe,
+  type UnsubscribeMechanism,
+  type UnsubscribePlan,
+} from '../unsubscribe.js'
 import * as out from '../output.js'
 import { handleCommandError } from '../output.js'
 
@@ -35,7 +43,7 @@ async function bulkAction(
 // Register commands
 // ---------------------------------------------------------------------------
 
-export function registerMailActionCommands(cli: Goke) {
+export function registerMailActionCommands(cli: ZeleCli) {
   cli
     .command('mail star [...threadIds]', 'Star threads')
     .action(async (threadIds, options) => {
@@ -121,4 +129,307 @@ export function registerMailActionCommands(cli: Goke) {
       out.printYaml(result)
       out.success(`Trashed ${result.count} spam thread(s)`)
     })
+
+  // =========================================================================
+  // mail unsubscribe — RFC 2369 + RFC 8058
+  // =========================================================================
+  //
+  // Reads List-Unsubscribe and List-Unsubscribe-Post from the latest non-draft
+  // message in a thread, then picks a mechanism:
+  //   1. RFC 8058 one-click (HTTPS POST with `List-Unsubscribe=One-Click`)
+  //   2. RFC 2369 mailto: (send the canonical unsubscribe email)
+  //   3. RFC 2369 http(s): landing page (manual — print URL only)
+  //
+  // The decision logic lives in ../unsubscribe.ts so it can be unit-tested
+  // with inline snapshots. This command is the thin executor: fetch thread,
+  // build plan, optionally dry-run, otherwise perform the chosen mechanism.
+
+  cli
+    .command('mail unsubscribe <threadId>', 'Unsubscribe from a mailing list thread (RFC 2369 / RFC 8058)')
+    .option('--via <via>', z.enum(['auto', 'one-click', 'mailto', 'url']).describe(
+      'Mechanism to use (default: auto — prefers one-click if DKIM passes, then mailto, then url)',
+    ))
+    .option('--dry-run', 'Print the unsubscribe plan without executing anything')
+    .option('--require-dkim', 'Refuse one-click unless the message has DKIM=pass')
+    .option('--then <then>', z.enum(['nothing', 'archive', 'trash']).describe(
+      'Follow-up action on the thread after unsubscribing (default: nothing)',
+    ))
+    .action(async (threadId, options) => {
+      const via = options.via ?? 'auto'
+      const then = options.then ?? 'nothing'
+
+      const { client } = await getClient(options.account)
+      const { parsed: thread } = await client.getThread({ threadId })
+
+      const nonDraft = thread.messages.filter((m) => !m.isDraft)
+      const latest: ParsedMessage | undefined = nonDraft[nonDraft.length - 1] ?? thread.messages[thread.messages.length - 1]
+      if (!latest) {
+        handleCommandError(new UnsubscribeUnavailableError({ threadId }))
+      }
+
+      // DKIM gating: per RFC 8058 §4 the signed headers SHOULD include
+      // List-Unsubscribe and List-Unsubscribe-Post. We can't verify the
+      // `h=` tag here, so we approximate with the MTA's DKIM verdict
+      // (`auth.dkim === 'pass'`). SPF and DMARC aren't relevant for this
+      // specific header-signing check, so we don't require `auth.authentic`.
+      const dkimPass: boolean | null = latest.auth ? latest.auth.dkim === 'pass' : null
+      const plan = planUnsubscribe({
+        listUnsubscribe: latest.listUnsubscribe,
+        listUnsubscribePost: latest.listUnsubscribePost,
+        dkimAuthentic: dkimPass,
+      })
+
+      if (plan.mechanisms.length === 0) {
+        handleCommandError(new UnsubscribeUnavailableError({ threadId }))
+      }
+
+      const chosen = pickMechanism(plan, via, dkimPass)
+      if (chosen instanceof Error) handleCommandError(chosen)
+
+      if (options.requireDkim && chosen.kind === 'one-click' && dkimPass !== true) {
+        handleCommandError(
+          new UnsubscribeFailedError({
+            mechanism: 'one-click',
+            reason:
+              dkimPass === false
+                ? 'DKIM did not pass and --require-dkim was set'
+                : 'DKIM status unknown and --require-dkim was set',
+          }),
+        )
+      }
+
+      if (options.dryRun) {
+        out.printYaml({
+          action: 'Unsubscribe (dry-run)',
+          thread_id: threadId,
+          chosen: describeMechanism(chosen),
+          plan: describePlan(plan),
+        })
+        return
+      }
+
+      // Execute the chosen mechanism.
+      if (chosen.kind === 'one-click') {
+        const res = await oneClickPost(chosen.url)
+        if (res instanceof Error) handleCommandError(res)
+      } else if (chosen.kind === 'mailto') {
+        const sendResult = await client.sendMessage({
+          to: [{ email: chosen.mailto.to }],
+          subject: chosen.mailto.subject ?? 'unsubscribe',
+          body: chosen.mailto.body ?? 'unsubscribe',
+          cc: chosen.mailto.cc?.map((email) => ({ email })),
+        })
+        if (sendResult instanceof Error) {
+          handleCommandError(
+            new UnsubscribeFailedError({
+              mechanism: 'mailto',
+              reason: sendResult.message,
+              cause: sendResult,
+            }),
+          )
+        }
+      } else {
+        // url: cannot be executed programmatically — surface the URL and exit
+        // without marking success (nothing was actually done).
+        out.printYaml({
+          action: 'Unsubscribe (manual required)',
+          thread_id: threadId,
+          url: chosen.url,
+          note: 'Only a landing-page URL is available. Open it in a browser to complete unsubscription.',
+          plan: describePlan(plan),
+        })
+        out.hint('Open the printed URL in a browser to finish unsubscribing.')
+        return
+      }
+
+      // Unsubscribe action itself succeeded at this point. Report that
+      // BEFORE attempting the follow-up so that a follow-up failure can't
+      // hide an already-completed (and irreversible) unsubscribe.
+      out.printYaml({
+        action: 'Unsubscribed',
+        thread_id: threadId,
+        mechanism: describeMechanism(chosen),
+        then,
+        plan: describePlan(plan),
+      })
+      out.success(`Unsubscribed via ${chosen.kind}`)
+
+      // Optional follow-up action on the thread. Failure here is non-fatal
+      // for the unsubscribe itself — warn and exit non-zero so scripts can
+      // still notice, but don't hide the success.
+      if (then === 'archive') {
+        const r = await client.archive({ threadIds: [threadId] })
+        if (r instanceof Error) {
+          out.error(`Unsubscribed, but follow-up archive failed: ${r.message}`)
+          process.exit(1)
+        }
+      } else if (then === 'trash') {
+        const r = await client.trash({ threadId })
+        if (r instanceof Error) {
+          out.error(`Unsubscribed, but follow-up trash failed: ${r.message}`)
+          process.exit(1)
+        }
+      }
+    })
+}
+
+// ---------------------------------------------------------------------------
+// Unsubscribe helpers
+// ---------------------------------------------------------------------------
+
+/** Pick a mechanism from a plan based on the --via flag.
+ *
+ *  In `auto` mode we only use one-click if DKIM is known to pass, so a
+ *  spoofed List-Unsubscribe-Post header on an unauthenticated message
+ *  can't trigger a background POST. Users can still force it with
+ *  `--via one-click` (and can combine with `--require-dkim` to re-gate). */
+function pickMechanism(
+  plan: UnsubscribePlan,
+  via: 'auto' | 'one-click' | 'mailto' | 'url',
+  dkimPass: boolean | null,
+): UnsubscribeMechanism | UnsubscribeFailedError {
+  if (via === 'auto') {
+    for (const m of plan.mechanisms) {
+      if (m.kind === 'one-click' && dkimPass !== true) continue
+      return m
+    }
+    // Nothing usable in auto mode — the only remaining case is a plan made
+    // up entirely of one-click entries on a message we couldn't verify.
+    if (plan.mechanisms.length === 0) {
+      return new UnsubscribeFailedError({ mechanism: 'auto', reason: 'no mechanisms available' })
+    }
+    return new UnsubscribeFailedError({
+      mechanism: 'auto',
+      reason:
+        'only one-click is advertised, but DKIM did not pass. Re-run with --via one-click to force it.',
+    })
+  }
+  const match = plan.mechanisms.find((m) => m.kind === via)
+  if (match) return match
+  return new UnsubscribeFailedError({
+    mechanism: via,
+    reason: `no ${via} mechanism advertised by the sender`,
+  })
+}
+
+/** Reject URLs that point at localhost, loopback, or RFC1918 / link-local /
+ *  ULA ranges. This is a best-effort SSRF guard — it won't catch DNS
+ *  rebinding or hostnames that resolve to private IPs, but it stops the
+ *  obvious cases of `https://127.0.0.1/unsubscribe` hidden in a spoofed
+ *  List-Unsubscribe header. */
+function isPrivateOrLoopbackHost(hostname: string): boolean {
+  const h = hostname.toLowerCase().replace(/^\[|\]$/g, '')
+  if (h === 'localhost' || h.endsWith('.localhost') || h === 'ip6-localhost') return true
+
+  // IPv4 literal
+  const v4 = h.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/)
+  if (v4) {
+    const [a, b] = [Number(v4[1]), Number(v4[2])]
+    if (a === 10) return true
+    if (a === 127) return true
+    if (a === 0) return true
+    if (a === 169 && b === 254) return true // link-local
+    if (a === 172 && b >= 16 && b <= 31) return true
+    if (a === 192 && b === 168) return true
+    return false
+  }
+
+  // IPv6 literal — reject loopback (::1), link-local (fe80::/10), ULA (fc00::/7).
+  if (h === '::1' || h === '0:0:0:0:0:0:0:1') return true
+  if (/^fe[89ab][0-9a-f]:/i.test(h)) return true
+  if (/^f[cd][0-9a-f]{2}:/i.test(h)) return true
+  return false
+}
+
+/** Build an RFC 8058 one-click POST request and validate the response.
+ *  Returns void on success, UnsubscribeFailedError on any failure. */
+async function oneClickPost(url: string): Promise<void | UnsubscribeFailedError> {
+  // Re-validate the URL at the executor boundary (not just the planner),
+  // in case a future code path constructs a mechanism without going
+  // through planUnsubscribe.
+  let parsed: URL
+  try {
+    parsed = new URL(url)
+  } catch (err) {
+    return new UnsubscribeFailedError({
+      mechanism: 'one-click',
+      reason: `invalid URL: ${String(err)}`,
+      cause: err,
+    })
+  }
+  if (parsed.protocol !== 'https:') {
+    return new UnsubscribeFailedError({
+      mechanism: 'one-click',
+      reason: `refusing to POST to ${parsed.protocol} URL (RFC 8058 requires https)`,
+    })
+  }
+  if (isPrivateOrLoopbackHost(parsed.hostname)) {
+    return new UnsubscribeFailedError({
+      mechanism: 'one-click',
+      reason: `refusing to POST to private/loopback host ${parsed.hostname} (SSRF guard)`,
+    })
+  }
+
+  // RFC 8058 §3.1: senders MUST NOT return redirects, so we refuse to follow.
+  // `redirect: 'manual'` lets us see 3xx status codes instead of auto-following.
+  // 10-second timeout keeps a slow/unreachable endpoint from hanging the CLI.
+  const res = await errore.tryAsync({
+    try: () =>
+      fetch(parsed, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: 'List-Unsubscribe=One-Click',
+        redirect: 'manual',
+        signal: AbortSignal.timeout(10_000),
+      }),
+    catch: (err) =>
+      new UnsubscribeFailedError({
+        mechanism: 'one-click',
+        reason: String(err),
+        cause: err,
+      }),
+  })
+  if (res instanceof Error) return res
+
+  if (res.status >= 200 && res.status < 300) return undefined
+  if (res.status >= 300 && res.status < 400) {
+    // RFC 8058 §3.1 says senders MUST NOT redirect, but many widely-deployed
+    // senders (ConvertKit, SendGrid, Mailchimp) redirect to a "you have been
+    // unsubscribed" confirmation page after processing the POST body. A POST
+    // that was going to be rejected would return 4xx, not 3xx — the server
+    // has to read and act on the body before deciding to redirect — so we
+    // treat 3xx as success with a warning printed to stderr.
+    const location = res.headers.get('location')
+    out.hint(
+      `one-click endpoint returned HTTP ${res.status} redirect${location ? ` → ${location}` : ''} (RFC 8058 §3.1 forbids this, but many senders do it anyway). Treating as success.`,
+    )
+    return undefined
+  }
+  return new UnsubscribeFailedError({
+    mechanism: 'one-click',
+    reason: `HTTP ${res.status} ${res.statusText}`,
+  })
+}
+
+/** YAML-friendly representation of a mechanism for output. */
+function describeMechanism(m: UnsubscribeMechanism): Record<string, unknown> {
+  if (m.kind === 'one-click') return { kind: 'one-click', url: m.url }
+  if (m.kind === 'url') return { kind: 'url', url: m.url }
+  return {
+    kind: 'mailto',
+    to: m.mailto.to,
+    ...(m.mailto.subject ? { subject: m.mailto.subject } : {}),
+    ...(m.mailto.body ? { body: m.mailto.body } : {}),
+    ...(m.mailto.cc && m.mailto.cc.length > 0 ? { cc: m.mailto.cc } : {}),
+  }
+}
+
+/** YAML-friendly representation of a full plan. */
+function describePlan(plan: UnsubscribePlan): Record<string, unknown> {
+  return {
+    mechanisms: plan.mechanisms.map(describeMechanism),
+    has_one_click: plan.hasOneClick,
+    dkim_authentic: plan.dkimAuthentic,
+    ...(plan.warnings.length > 0 ? { warnings: plan.warnings } : {}),
+  }
 }

package/src/commands/mail.ts

@@ -3,7 +3,7 @@
 // Cache is handled by the client — commands just call methods and use data.
 // Multi-account: list/search fetch all accounts concurrently and merge by date.
 
-import type { Goke } from 'goke'
+import type { ZeleCli } from '../cli-types.js'
 import { z } from 'zod'
 import fs from 'node:fs'
 import path from 'node:path'
@@ -13,6 +13,7 @@ import { getClients, getClient, listAccounts, login } from '../auth.js'
 import type { ThreadListResult } from '../gmail-client.js'
 import type { GmailClient } from '../gmail-client.js'
 import { AuthError } from '../api-utils.js'
+import { hasUnsubscribeMechanism, hasOneClickUnsubscribe } from '../unsubscribe.js'
 import * as out from '../output.js'
 import { handleCommandError } from '../output.js'
 import pc from 'picocolors'
@@ -38,7 +39,7 @@ function formatLabels(labelIds: string[], labelMap?: Map<string, string>): strin
 // Register commands
 // ---------------------------------------------------------------------------
 
-export function registerMailCommands(cli: Goke) {
+export function registerMailCommands(cli: ZeleCli) {
   // =========================================================================
   // mail (TUI)
   // =========================================================================
@@ -51,13 +52,15 @@ export function registerMailCommands(cli: Goke) {
   cli
     .command('mail list', 'List email threads')
     .option('--folder [folder]', 'Folder to list (inbox, sent, trash, spam, starred, drafts, archive, all) (default: inbox)')
-    .option('--max [max]', 'Max results per page (default: 20)')
+    .option('--limit [limit]', 'Max threads to show (default: 20)')
     .option('--page <page>', 'Pagination token (requires --account, only works for a single account)')
     .option('--label <label>', 'Filter by label name')
     .option('--filter <filter>', 'Gmail search filter (e.g. "is:unread", "from:github", "has:attachment")')
     .action(async (options) => {
-      const folder = options.folder ?? 'inbox'
-      const max = options.max ? Number(options.max) : 20
+      // `options.folder` / `options.limit` are `string | undefined` now.
+      // `''` (bare flag) falls back to the default via `||`.
+      const folder = options.folder || 'inbox'
+      const limit = options.limit ? Number(options.limit) : 20
       const clients = await getClients(options.account)
 
       if (options.page && clients.length > 1) {
@@ -70,7 +73,7 @@ export function registerMailCommands(cli: Goke) {
         clients.map(async ({ email, client, accountType }) => {
           const result = await client.listThreads({
             folder,
-            maxResults: max,
+            maxResults: limit,
             labelIds: options.label ? [options.label] : undefined,
             pageToken: options.page,
             query: options.filter,
@@ -99,13 +102,13 @@ export function registerMailCommands(cli: Goke) {
       const labelMap = new Map<string, string>()
       for (const r of allResults) for (const [id, name] of r.labelMap) labelMap.set(id, name)
 
-      // Merge threads from all accounts, sorted by date descending, capped at max
+      // Merge threads from all accounts, sorted by date descending, capped at limit
       const merged = allResults
         .flatMap(({ email, result }) =>
           result.threads.map((t) => ({ ...t, account: email })),
         )
         .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime())
-        .slice(0, max)
+        .slice(0, limit)
 
       if (merged.length === 0) {
         out.printList([], { summary: 'No threads found' })
@@ -118,6 +121,8 @@ export function registerMailCommands(cli: Goke) {
           const to = t.to.map((s) => out.formatSender(s)).join(', ')
           const cc = t.cc.map((s) => out.formatSender(s)).join(', ')
           const labels = formatLabels(t.labelIds, labelMap)
+          const canUnsubscribe = hasUnsubscribeMechanism(t.listUnsubscribe)
+          const oneClick = hasOneClickUnsubscribe(t.listUnsubscribe, t.listUnsubscribePost)
           return {
             ...(showAccount ? { account: t.account } : {}),
             id: t.id,
@@ -130,6 +135,8 @@ export function registerMailCommands(cli: Goke) {
             date: out.formatDate(t.date),
             messages: t.messageCount,
             ...(labels ? { labels } : {}),
+            ...(canUnsubscribe ? { can_unsubscribe: true } : {}),
+            ...(oneClick ? { one_click: true } : {}),
             ...(t.listUnsubscribe ? { unsubscribe: t.listUnsubscribe } : {}),
           }
         }),
@@ -143,10 +150,10 @@ export function registerMailCommands(cli: Goke) {
 
   cli
     .command('mail search <query>', 'Search email threads using Gmail query syntax (from:, to:, subject:, has:attachment, etc). See https://support.google.com/mail/answer/7190')
-    .option('--max [max]', 'Max results (default: 20)')
+    .option('--limit [limit]', 'Max results to show (default: 20)')
     .option('--page <page>', 'Pagination token (requires --account, only works for a single account)')
     .action(async (query, options) => {
-      const max = options.max ? Number(options.max) : 20
+      const limit = options.limit ? Number(options.limit) : 20
       const clients = await getClients(options.account)
 
       if (options.page && clients.length > 1) {
@@ -159,7 +166,7 @@ export function registerMailCommands(cli: Goke) {
         clients.map(async ({ email, client, accountType }) => {
           const result = await client.listThreads({
             query,
-            maxResults: max,
+            maxResults: limit,
             pageToken: options.page,
           })
           if (result instanceof Error) return result
@@ -190,7 +197,7 @@ export function registerMailCommands(cli: Goke) {
           result.threads.map((t) => ({ ...t, account: email })),
         )
         .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime())
-        .slice(0, max)
+        .slice(0, limit)
 
       if (merged.length === 0) {
         out.printList([], { summary: `No results for "${query}"` })
@@ -203,6 +210,8 @@ export function registerMailCommands(cli: Goke) {
           const to = t.to.map((s) => out.formatSender(s)).join(', ')
           const cc = t.cc.map((s) => out.formatSender(s)).join(', ')
           const labels = formatLabels(t.labelIds, labelMap)
+          const canUnsubscribe = hasUnsubscribeMechanism(t.listUnsubscribe)
+          const oneClick = hasOneClickUnsubscribe(t.listUnsubscribe, t.listUnsubscribePost)
           return {
             ...(showAccount ? { account: t.account } : {}),
             id: t.id,
@@ -215,6 +224,8 @@ export function registerMailCommands(cli: Goke) {
             date: out.formatDate(t.date),
             messages: t.messageCount,
             ...(labels ? { labels } : {}),
+            ...(canUnsubscribe ? { can_unsubscribe: true } : {}),
+            ...(oneClick ? { one_click: true } : {}),
             ...(t.listUnsubscribe ? { unsubscribe: t.listUnsubscribe } : {}),
           }
         }),
@@ -460,6 +471,7 @@ export function registerMailCommands(cli: Goke) {
     .option('--cc <cc>', z.string().describe('Additional CC recipients'))
     .option('--all', 'Reply all (include all original recipients)')
     .option('--from <from>', z.string().describe('Send-as alias email'))
+    .option('--draft', 'Save as draft instead of sending')
     .action(async (threadId, options) => {
       let body = options.body ?? ''
       if (options.bodyFile) {
@@ -485,6 +497,21 @@ export function registerMailCommands(cli: Goke) {
         ? options.cc.split(',').map((e: string) => ({ email: e.trim() })).filter((e: { email: string }) => e.email)
         : undefined
 
+      if (options.draft) {
+        const result = await client.createDraftReply({
+          threadId,
+          body,
+          replyAll: options.all,
+          cc,
+          fromEmail: options.from,
+        })
+        if (result instanceof Error) handleCommandError(result)
+
+        out.printYaml(result)
+        out.success('Reply draft created')
+        return
+      }
+
       const result = await client.replyToThread({
         threadId,
         body,
@@ -507,6 +534,7 @@ export function registerMailCommands(cli: Goke) {
     .option('--to <to>', z.string().describe('Forward recipient(s), comma-separated'))
     .option('--body <body>', z.string().describe('Optional message to prepend'))
     .option('--from <from>', z.string().describe('Send-as alias email'))
+    .option('--draft', 'Save as draft instead of sending')
     .action(async (threadId, options) => {
       if (!options.to) {
         out.error('--to is required')
@@ -520,6 +548,20 @@ export function registerMailCommands(cli: Goke) {
 
       const { client } = await getClient(options.account)
 
+      if (options.draft) {
+        const result = await client.createDraftForward({
+          threadId,
+          to: recipients,
+          body: options.body,
+          fromEmail: options.from,
+        })
+        if (result instanceof Error) handleCommandError(result)
+
+        out.printYaml(result)
+        out.success('Forward draft created')
+        return
+      }
+
       const result = await client.forwardThread({
         threadId,
         to: recipients,

package/src/commands/profile.ts

@@ -3,13 +3,13 @@
 // Cache is handled by the client — commands just call methods and use data.
 // Multi-account: shows all accounts or filtered by --account.
 
-import type { Goke } from 'goke'
+import type { ZeleCli } from '../cli-types.js'
 import { getClients } from '../auth.js'
 import type { GmailClient } from '../gmail-client.js'
 import { AuthError } from '../api-utils.js'
 import * as out from '../output.js'
 
-export function registerProfileCommands(cli: Goke) {
+export function registerProfileCommands(cli: ZeleCli) {
   cli
     .command('profile', 'Show account info')
     .action(async (options) => {

package/src/commands/watch.ts

@@ -2,7 +2,7 @@
 // Thin CLI wrapper around GmailClient.watchInbox() async generator.
 // Multi-account: watches all accounts concurrently and merges output.
 
-import type { Goke } from 'goke'
+import type { ZeleCli } from '../cli-types.js'
 import { z } from 'zod'
 import { getClients } from '../auth.js'
 import type { WatchEvent } from '../gmail-client.js'
@@ -13,12 +13,12 @@ import * as out from '../output.js'
 // Register commands
 // ---------------------------------------------------------------------------
 
-export function registerWatchCommands(cli: Goke) {
+export function registerWatchCommands(cli: ZeleCli) {
   cli
     .command('mail watch', 'Watch for new emails (poll via History API)')
     .option('--interval [interval]', z.string().describe('Poll interval in seconds (default: 15)'))
     .option('--folder [folder]', z.string().describe('Folder to watch (default: inbox)'))
-    .option('--query [query]', z.string().describe('Filter messages client-side (from:, to:, cc:, subject:, is:unread, is:starred, has:attachment, -negate). See https://support.google.com/mail/answer/7190'))
+    .option('--filter [filter]', z.string().describe('Filter messages client-side (from:, to:, cc:, subject:, is:unread, is:starred, has:attachment, -negate). See https://support.google.com/mail/answer/7190'))
     .option('--once', z.boolean().describe('Print changes once and exit (no loop)'))
     .action(async (options) => {
       const interval = options.interval ? Number(options.interval) : 15
@@ -43,7 +43,7 @@ export function registerWatchCommands(cli: Goke) {
         client.watchInbox({
           folder,
           intervalMs: interval * 1000,
-          query: options.query,
+          query: options.filter,
           once: options.once,
         }),
       )