@hartewired/gmail-cli 1.0.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,130 @@
+# gmail-cli
+
+[![by — harteWired](https://img.shields.io/badge/by-harteWired-e6a562?style=flat&labelColor=15151e)](https://github.com/harteWired)
+[![npm](https://img.shields.io/npm/v/@hartewired/gmail-cli?style=flat&labelColor=15151e&color=e6a562)](https://www.npmjs.com/package/@hartewired/gmail-cli)
+[![license: MIT](https://img.shields.io/badge/license-MIT-e6a562?style=flat&labelColor=15151e)](./LICENSE)
+
+A stateless, zero-dependency, **agent-friendly** Gmail CLI. Read, send, reply, forward, label, and organize mail straight from the shell — with JSON output on every command.
+
+```bash
+gmail list "is:unread newer_than:3d" --max 10
+gmail send --to a@b.com --subject "Q2 report" --html --body-file note.html --attach report.pdf
+gmail reply <id> --all --body "Thanks — got it."
+gmail markread --query "is:unread older_than:30d"
+```
+
+## Why another Gmail CLI
+
+Most Gmail tools are built for a human sitting at a terminal. This one is built to be **driven by a program** — an LLM agent, a cron job, a shell script:
+
+1. **Stateless.** No daemon, no background auth server, no long-running process to crash or reconnect. Each command mints (or reuses a cached) access token and exits. Nothing runs when idle.
+2. **Zero dependencies.** Pure Node (>= 20, uses the built-in `fetch`). Nothing to audit, nothing to break on an upstream release.
+3. **Machine-readable.** `--json` (and JSON-by-default on write/organize commands) means the output parses cleanly. Search-query batch ops (`--query`) let one command act on many messages.
+
+If you want a rich human TUI, use [himalaya](https://github.com/pimalaya/himalaya). If you want something an agent can shell out to and parse, that's this.
+
+## Install
+
+```bash
+npm install -g @hartewired/gmail-cli
+# or run without installing:
+npx @hartewired/gmail-cli help
+```
+
+## Setup — create a Google OAuth client
+
+gmail-cli talks to your own Google Cloud OAuth client (the client secret for a
+Desktop app is not treated as confidential by Google). One-time:
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/) and create (or pick) a project.
+2. **APIs & Services → Library →** enable the **Gmail API**.
+3. **APIs & Services → OAuth consent screen:** configure it (External is fine), and add your Google account under **Test users** so you can authorize while the app is unverified.
+4. **APIs & Services → Credentials → Create credentials → OAuth client ID → Application type: Desktop app.** Copy the **Client ID** and **Client secret**.
+
+Provide the client to gmail-cli either way:
+
+```bash
+# via env vars
+export GMAIL_CLI_CLIENT_ID="…apps.googleusercontent.com"
+export GMAIL_CLI_CLIENT_SECRET="…"
+
+# or persist to the config file (~/.config/gmail-cli/config.json)
+gmail auth --client-id "…apps.googleusercontent.com" --client-secret "…"
+```
+
+## Authentication
+
+Run the one-time sign-in. Two modes:
+
+```bash
+gmail auth            # loopback: opens a browser, captures the redirect automatically
+gmail auth --manual   # headless: prints a URL, you paste back the `code`
+```
+
+Use `--manual` on a remote/SSH box with no local browser. It stores a refresh
+token in `~/.config/gmail-cli/config.json` (mode 600). From then on every command
+just works — the CLI refreshes short-lived access tokens on its own.
+
+**Prefer bringing your own token?** Any refresh token minted for your OAuth client
+with the Gmail scopes works — obtain one however you like (e.g. the
+[OAuth 2.0 Playground](https://developers.google.com/oauthplayground/)) and set
+`GMAIL_CLI_REFRESH_TOKEN`, or drop `refresh_token` into the config file. `gmail auth`
+is just a convenience wrapper around this.
+
+Scopes requested: `gmail.modify`, `gmail.compose`, `gmail.send`.
+
+## Commands
+
+Read:
+
+| Command | Purpose |
+|---|---|
+| `profile` / `labels` | account info / list labels |
+| `list [query] [--max N] [--label L] [--json]` | list messages (Gmail search syntax) |
+| `search <query>` | alias for `list` |
+| `threads [query] [--max N] [--json]` | list threads |
+| `read <id> [--html] [--json] [--raw]` | full message; `--raw` streams the `.eml` |
+| `thread <id> [--json]` | full thread |
+| `attachments <id>` | list a message's attachments |
+| `download <id> [--attachment ID] [--out DIR]` | save attachment(s) to disk |
+
+Write — body from `--body TEXT`, `--body-file PATH`, or a pipe (`--body -`);
+`--html` sends `multipart/alternative` (HTML + auto plaintext); `--attach` repeatable:
+
+| Command | Purpose |
+|---|---|
+| `send --to A --subject S <body> [--html] [--attach F]... [--cc] [--bcc]` | send a message |
+| `reply <id> <body> [--html] [--all] [--attach F]...` | reply in-thread; `--all` = reply-all |
+| `forward <id> --to A [--body intro] [--html] [--no-attachments]` | forward (re-attaches originals) |
+| `draft …` / `drafts` / `draft-send <id>` / `draft-delete <id>` | draft lifecycle |
+
+Organize — every verb accepts one or more `<id>` **and/or** `--query Q` for batch:
+
+| Command | Purpose |
+|---|---|
+| `modify <id...> [--add L]... [--remove L]...` | add/remove labels (name or id) |
+| `trash` / `untrash` / `markread` / `markunread` / `star` / `unstar` | common actions |
+| `archive` / `unarchive` / `spam` / `unspam` | move mail around |
+| `label-create <name>` / `label-delete <name>` / `label-rename <name> --to <new>` | label admin |
+
+Run `gmail help` for the full list.
+
+## Configuration reference
+
+| Source | Keys |
+|---|---|
+| Env vars | `GMAIL_CLI_CLIENT_ID`, `GMAIL_CLI_CLIENT_SECRET`, `GMAIL_CLI_REFRESH_TOKEN` |
+| Config file (`$GMAIL_CLI_CONFIG` or `~/.config/gmail-cli/config.json`) | `client_id`, `client_secret`, `refresh_token` |
+
+Env vars take precedence over the file. The access-token cache lives at
+`~/.config/gmail-cli/token.json`.
+
+## Development
+
+```bash
+npm test    # node --test (unit tests for MIME, arg parsing, config resolution)
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/bin/gmail.js

@@ -0,0 +1,409 @@
+#!/usr/bin/env node
+// gmail — a stateless, zero-dependency, agent-friendly Gmail CLI.
+//
+// No daemon: each command mints/reuses a cached OAuth access token and exits.
+// Run `gmail auth` once to sign in, then `gmail help` for the command list.
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { gmail } from '../lib/api.js';
+import { parseArgs } from '../lib/args.js';
+import {
+  buildRaw, header, extractBody, htmlToText,
+  listAttachments, base64urlDecode, guessMimeType, parseAddrs,
+} from '../lib/mime.js';
+import { authorize } from '../lib/oauth.js';
+import { resolveCreds, saveConfig, configPath } from '../lib/config.js';
+
+const asArray = (v) => (v === undefined ? [] : [].concat(v));
+const out = (obj) => console.log(JSON.stringify(obj, null, 2));
+
+// --- body / attachment helpers ----------------------------------------------
+function readContent(inline, file) {
+  if (file !== undefined) {
+    if (file === '-' || file === true) return readFileSync(0, 'utf8');
+    return readFileSync(file, 'utf8');
+  }
+  if (inline === '-' || inline === true) return readFileSync(0, 'utf8');
+  return inline;
+}
+
+function resolveBody(flags, { fallback = '' } = {}) {
+  const raw = readContent(flags.body, flags['body-file']);
+  const content = raw === undefined ? fallback : raw;
+  if (flags.html) {
+    return { html: content, text: flags.text ? readContent(flags.text) : undefined };
+  }
+  return { text: content };
+}
+
+function resolveAttachments(flags) {
+  return asArray(flags.attach).map((p) => ({
+    filename: basename(p), mimeType: guessMimeType(p), content: readFileSync(p),
+  }));
+}
+
+let _me = null;
+async function myAddress() {
+  if (!_me) _me = (await gmail('GET', '/profile')).emailAddress;
+  return _me;
+}
+
+// --- label resolution -------------------------------------------------------
+let _labels = null;
+async function allLabels() {
+  if (!_labels) _labels = (await gmail('GET', '/labels')).labels || [];
+  return _labels;
+}
+const SYSTEM_LABELS = ['INBOX', 'SPAM', 'TRASH', 'UNREAD', 'STARRED', 'IMPORTANT', 'SENT', 'DRAFT', 'CHAT', 'CATEGORY_PERSONAL', 'CATEGORY_SOCIAL', 'CATEGORY_PROMOTIONS', 'CATEGORY_UPDATES', 'CATEGORY_FORUMS'];
+async function resolveLabel(nameOrId) {
+  if (SYSTEM_LABELS.includes(nameOrId.toUpperCase())) return nameOrId.toUpperCase();
+  const hit = (await allLabels()).find((l) => l.id === nameOrId || l.name.toLowerCase() === nameOrId.toLowerCase());
+  if (!hit) throw new Error(`unknown label: ${nameOrId} (run \`gmail labels\`)`);
+  return hit.id;
+}
+
+async function resolveTargets(pos, flags) {
+  const ids = [...pos];
+  if (flags.query) {
+    const { messages = [] } = await gmail('GET', '/messages', { query: { q: flags.query, maxResults: flags.max || 100 } });
+    ids.push(...messages.map((m) => m.id));
+  }
+  return [...new Set(ids)];
+}
+
+async function applyLabels(ids, addLabelIds, removeLabelIds) {
+  if (ids.length === 0) throw new Error('no target messages (pass ids or --query)');
+  if (ids.length === 1) {
+    const res = await gmail('POST', `/messages/${ids[0]}/modify`, { body: { addLabelIds, removeLabelIds } });
+    return { id: res.id, labelIds: res.labelIds };
+  }
+  await gmail('POST', '/messages/batchModify', { body: { ids, addLabelIds, removeLabelIds } });
+  return { modified: ids.length, ids };
+}
+
+// --- commands ---------------------------------------------------------------
+const commands = {
+  // auth [--client-id X] [--client-secret Y] [--manual]
+  async auth(pos, flags) {
+    if (flags['client-id']) saveConfig({ client_id: flags['client-id'] });
+    if (flags['client-secret']) saveConfig({ client_secret: flags['client-secret'] });
+    const { clientId, clientSecret } = resolveCreds({ requireToken: false });
+    const refreshToken = await authorize({ clientId, clientSecret, manual: !!flags.manual });
+    saveConfig({ refresh_token: refreshToken });
+    const me = await gmail('GET', '/profile');
+    out({ authenticated: true, email: me.emailAddress, config: configPath() });
+  },
+
+  async profile() { out(await gmail('GET', '/profile')); },
+
+  async labels() { out((await allLabels()).map(({ id, name, type }) => ({ id, name, type }))); },
+
+  async list(pos, flags) {
+    const q = pos.join(' ') || flags.query || undefined;
+    const labelIds = flags.label ? [await resolveLabel(flags.label)] : undefined;
+    const { messages = [] } = await gmail('GET', '/messages', { query: { q, maxResults: flags.max || 20, labelIds } });
+    const rows = [];
+    for (const m of messages) {
+      const msg = await gmail('GET', `/messages/${m.id}`, { query: { format: 'metadata', metadataHeaders: ['From', 'Subject', 'Date'] } });
+      rows.push({
+        id: msg.id, threadId: msg.threadId, date: header(msg.payload, 'Date'),
+        from: header(msg.payload, 'From'), subject: header(msg.payload, 'Subject'),
+        unread: (msg.labelIds || []).includes('UNREAD'), snippet: msg.snippet,
+      });
+    }
+    if (flags.json) return out(rows);
+    if (!rows.length) return console.log('(no messages)');
+    for (const r of rows) {
+      console.log(`${r.unread ? '●' : ' '} ${r.id}  ${r.date}`);
+      console.log(`   From:    ${r.from}`);
+      console.log(`   Subject: ${r.subject}`);
+      console.log(`   ${r.snippet}\n`);
+    }
+  },
+
+  async search(pos, flags) { return commands.list(pos, flags); },
+
+  async threads(pos, flags) {
+    const q = pos.join(' ') || flags.query || undefined;
+    const { threads = [] } = await gmail('GET', '/threads', { query: { q, maxResults: flags.max || 20 } });
+    const rows = [];
+    for (const t of threads) {
+      const th = await gmail('GET', `/threads/${t.id}`, { query: { format: 'metadata', metadataHeaders: ['From', 'Subject', 'Date'] } });
+      const last = th.messages[th.messages.length - 1];
+      rows.push({ threadId: th.id, messages: th.messages.length, subject: header(last.payload, 'Subject'), from: header(last.payload, 'From'), date: header(last.payload, 'Date'), snippet: th.messages[0].snippet });
+    }
+    if (flags.json) return out(rows);
+    if (!rows.length) return console.log('(no threads)');
+    for (const r of rows) {
+      console.log(`${r.threadId}  (${r.messages} msg)  ${r.date}`);
+      console.log(`   ${r.from}`);
+      console.log(`   ${r.subject}\n`);
+    }
+  },
+
+  async read(pos, flags) {
+    const id = pos[0];
+    if (!id) throw new Error('usage: gmail read <messageId>');
+    if (flags.raw) {
+      const msg = await gmail('GET', `/messages/${id}`, { query: { format: 'raw' } });
+      return process.stdout.write(base64urlDecode(msg.raw));
+    }
+    const msg = await gmail('GET', `/messages/${id}`, { query: { format: 'full' } });
+    if (flags.json) return out(msg);
+    const body = extractBody(msg.payload);
+    const atts = listAttachments(msg.payload);
+    console.log(`Date:    ${header(msg.payload, 'Date')}`);
+    console.log(`From:    ${header(msg.payload, 'From')}`);
+    console.log(`To:      ${header(msg.payload, 'To')}`);
+    const cc = header(msg.payload, 'Cc');
+    if (cc) console.log(`Cc:      ${cc}`);
+    console.log(`Subject: ${header(msg.payload, 'Subject')}`);
+    console.log(`Labels:  ${(msg.labelIds || []).join(', ')}`);
+    if (atts.length) console.log(`Attach:  ${atts.map((a) => `${a.filename} (${a.mimeType}, ${a.size}B)`).join('; ')}`);
+    console.log('');
+    if (flags.html && body.html) console.log(body.html);
+    else console.log(body.text || (body.html ? htmlToText(body.html) : msg.snippet));
+  },
+
+  async thread(pos, flags) {
+    const id = pos[0];
+    if (!id) throw new Error('usage: gmail thread <threadId>');
+    const th = await gmail('GET', `/threads/${id}`, { query: { format: 'full' } });
+    if (flags.json) return out(th);
+    for (const msg of th.messages || []) {
+      const body = extractBody(msg.payload);
+      console.log('─'.repeat(60));
+      console.log(`Date:    ${header(msg.payload, 'Date')}`);
+      console.log(`From:    ${header(msg.payload, 'From')}`);
+      console.log(`Subject: ${header(msg.payload, 'Subject')}\n`);
+      console.log(body.text || (body.html ? htmlToText(body.html) : msg.snippet));
+      console.log('');
+    }
+  },
+
+  async attachments(pos) {
+    const id = pos[0];
+    if (!id) throw new Error('usage: gmail attachments <messageId>');
+    const msg = await gmail('GET', `/messages/${id}`, { query: { format: 'full' } });
+    out(listAttachments(msg.payload));
+  },
+
+  async download(pos, flags) {
+    const id = pos[0];
+    if (!id) throw new Error('usage: gmail download <messageId> [--attachment <id>] [--out <dir>]');
+    const msg = await gmail('GET', `/messages/${id}`, { query: { format: 'full' } });
+    let atts = listAttachments(msg.payload);
+    if (flags.attachment) atts = atts.filter((a) => a.attachmentId === flags.attachment);
+    if (!atts.length) throw new Error('no matching attachments');
+    const dir = (flags.out && flags.out !== true) ? flags.out : '.';
+    const saved = [];
+    for (const a of atts) {
+      const data = await gmail('GET', `/messages/${id}/attachments/${a.attachmentId}`);
+      const path = `${dir.replace(/\/$/, '')}/${a.filename}`;
+      writeFileSync(path, base64urlDecode(data.data));
+      saved.push({ file: path, bytes: a.size });
+    }
+    out({ downloaded: saved });
+  },
+
+  async send(pos, flags) {
+    if (!flags.to) throw new Error('usage: gmail send --to <addr> --subject <s> --body <text>|--body-file <f> [--html] [--attach <f>]... [--cc] [--bcc]');
+    const { text, html } = resolveBody(flags);
+    const raw = buildRaw({ to: asArray(flags.to), cc: asArray(flags.cc), bcc: asArray(flags.bcc), subject: flags.subject || '', text, html, attachments: resolveAttachments(flags) });
+    const res = await gmail('POST', '/messages/send', { body: { raw } });
+    out({ sent: true, id: res.id, threadId: res.threadId });
+  },
+
+  async reply(pos, flags) {
+    const id = pos[0];
+    if (!id) throw new Error('usage: gmail reply <messageId> --body <text> [--html] [--all] [--attach <f>]...');
+    const orig = await gmail('GET', `/messages/${id}`, { query: { format: 'metadata', metadataHeaders: ['From', 'To', 'Cc', 'Subject', 'Message-ID', 'References', 'Reply-To'] } });
+    const p = orig.payload;
+    const me = (await myAddress()).toLowerCase();
+    const fromAddr = parseAddrs(header(p, 'Reply-To') || header(p, 'From'));
+    const to = fromAddr.map((a) => a.raw);
+    let cc = [];
+    if (flags.all) {
+      const seen = new Set([me, ...fromAddr.map((a) => a.email.toLowerCase())]);
+      for (const a of [...parseAddrs(header(p, 'To')), ...parseAddrs(header(p, 'Cc'))]) {
+        const key = a.email.toLowerCase();
+        if (seen.has(key)) continue;
+        seen.add(key);
+        cc.push(a.raw);
+      }
+    }
+    const subject = header(p, 'Subject');
+    const msgId = header(p, 'Message-ID');
+    const refs = [header(p, 'References'), msgId].filter(Boolean).join(' ');
+    const { text, html } = resolveBody(flags);
+    const raw = buildRaw({ to, cc, subject: /^re:/i.test(subject) ? subject : `Re: ${subject}`, text, html, attachments: resolveAttachments(flags), inReplyTo: msgId || undefined, references: refs || undefined });
+    const res = await gmail('POST', '/messages/send', { body: { raw, threadId: orig.threadId } });
+    out({ replied: true, id: res.id, threadId: res.threadId, cc });
+  },
+
+  async forward(pos, flags) {
+    const id = pos[0];
+    if (!id || !flags.to) throw new Error('usage: gmail forward <messageId> --to <addr> [--body <intro>] [--html] [--no-attachments]');
+    const orig = await gmail('GET', `/messages/${id}`, { query: { format: 'full' } });
+    const p = orig.payload;
+    const body = extractBody(p);
+    const intro = resolveBody(flags, { fallback: '' });
+    const quotedHeader = ['---------- Forwarded message ----------', `From: ${header(p, 'From')}`, `Date: ${header(p, 'Date')}`, `Subject: ${header(p, 'Subject')}`, `To: ${header(p, 'To')}`, ''].join('\n');
+    let attachments = [];
+    if (!flags['no-attachments']) {
+      for (const a of listAttachments(p)) {
+        const data = await gmail('GET', `/messages/${id}/attachments/${a.attachmentId}`);
+        attachments.push({ filename: a.filename, mimeType: a.mimeType, content: base64urlDecode(data.data) });
+      }
+    }
+    let sendBody;
+    if (flags.html) {
+      const origHtml = body.html || `<pre>${htmlToText(body.text || '')}</pre>`;
+      sendBody = { html: `${intro.html || ''}<br><br>${quotedHeader.replace(/\n/g, '<br>')}<br>${origHtml}` };
+    } else {
+      sendBody = { text: `${intro.text || ''}\n\n${quotedHeader}\n${body.text || htmlToText(body.html || '')}` };
+    }
+    const subject = header(p, 'Subject');
+    const raw = buildRaw({ to: asArray(flags.to), cc: asArray(flags.cc), bcc: asArray(flags.bcc), subject: /^fwd?:/i.test(subject) ? subject : `Fwd: ${subject}`, ...sendBody, attachments });
+    const res = await gmail('POST', '/messages/send', { body: { raw } });
+    out({ forwarded: true, id: res.id, threadId: res.threadId, attachments: attachments.length });
+  },
+
+  async draft(pos, flags) {
+    if (!flags.to) throw new Error('usage: gmail draft --to <addr> --subject <s> --body <text> [--html] [--attach <f>]...');
+    const { text, html } = resolveBody(flags);
+    const raw = buildRaw({ to: asArray(flags.to), cc: asArray(flags.cc), bcc: asArray(flags.bcc), subject: flags.subject || '', text, html, attachments: resolveAttachments(flags) });
+    const res = await gmail('POST', '/drafts', { body: { message: { raw } } });
+    out({ draft: true, id: res.id, messageId: res.message?.id });
+  },
+
+  async drafts(pos, flags) {
+    const { drafts = [] } = await gmail('GET', '/drafts', { query: { maxResults: flags.max || 20 } });
+    const rows = [];
+    for (const d of drafts) {
+      const msg = await gmail('GET', `/messages/${d.message.id}`, { query: { format: 'metadata', metadataHeaders: ['To', 'Subject'] } });
+      rows.push({ draftId: d.id, to: header(msg.payload, 'To'), subject: header(msg.payload, 'Subject'), snippet: msg.snippet });
+    }
+    out(rows);
+  },
+
+  async 'draft-send'(pos) {
+    const id = pos[0];
+    if (!id) throw new Error('usage: gmail draft-send <draftId>');
+    const res = await gmail('POST', '/drafts/send', { body: { id } });
+    out({ sent: true, id: res.id, threadId: res.threadId });
+  },
+
+  async 'draft-delete'(pos) {
+    const id = pos[0];
+    if (!id) throw new Error('usage: gmail draft-delete <draftId>');
+    await gmail('DELETE', `/drafts/${id}`);
+    out({ deleted: true, draftId: id });
+  },
+
+  async modify(pos, flags) {
+    const ids = await resolveTargets(pos, flags);
+    const addLabelIds = [];
+    const removeLabelIds = [];
+    for (const l of asArray(flags.add)) addLabelIds.push(await resolveLabel(l));
+    for (const l of asArray(flags.remove)) removeLabelIds.push(await resolveLabel(l));
+    out(await applyLabels(ids, addLabelIds, removeLabelIds));
+  },
+
+  async trash(pos, flags) {
+    const ids = await resolveTargets(pos, flags);
+    const done = [];
+    for (const id of ids) { await gmail('POST', `/messages/${id}/trash`); done.push(id); }
+    out({ trashed: done.length, ids: done });
+  },
+
+  async untrash(pos, flags) {
+    const ids = await resolveTargets(pos, flags);
+    const done = [];
+    for (const id of ids) { await gmail('POST', `/messages/${id}/untrash`); done.push(id); }
+    out({ untrashed: done.length, ids: done });
+  },
+
+  async markread(pos, flags) { out(await applyLabels(await resolveTargets(pos, flags), [], ['UNREAD'])); },
+  async markunread(pos, flags) { out(await applyLabels(await resolveTargets(pos, flags), ['UNREAD'], [])); },
+  async star(pos, flags) { out(await applyLabels(await resolveTargets(pos, flags), ['STARRED'], [])); },
+  async unstar(pos, flags) { out(await applyLabels(await resolveTargets(pos, flags), [], ['STARRED'])); },
+  async archive(pos, flags) { out(await applyLabels(await resolveTargets(pos, flags), [], ['INBOX'])); },
+  async unarchive(pos, flags) { out(await applyLabels(await resolveTargets(pos, flags), ['INBOX'], [])); },
+  async spam(pos, flags) { out(await applyLabels(await resolveTargets(pos, flags), ['SPAM'], ['INBOX'])); },
+  async unspam(pos, flags) { out(await applyLabels(await resolveTargets(pos, flags), ['INBOX'], ['SPAM'])); },
+
+  async 'label-create'(pos, flags) {
+    const name = pos[0] || flags.name;
+    if (!name) throw new Error('usage: gmail label-create <name>');
+    const res = await gmail('POST', '/labels', { body: { name, labelListVisibility: 'labelShow', messageListVisibility: 'show' } });
+    out({ created: true, id: res.id, name: res.name });
+  },
+
+  async 'label-delete'(pos) {
+    if (!pos[0]) throw new Error('usage: gmail label-delete <name-or-id>');
+    const id = await resolveLabel(pos[0]);
+    await gmail('DELETE', `/labels/${id}`);
+    out({ deleted: true, id });
+  },
+
+  async 'label-rename'(pos, flags) {
+    if (!pos[0] || !flags.to) throw new Error('usage: gmail label-rename <name-or-id> --to <newName>');
+    const id = await resolveLabel(pos[0]);
+    const res = await gmail('PATCH', `/labels/${id}`, { body: { name: flags.to } });
+    out({ renamed: true, id: res.id, name: res.name });
+  },
+
+  help() {
+    console.log(`gmail — stateless, zero-dep Gmail CLI
+
+Setup:
+  gmail auth [--manual] [--client-id X --client-secret Y]
+                                         one-time OAuth sign-in
+
+Read:
+  profile | labels
+  list [query] [--max N] [--label L] [--json]
+  search <query>                         alias for list
+  threads [query] [--max N] [--json]
+  read <id> [--html] [--json] [--raw]    (--raw = .eml to stdout)
+  thread <id> [--json]
+  attachments <id>
+  download <id> [--attachment ID] [--out DIR]
+
+Write (body: --body TEXT | --body-file F | pipe '-'; --html sends HTML+text):
+  send --to A --subject S --body B [--html] [--attach F]... [--cc] [--bcc]
+  reply <id> --body B [--html] [--all] [--attach F]...
+  forward <id> --to A [--body intro] [--html] [--no-attachments]
+  draft --to A --subject S --body B [--html] [--attach F]...
+  drafts | draft-send <draftId> | draft-delete <draftId>
+
+Organize (accept <id>... and/or --query Q for batch):
+  modify <id...> [--add L]... [--remove L]...
+  trash | untrash | markread | markunread | star | unstar
+  archive | unarchive | spam | unspam
+  label-create <name> | label-delete <name> | label-rename <name> --to <new>
+
+Docs: https://github.com/harteWired/gmail-cli`);
+  },
+};
+
+async function main() {
+  const [, , cmd, ...rest] = process.argv;
+  const command = commands[cmd];
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h' || !command) {
+    if (cmd && !command) console.error(`unknown command: ${cmd}\n`);
+    commands.help();
+    process.exit(cmd && !command ? 1 : 0);
+  }
+  const { positional, flags } = parseArgs(rest);
+  try {
+    await command(positional, flags);
+  } catch (err) {
+    console.error(`error: ${err.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/lib/api.js

@@ -0,0 +1,33 @@
+// Thin wrapper over the Gmail REST API for the authenticated user (`me`).
+
+import { getAccessToken } from './auth.js';
+
+const BASE = 'https://gmail.googleapis.com/gmail/v1/users/me';
+
+// method: GET/POST; path: e.g. '/messages'; query: object; body: JSON-able.
+export async function gmail(method, path, { query, body } = {}) {
+  const token = await getAccessToken();
+  const url = new URL(BASE + path);
+  if (query) {
+    for (const [k, v] of Object.entries(query)) {
+      if (v === undefined || v === null) continue;
+      if (Array.isArray(v)) v.forEach((x) => url.searchParams.append(k, x));
+      else url.searchParams.set(k, v);
+    }
+  }
+  const res = await fetch(url, {
+    method,
+    headers: {
+      Authorization: `Bearer ${token}`,
+      ...(body ? { 'Content-Type': 'application/json' } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  const data = text ? JSON.parse(text) : {};
+  if (!res.ok) {
+    const msg = data?.error?.message || res.statusText;
+    throw new Error(`Gmail API ${method} ${path} failed (HTTP ${res.status}): ${msg}`);
+  }
+  return data;
+}

package/lib/args.js

@@ -0,0 +1,22 @@
+// Minimal argv parser: splits positionals from --flags. Repeated flags become
+// arrays; bare flags (no following value) are booleans.
+export function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith('--')) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) {
+        flags[key] = true;
+      } else {
+        flags[key] = key in flags ? [].concat(flags[key], next) : next;
+        i++;
+      }
+    } else {
+      positional.push(a);
+    }
+  }
+  return { positional, flags };
+}

package/lib/auth.js

@@ -0,0 +1,43 @@
+// OAuth access-token minting. Reads credentials via config.js and caches a
+// short-lived access token so back-to-back commands don't re-hit Google.
+// Stateless: no server, nothing runs when idle.
+
+import { resolveCreds, readTokenCache, writeTokenCache } from './config.js';
+
+export const TOKEN_ENDPOINT = 'https://oauth2.googleapis.com/token';
+
+async function refresh() {
+  const { clientId, clientSecret, refreshToken } = resolveCreds();
+  const body = new URLSearchParams({
+    client_id: clientId,
+    client_secret: clientSecret,
+    refresh_token: refreshToken,
+    grant_type: 'refresh_token',
+  });
+  const res = await fetch(TOKEN_ENDPOINT, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body,
+  });
+  const data = await res.json();
+  if (!res.ok || !data.access_token) {
+    throw new Error(
+      `token refresh failed (HTTP ${res.status}): ${data.error || 'unknown'} — ${data.error_description || ''}`.trim() +
+      (data.error === 'invalid_grant' ? '\nThe stored refresh token was revoked or expired. Run `gmail auth` again.' : '')
+    );
+  }
+  writeTokenCache({
+    access_token: data.access_token,
+    expires_at: Math.floor(Date.now() / 1000) + (data.expires_in || 3600) - 60,
+  });
+  return data.access_token;
+}
+
+// Returns a valid access token, refreshing only when the cached one is stale.
+export async function getAccessToken() {
+  const cache = readTokenCache();
+  if (cache?.access_token && cache.expires_at > Math.floor(Date.now() / 1000)) {
+    return cache.access_token;
+  }
+  return refresh();
+}

package/lib/config.js

@@ -0,0 +1,87 @@
+// Configuration + credential resolution for gmail-cli.
+//
+// Credentials (OAuth client id/secret + refresh token) resolve in priority
+// order:
+//   1. Environment variables (GMAIL_CLI_CLIENT_ID, _CLIENT_SECRET, _REFRESH_TOKEN)
+//   2. Config file JSON (default ~/.config/gmail-cli/config.json, override with
+//      $GMAIL_CLI_CONFIG)
+//
+// The short-lived access token is cached next to the config file.
+
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync,
+} from 'node:fs';
+
+// Paths are resolved lazily (read env at call time) so overrides and tests work.
+export function configDir() {
+  const xdg = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+  return join(xdg, 'gmail-cli');
+}
+export function configPath() {
+  return process.env.GMAIL_CLI_CONFIG || join(configDir(), 'config.json');
+}
+export function tokenPath() {
+  return join(configDir(), 'token.json');
+}
+
+function ensureDir() {
+  mkdirSync(configDir(), { recursive: true, mode: 0o700 });
+}
+
+export function loadConfig() {
+  try {
+    return JSON.parse(readFileSync(configPath(), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+// Merge a patch into the config file and persist it (mode 600 — holds secrets).
+export function saveConfig(patch) {
+  ensureDir();
+  const merged = { ...loadConfig(), ...patch };
+  const path = configPath();
+  writeFileSync(path, JSON.stringify(merged, null, 2) + '\n', { mode: 0o600 });
+  if (existsSync(path)) chmodSync(path, 0o600);
+  return merged;
+}
+
+// Resolve { clientId, clientSecret, refreshToken }. `requireToken=false` skips
+// the refresh-token requirement (used by `gmail auth`, which is minting one).
+export function resolveCreds({ requireToken = true } = {}) {
+  const file = loadConfig();
+  const clientId = process.env.GMAIL_CLI_CLIENT_ID || file.client_id;
+  const clientSecret = process.env.GMAIL_CLI_CLIENT_SECRET || file.client_secret;
+  const refreshToken = process.env.GMAIL_CLI_REFRESH_TOKEN || file.refresh_token;
+
+  if (!clientId || !clientSecret) {
+    throw new Error(
+      'no OAuth client configured. Set GMAIL_CLI_CLIENT_ID / GMAIL_CLI_CLIENT_SECRET, ' +
+      `or add client_id / client_secret to ${configPath()}. See README "Setup".`
+    );
+  }
+  if (requireToken && !refreshToken) {
+    throw new Error(
+      'not authenticated. Run `gmail auth` to sign in, or set GMAIL_CLI_REFRESH_TOKEN. ' +
+      'See README "Authentication".'
+    );
+  }
+  return { clientId, clientSecret, refreshToken };
+}
+
+export function readTokenCache() {
+  try {
+    return JSON.parse(readFileSync(tokenPath(), 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function writeTokenCache(obj) {
+  ensureDir();
+  const path = tokenPath();
+  writeFileSync(path, JSON.stringify(obj), { mode: 0o600 });
+  if (existsSync(path)) chmodSync(path, 0o600);
+}

package/lib/mime.js

@@ -0,0 +1,195 @@
+// MIME helpers: build outgoing RFC 2822 messages (with multipart/alternative
+// and attachments) and decode incoming ones.
+
+import { randomBytes } from 'node:crypto';
+import { basename, extname } from 'node:path';
+
+function base64url(buf) {
+  return Buffer.from(buf)
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+export function base64urlDecode(str) {
+  return Buffer.from(str.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+}
+
+// Encode a header value that may contain non-ASCII (RFC 2047, B-encoding).
+function encodeHeader(value) {
+  // eslint-disable-next-line no-control-regex
+  if (/^[\x00-\x7F]*$/.test(value)) return value;
+  return `=?UTF-8?B?${Buffer.from(value, 'utf8').toString('base64')}?=`;
+}
+
+// Wrap a base64 string at 76 chars per RFC 2045.
+const wrap76 = (b64) => b64.replace(/(.{76})/g, '$1\r\n');
+
+// A minimal extension -> MIME type map for attachments.
+const MIME_TYPES = {
+  '.pdf': 'application/pdf', '.png': 'image/png', '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp',
+  '.svg': 'image/svg+xml', '.txt': 'text/plain', '.md': 'text/markdown',
+  '.csv': 'text/csv', '.html': 'text/html', '.json': 'application/json',
+  '.zip': 'application/zip', '.doc': 'application/msword', '.ics': 'text/calendar',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xls': 'application/vnd.ms-excel',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+};
+export function guessMimeType(filename) {
+  return MIME_TYPES[extname(filename).toLowerCase()] || 'application/octet-stream';
+}
+
+// Build a single MIME part from a set of header lines and a base64 body.
+function part(headers, bodyBase64) {
+  return [...headers, '', wrap76(bodyBase64)].join('\r\n');
+}
+
+// Build the body section (everything below the top-level headers): handles
+// text-only, html+text (multipart/alternative), and attachments
+// (multipart/mixed wrapping the body). Returns { headers[], body }.
+function buildBody({ text, html, attachments }) {
+  // 1. The message body: text/plain, or multipart/alternative when HTML exists.
+  let bodyHeaders;
+  let bodyContent;
+  if (html) {
+    const altBoundary = `alt_${randomBytes(12).toString('hex')}`;
+    const textPart = part(
+      ['Content-Type: text/plain; charset=UTF-8', 'Content-Transfer-Encoding: base64'],
+      Buffer.from(text || htmlToText(html), 'utf8').toString('base64')
+    );
+    const htmlPart = part(
+      ['Content-Type: text/html; charset=UTF-8', 'Content-Transfer-Encoding: base64'],
+      Buffer.from(html, 'utf8').toString('base64')
+    );
+    bodyHeaders = [`Content-Type: multipart/alternative; boundary="${altBoundary}"`];
+    bodyContent = [
+      `--${altBoundary}`, textPart,
+      `--${altBoundary}`, htmlPart,
+      `--${altBoundary}--`,
+    ].join('\r\n');
+  } else {
+    bodyHeaders = ['Content-Type: text/plain; charset=UTF-8', 'Content-Transfer-Encoding: base64'];
+    bodyContent = wrap76(Buffer.from(text || '', 'utf8').toString('base64'));
+  }
+
+  // 2. No attachments -> the body is the whole message.
+  if (!attachments || attachments.length === 0) {
+    return { headers: bodyHeaders, body: bodyContent };
+  }
+
+  // 3. Attachments -> multipart/mixed [ bodyPart, ...attachments ].
+  const mixedBoundary = `mix_${randomBytes(12).toString('hex')}`;
+  const bodyPart = [...bodyHeaders, '', bodyContent].join('\r\n');
+  const attachParts = attachments.map((a) => {
+    const name = encodeHeader(a.filename);
+    return part(
+      [
+        `Content-Type: ${a.mimeType || guessMimeType(a.filename)}; name="${name}"`,
+        'Content-Transfer-Encoding: base64',
+        `Content-Disposition: attachment; filename="${name}"`,
+      ],
+      a.content.toString('base64')
+    );
+  });
+  const body = [
+    `--${mixedBoundary}`, bodyPart,
+    ...attachParts.flatMap((p) => [`--${mixedBoundary}`, p]),
+    `--${mixedBoundary}--`,
+  ].join('\r\n');
+  return { headers: [`Content-Type: multipart/mixed; boundary="${mixedBoundary}"`], body };
+}
+
+// Build a base64url-encoded raw message for messages.send / drafts.
+// opts: { from, to[], cc[], bcc[], subject, text, html, attachments[],
+//         inReplyTo, references }
+// attachments: [{ filename, mimeType?, content: Buffer }]
+export function buildRaw(opts) {
+  const addr = (arr) => (Array.isArray(arr) ? arr.join(', ') : arr);
+  const top = [];
+  if (opts.from) top.push(`From: ${opts.from}`);
+  top.push(`To: ${addr(opts.to)}`);
+  if (opts.cc?.length) top.push(`Cc: ${addr(opts.cc)}`);
+  if (opts.bcc?.length) top.push(`Bcc: ${addr(opts.bcc)}`);
+  top.push(`Subject: ${encodeHeader(opts.subject || '')}`);
+  if (opts.inReplyTo) top.push(`In-Reply-To: ${opts.inReplyTo}`);
+  if (opts.references) top.push(`References: ${opts.references}`);
+  top.push('MIME-Version: 1.0');
+
+  const { headers, body } = buildBody(opts);
+  return base64url([...top, ...headers, '', body].join('\r\n'));
+}
+
+// Pull a header value (case-insensitive) from a message payload.
+export function header(payload, name) {
+  const h = payload?.headers?.find((x) => x.name.toLowerCase() === name.toLowerCase());
+  return h?.value || '';
+}
+
+// Recursively extract the best text body. Returns { text, html }.
+export function extractBody(payload) {
+  const out = { text: '', html: '' };
+  const walk = (p) => {
+    if (!p) return;
+    const mime = p.mimeType || '';
+    if (p.body?.data) {
+      const decoded = base64urlDecode(p.body.data).toString('utf8');
+      if (mime === 'text/plain' && !out.text) out.text = decoded;
+      else if (mime === 'text/html' && !out.html) out.html = decoded;
+    }
+    if (p.parts) p.parts.forEach(walk);
+  };
+  walk(payload);
+  return out;
+}
+
+// List attachment parts in a payload: [{ filename, mimeType, size, attachmentId }].
+export function listAttachments(payload) {
+  const found = [];
+  const walk = (p) => {
+    if (!p) return;
+    if (p.filename && p.body?.attachmentId) {
+      found.push({
+        filename: p.filename,
+        mimeType: p.mimeType,
+        size: p.body.size,
+        attachmentId: p.body.attachmentId,
+      });
+    }
+    if (p.parts) p.parts.forEach(walk);
+  };
+  walk(payload);
+  return found;
+}
+
+// Very light HTML -> text fallback for display and for the plaintext alternative.
+export function htmlToText(html) {
+  return html
+    .replace(/<style[\s\S]*?<\/style>/gi, '')
+    .replace(/<script[\s\S]*?<\/script>/gi, '')
+    .replace(/<\/(p|div|tr|h[1-6]|li)>/gi, '\n')
+    .replace(/<br\s*\/?>/gi, '\n')
+    .replace(/<[^>]+>/g, '')
+    .replace(/&nbsp;/g, ' ')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'")
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+// Parse "Name <a@b.com>, c@d.com" -> [{ name, email, raw }].
+export function parseAddrs(str) {
+  if (!str) return [];
+  return str.split(',').map((chunk) => {
+    const m = chunk.match(/<([^>]+)>/);
+    const email = (m ? m[1] : chunk).trim();
+    const name = m ? chunk.slice(0, m.index).trim().replace(/^"|"$/g, '') : '';
+    return { name, email, raw: chunk.trim() };
+  }).filter((a) => a.email);
+}
+
+export { basename };

package/lib/oauth.js

@@ -0,0 +1,126 @@
+// Interactive OAuth for `gmail auth`. Two modes:
+//   - loopback (default): spin a localhost server, open the browser, capture the
+//     redirect automatically.
+//   - manual (--manual): print the URL, user pastes back the `code`. For
+//     headless / remote machines with no local browser.
+
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { TOKEN_ENDPOINT } from './auth.js';
+
+const AUTH_ENDPOINT = 'https://accounts.google.com/o/oauth2/v2/auth';
+
+// Full set the CLI needs: read/modify/labels/trash (modify), drafts (compose),
+// send.
+export const SCOPES = [
+  'https://www.googleapis.com/auth/gmail.modify',
+  'https://www.googleapis.com/auth/gmail.compose',
+  'https://www.googleapis.com/auth/gmail.send',
+];
+
+function buildAuthUrl({ clientId, redirectUri, state }) {
+  const u = new URL(AUTH_ENDPOINT);
+  u.searchParams.set('client_id', clientId);
+  u.searchParams.set('redirect_uri', redirectUri);
+  u.searchParams.set('response_type', 'code');
+  u.searchParams.set('scope', SCOPES.join(' '));
+  u.searchParams.set('access_type', 'offline'); // request a refresh token
+  u.searchParams.set('prompt', 'consent'); // force refresh_token every time
+  if (state) u.searchParams.set('state', state);
+  return u.toString();
+}
+
+async function exchangeCode({ code, clientId, clientSecret, redirectUri }) {
+  const res = await fetch(TOKEN_ENDPOINT, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body: new URLSearchParams({
+      code, client_id: clientId, client_secret: clientSecret,
+      redirect_uri: redirectUri, grant_type: 'authorization_code',
+    }),
+  });
+  const data = await res.json();
+  if (!res.ok || !data.refresh_token) {
+    throw new Error(
+      `code exchange failed (HTTP ${res.status}): ${data.error || 'unknown'} — ${data.error_description || ''}`.trim() +
+      (!data.refresh_token && res.ok ? '\nNo refresh_token returned — revoke prior access at myaccount.google.com and retry (prompt=consent is set).' : '')
+    );
+  }
+  return data.refresh_token;
+}
+
+function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open'
+    : process.platform === 'win32' ? 'cmd'
+    : 'xdg-open';
+  const args = process.platform === 'win32' ? ['/c', 'start', '""', url] : [url];
+  try {
+    spawn(cmd, args, { stdio: 'ignore', detached: true }).unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => rl.question(question, (a) => { rl.close(); resolve(a.trim()); }));
+}
+
+// Manual flow: fixed OOB-style loopback URI the user completes anywhere, then
+// pastes the code. Uses http://127.0.0.1 as redirect (must be registered on the
+// OAuth client) — the browser lands on a "can't connect" page whose URL carries
+// ?code=...; the user copies that code.
+async function manualFlow({ clientId, clientSecret }) {
+  const redirectUri = 'http://127.0.0.1';
+  const url = buildAuthUrl({ clientId, redirectUri });
+  console.log('\nOpen this URL in any browser, approve access, then copy the `code`');
+  console.log('value from the address bar of the page you land on:\n');
+  console.log(url + '\n');
+  const code = await prompt('Paste the code here: ');
+  if (!code) throw new Error('no code provided');
+  return exchangeCode({ code, clientId, clientSecret, redirectUri });
+}
+
+// Loopback flow: capture the redirect on a local port automatically.
+function loopbackFlow({ clientId, clientSecret }) {
+  return new Promise((resolve, reject) => {
+    const server = createServer(async (req, res) => {
+      try {
+        const url = new URL(req.url, `http://127.0.0.1`);
+        const code = url.searchParams.get('code');
+        const err = url.searchParams.get('error');
+        res.writeHead(200, { 'Content-Type': 'text/html' });
+        res.end(`<html><body style="font-family:sans-serif;padding:2rem"><h2>${err ? 'Authorization failed' : 'Authorized — you can close this tab.'}</h2></body></html>`);
+        server.close();
+        if (err) return reject(new Error(`authorization denied: ${err}`));
+        if (!code) return reject(new Error('no code in redirect'));
+        const port = server.address().port;
+        const refreshToken = await exchangeCode({
+          code, clientId, clientSecret, redirectUri: `http://127.0.0.1:${port}`,
+        });
+        resolve(refreshToken);
+      } catch (e) {
+        reject(e);
+      }
+    });
+    server.on('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const port = server.address().port;
+      const redirectUri = `http://127.0.0.1:${port}`;
+      const url = buildAuthUrl({ clientId, redirectUri });
+      console.log('\nOpening your browser to authorize gmail-cli...');
+      console.log('If it does not open, visit this URL manually:\n');
+      console.log(url + '\n');
+      openBrowser(url);
+    });
+  });
+}
+
+// Run the interactive grant and return a refresh token.
+export function authorize({ clientId, clientSecret, manual }) {
+  return manual
+    ? manualFlow({ clientId, clientSecret })
+    : loopbackFlow({ clientId, clientSecret });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@hartewired/gmail-cli",
+  "version": "1.0.0",
+  "description": "A stateless, zero-dependency, agent-friendly Gmail CLI. Read, send, reply, label, and organize mail from the shell — no daemon, JSON output on every command.",
+  "type": "module",
+  "bin": {
+    "gmail": "bin/gmail.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "gmail",
+    "cli",
+    "email",
+    "google",
+    "oauth",
+    "agent",
+    "llm",
+    "automation",
+    "stateless",
+    "zero-dependency"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/harteWired/gmail-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/harteWired/gmail-cli/issues"
+  },
+  "homepage": "https://github.com/harteWired/gmail-cli#readme",
+  "author": "Matt Harte (https://github.com/harteWired)",
+  "license": "MIT"
+}