@hartewired/gmail-cli 1.0.0 → 1.1.0

package/README.md

@@ -1,8 +1,10 @@
 # gmail-cli
 
-[![by — harteWired](https://img.shields.io/badge/by-harteWired-e6a562?style=flat&labelColor=15151e)](https://github.com/harteWired)
+[![publish](https://img.shields.io/github/actions/workflow/status/harteWired/gmail-cli/publish.yml?style=flat&labelColor=15151e&color=e6a562&label=publish)](https://github.com/harteWired/gmail-cli/actions/workflows/publish.yml)
 [![npm](https://img.shields.io/npm/v/@hartewired/gmail-cli?style=flat&labelColor=15151e&color=e6a562)](https://www.npmjs.com/package/@hartewired/gmail-cli)
+[![node](https://img.shields.io/node/v/@hartewired/gmail-cli?style=flat&labelColor=15151e&color=e6a562)](https://nodejs.org)
 [![license: MIT](https://img.shields.io/badge/license-MIT-e6a562?style=flat&labelColor=15151e)](./LICENSE)
+[![by — harteWired](https://img.shields.io/badge/by-harteWired-e6a562?style=flat&labelColor=15151e)](https://github.com/harteWired)
 
 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.
 
@@ -13,6 +15,10 @@ gmail reply <id> --all --body "Thanks — got it."
 gmail markread --query "is:unread older_than:30d"
 ```
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/harteWired/gmail-cli/main/docs/architecture.svg" width="820" alt="Stateless architecture: a caller shells out to gmail, which resolves credentials, mints or reuses a cached access token, calls the Gmail REST API, prints JSON, and exits. No daemon runs when idle.">
+</p>
+
 ## 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:
@@ -73,6 +79,27 @@ is just a convenience wrapper around this.
 
 Scopes requested: `gmail.modify`, `gmail.compose`, `gmail.send`.
 
+## Multiple accounts
+
+Every command takes `--account NAME` to target a specific inbox. Authorize each one once:
+
+```bash
+gmail auth --account personal
+gmail auth --account work
+```
+
+Then target them per command:
+
+```bash
+gmail list --account work "is:unread"
+gmail send --account personal --to a@b.com --subject Hi --body "hey"
+gmail accounts                 # list configured accounts + the default
+```
+
+The first account you authorize becomes the default (used whenever `--account`
+is omitted). Each account's credentials and token cache are stored separately.
+A single-account setup never needs `--account` at all.
+
 ## Commands
 
 Read:
@@ -111,13 +138,25 @@ 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` |
+The config file (`$GMAIL_CLI_CONFIG`, default `~/.config/gmail-cli/config.json`)
+holds named accounts:
+
+```json
+{
+  "default": "personal",
+  "accounts": {
+    "personal": { "client_id": "…", "client_secret": "…", "refresh_token": "…" },
+    "work":     { "client_id": "…", "client_secret": "…", "refresh_token": "…" }
+  }
+}
+```
+
+Env vars override the active account per-field (handy for single-account CI):
+`GMAIL_CLI_CLIENT_ID`, `GMAIL_CLI_CLIENT_SECRET`, `GMAIL_CLI_REFRESH_TOKEN`.
 
-Env vars take precedence over the file. The access-token cache lives at
-`~/.config/gmail-cli/token.json`.
+A legacy flat file (`{ "client_id", "client_secret", "refresh_token" }`) is still
+read as the account named `default`. Per-account token caches live at
+`~/.config/gmail-cli/token-<account>.json`.
 
 ## Development
 

package/bin/gmail.js

@@ -13,7 +13,7 @@ import {
   listAttachments, base64urlDecode, guessMimeType, parseAddrs,
 } from '../lib/mime.js';
 import { authorize } from '../lib/oauth.js';
-import { resolveCreds, saveConfig, configPath } from '../lib/config.js';
+import { resolveCreds, saveAccount, setAccount, activeAccount, listAccounts, configPath } from '../lib/config.js';
 
 const asArray = (v) => (v === undefined ? [] : [].concat(v));
 const out = (obj) => console.log(JSON.stringify(obj, null, 2));
@@ -84,15 +84,24 @@ async function applyLabels(ids, addLabelIds, removeLabelIds) {
 
 // --- commands ---------------------------------------------------------------
 const commands = {
-  // auth [--client-id X] [--client-secret Y] [--manual]
+  // auth [--account NAME] [--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 account = flags.account || activeAccount();
+    setAccount(account);
+    const patch = {};
+    if (flags['client-id']) patch.client_id = flags['client-id'];
+    if (flags['client-secret']) patch.client_secret = flags['client-secret'];
+    if (Object.keys(patch).length) saveAccount(account, patch);
     const { clientId, clientSecret } = resolveCreds({ requireToken: false });
     const refreshToken = await authorize({ clientId, clientSecret, manual: !!flags.manual });
-    saveConfig({ refresh_token: refreshToken });
+    saveAccount(account, { refresh_token: refreshToken });
     const me = await gmail('GET', '/profile');
-    out({ authenticated: true, email: me.emailAddress, config: configPath() });
+    out({ authenticated: true, account, email: me.emailAddress, config: configPath() });
+  },
+
+  // accounts — list configured accounts and the active/default one.
+  accounts() {
+    out({ active: activeAccount(), accounts: listAccounts() });
   },
 
   async profile() { out(await gmail('GET', '/profile')); },
@@ -359,8 +368,12 @@ const commands = {
     console.log(`gmail — stateless, zero-dep Gmail CLI
 
 Setup:
-  gmail auth [--manual] [--client-id X --client-secret Y]
+  gmail auth [--account NAME] [--manual] [--client-id X --client-secret Y]
                                          one-time OAuth sign-in
+  gmail accounts                         list configured accounts
+
+Any command takes --account NAME to target a specific inbox (default: the
+configured "default" account).
 
 Read:
   profile | labels
@@ -398,6 +411,7 @@ async function main() {
     process.exit(cmd && !command ? 1 : 0);
   }
   const { positional, flags } = parseArgs(rest);
+  if (flags.account) setAccount(flags.account); // global: select which account this command uses
   try {
     await command(positional, flags);
   } catch (err) {

package/lib/config.js

@@ -1,12 +1,23 @@
 // 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)
+// Multi-account. The config file (default ~/.config/gmail-cli/config.json,
+// override with $GMAIL_CLI_CONFIG) holds named accounts:
 //
-// The short-lived access token is cached next to the config file.
+//   {
+//     "default": "personal",
+//     "accounts": {
+//       "personal": { "client_id": "...", "client_secret": "...", "refresh_token": "..." },
+//       "work":     { "client_id": "...", "client_secret": "...", "refresh_token": "..." }
+//     }
+//   }
+//
+// A legacy flat file ({ "client_id", "client_secret", "refresh_token" }) is
+// still honored and treated as the account named "default".
+//
+// The active account is picked by (in order): the --account flag, the config
+// "default", then "default". Env vars (GMAIL_CLI_CLIENT_ID / _CLIENT_SECRET /
+// _REFRESH_TOKEN) override per-field for whichever account is active — handy
+// for single-account CI.
 
 import { homedir } from 'node:os';
 import { join } from 'node:path';
@@ -14,7 +25,7 @@ import {
   readFileSync, writeFileSync, mkdirSync, existsSync, chmodSync,
 } from 'node:fs';
 
-// Paths are resolved lazily (read env at call time) so overrides and tests work.
+// --- paths (lazy: read env at call time, so tests/overrides work) -----------
 export function configDir() {
   const xdg = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
   return join(xdg, 'gmail-cli');
@@ -22,8 +33,9 @@ export function configDir() {
 export function configPath() {
   return process.env.GMAIL_CLI_CONFIG || join(configDir(), 'config.json');
 }
-export function tokenPath() {
-  return join(configDir(), 'token.json');
+const sanitize = (name) => name.replace(/[^a-zA-Z0-9_-]/g, '_');
+export function tokenPath(account) {
+  return join(configDir(), `token-${sanitize(account || activeAccount())}.json`);
 }
 
 function ensureDir() {
@@ -38,39 +50,81 @@ export function loadConfig() {
   }
 }
 
-// Merge a patch into the config file and persist it (mode 600 — holds secrets).
-export function saveConfig(patch) {
+// --- active-account selection -----------------------------------------------
+let _account = null;
+export function setAccount(name) { _account = name || null; }
+
+export function activeAccount() {
+  if (_account) return _account;
+  const cfg = loadConfig();
+  return cfg.default || 'default';
+}
+
+export function listAccounts() {
+  const cfg = loadConfig();
+  if (cfg.accounts) return Object.keys(cfg.accounts);
+  if (cfg.client_id || cfg.refresh_token) return ['default']; // legacy flat
+  return [];
+}
+
+// Per-account stored credentials from the file (no env), or {} if none.
+function fileCredsFor(name) {
+  const cfg = loadConfig();
+  if (cfg.accounts?.[name]) return cfg.accounts[name];
+  // Legacy flat file counts as the "default" account.
+  if (!cfg.accounts && name === 'default' && (cfg.client_id || cfg.refresh_token)) {
+    return { client_id: cfg.client_id, client_secret: cfg.client_secret, refresh_token: cfg.refresh_token };
+  }
+  return {};
+}
+
+// Write credentials for a named account, migrating a legacy flat file into the
+// accounts map on first multi-account write. Sets `default` if unset.
+export function saveAccount(name, creds) {
   ensureDir();
-  const merged = { ...loadConfig(), ...patch };
+  const cfg = loadConfig();
+  if (!cfg.accounts) {
+    cfg.accounts = {};
+    if (cfg.client_id || cfg.refresh_token) {
+      cfg.accounts.default = { client_id: cfg.client_id, client_secret: cfg.client_secret, refresh_token: cfg.refresh_token };
+    }
+  }
+  delete cfg.client_id; delete cfg.client_secret; delete cfg.refresh_token;
+  cfg.accounts[name] = { ...cfg.accounts[name], ...creds };
+  if (!cfg.default) cfg.default = name;
   const path = configPath();
-  writeFileSync(path, JSON.stringify(merged, null, 2) + '\n', { mode: 0o600 });
+  writeFileSync(path, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
   if (existsSync(path)) chmodSync(path, 0o600);
-  return merged;
+  return cfg;
 }
 
-// Resolve { clientId, clientSecret, refreshToken }. `requireToken=false` skips
-// the refresh-token requirement (used by `gmail auth`, which is minting one).
+// --- credential resolution --------------------------------------------------
+// Resolve { account, clientId, clientSecret, refreshToken } for the active
+// account. `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;
+  const account = activeAccount();
+  const fc = fileCredsFor(account);
+  const clientId = process.env.GMAIL_CLI_CLIENT_ID || fc.client_id;
+  const clientSecret = process.env.GMAIL_CLI_CLIENT_SECRET || fc.client_secret;
+  const refreshToken = process.env.GMAIL_CLI_REFRESH_TOKEN || fc.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".`
+      `no OAuth client for account "${account}". Set GMAIL_CLI_CLIENT_ID / GMAIL_CLI_CLIENT_SECRET, ` +
+      `or run \`gmail auth --account ${account} --client-id … --client-secret …\`. 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".'
+      `account "${account}" is not authenticated. Run \`gmail auth --account ${account}\`, ` +
+      'or set GMAIL_CLI_REFRESH_TOKEN. See README "Authentication".'
     );
   }
-  return { clientId, clientSecret, refreshToken };
+  return { account, clientId, clientSecret, refreshToken };
 }
 
+// --- token cache ------------------------------------------------------------
 export function readTokenCache() {
   try {
     return JSON.parse(readFileSync(tokenPath(), 'utf8'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hartewired/gmail-cli",
-  "version": "1.0.0",
+  "version": "1.1.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": {