Pp Gmail

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/productivity/gmail/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

Gmail — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the gmail-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to $HOME/.local/bin on macOS/Linux and %LOCALAPPDATA%\Programs\PrintingPress\bin on Windows:

   npx -y @mvanhorn/printing-press-library install gmail --cli-only

2. Verify: gmail-pp-cli --version
3. Ensure the reported install directory is on $PATH for the agent/runtime that will invoke this skill.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.5 or newer). This installs into $GOPATH/bin (default $HOME/go/bin), so add that directory to $PATH instead:

go install github.com/mvanhorn/printing-press-library/library/productivity/gmail/cmd/gmail-pp-cli@latest

If --version reports "command not found" after install, the runtime cannot see the binary directory on $PATH. Do not proceed with skill commands until verification succeeds.

Every read and cleanup surface from the Gmail tool landscape, multi-account, with a local SQLite store underneath: sender intelligence, all-category digests, bulk trash/label with preview-confirm-undo, RFC 8058 one-click unsubscribes with a compliance ledger. Send, drafts, settings, and permanent deletion are absent from the binary by construction — Trash is the ceiling.

When to Use This CLI

Reach for this CLI when an agent or operator needs to understand or clean a Gmail mailbox safely: summaries across every category, sender and storage intelligence, bulk trash/label with preview and undo, and one-click unsubscribes with follow-up verification. It is the wrong tool for composing or sending anything — by design it cannot.

Do NOT use this CLI for:

• Composing, sending, replying, forwarding, or drafting email — no send or draft surface exists in the binary.
• Permanently deleting messages or emptying Trash — Trash is the ceiling; the gmail.modify scope cannot permanently delete.
• Deleting labels — labels create and labels rename are the only label writes; there is no labels delete, update, or patch.
• Managing Gmail settings, filters, forwarding, or vacation responders — settings endpoints do not exist in this binary.
• Thread-level mutations — threads are read-only; mutations operate on messages through the cleanup engine.
• Sending mailto: unsubscribes — unsub run executes RFC 8058 one-click HTTPS POSTs only; mailto-only senders are surfaced as a desk list, never acted on.

Unique Capabilities

These capabilities aren't available in any other tool for this API.

Cleanup that compounds

• unsub verify — See which senders kept mailing you after a one-click unsubscribe, with an escalation query per violator.

  After running unsubscribes, this is the only way to learn which ones actually stuck before escalating to block/filter decisions.

  gmail-pp-cli unsub verify --account ads --agent

• rules run — Named local recipes (query plus trash or label action) replayed through the preview-confirm-undo engine as one merged plan.

  Standing hygiene (old promos to trash, receipts to their folder) becomes one command a scheduled job can run daily, always previewed before applying.

  gmail-pp-cli rules run --plan-only --agent

• sort suggest — Senders whose mail you already label consistently, with a generated plan to label the rest the same way.

  Folder-sorting at scale without guessing: the plan only proposes what the operator's own labeling history already proves.

  gmail-pp-cli sort suggest --account personal --min-confidence 0.8 --agent

Local state that answers instantly

• delta — Everything new since your last check: new messages per category and sender, never-seen senders, volume spikes.

  The first question of any recurring mailbox check is what changed — this answers it without re-reporting what the operator already saw.

  gmail-pp-cli delta --account personal --agent

• storage report — Which senders, labels, years, and attachments own your storage, with ready-to-run cleanup queries per row.

  Turns a vague quota number into a ranked hit-list whose rows paste straight into cleanup plan.

  gmail-pp-cli storage report --account ads --top 15 --agent

Safety made visible

• trash report — What you trashed, grouped by applied plan, with days remaining before Gmail's 30-day purge makes undo impossible.

  The last regret-check: surfaces batches whose undo window is closing so recovery happens while it still can.

  gmail-pp-cli trash report --closing-soon --agent

• score — Per-account hygiene metrics — unread share, promo share, subscription count, storage headroom — snapshotted over time.

  Shows whether the cleanup campaign is actually winning — Promotions down 60% since baseline beats a feeling.

  gmail-pp-cli score --account ads --agent

Command Reference

Raw modify/trash/delete subcommands do not exist. Every mailbox mutation flows through cleanup plan → cleanup apply (reversible via undo), labels create/labels rename, or unsub plan → unsub run — all gated by one-time plan tokens. One-click POSTs additionally require the unsubscribe URL host to share the sender's registrable domain: ESP-hosted (third-party) destinations are listed by unsub plan under third_party_hosts and are skipped by unsub run unless it is invoked with --allow-third-party.

Mailbox engine

• gmail-pp-cli accounts / accounts auth — List gauth profiles and token status; run the browser OAuth flow for one profile (or --all).
• gmail-pp-cli sync — Sync message metadata into the local store (full or historyId-incremental); never mutates the mailbox.
• gmail-pp-cli digest — Per-category mailbox summary plus an account rollup.
• gmail-pp-cli senders — Rank senders by volume, with size, unread rate, and unsubscribe capability.
• gmail-pp-cli delta / storage report / trash report / score / sort suggest — The local-intelligence reports described under Unique Capabilities.
• gmail-pp-cli cleanup plan|apply|recover — Preview-confirm-undo cleanup: plan freezes what would change (mailbox untouched), apply executes exactly that, recover finishes a crashed apply.
• gmail-pp-cli undo --ledger <id> — Reverse a ledgered apply delta-by-delta; changed ids are skipped as conflicts, never forced.
• gmail-pp-cli rules add|list|rm|run — Named local cleanup recipes replayed through the engine as one merged plan; run always stops at the plan.
• gmail-pp-cli unsub audit|plan|run|verify — One-click unsubscribe engine: classify, freeze, POST (RFC 8058, hardened), verify.
• gmail-pp-cli search / analytics / tail / workflow archive|status / api — Local FTS search and analytics, polling change stream, archive workflows, endpoint browsing.

API reads (plus the two safe label writes) — <userId> accepts me

• gmail-pp-cli history <userId> — Lists the history of all changes to the given mailbox.
• gmail-pp-cli labels list|get — Read labels.
• gmail-pp-cli labels create — Create a label, idempotently by name (an existing case-insensitive match is returned, not duplicated).
• gmail-pp-cli labels rename — Rename a label by id, ledgering the inverse for undo --ledger <id>. No labels delete, update, or patch exists.
• gmail-pp-cli messages list|get / messages attachments get — Read messages and attachments (reads only).
• gmail-pp-cli threads list|get — Read threads (thread mutations do not exist).
• gmail-pp-cli users-profile <userId> — Gets the current user's Gmail profile.

Finding the right command

When you know what you want to do but not which command does it, ask the CLI directly:

gmail-pp-cli which "<capability in your own words>"

which resolves a natural-language capability query to the best matching command from this CLI's curated feature index. Exit code 0 means at least one match; exit code 2 means no confident match — fall back to --help or use a narrower query.

Recipes

Morning mailbox delta

gmail-pp-cli delta --account ads --agent

What arrived since the last check, grouped by category and sender, without re-reporting what was already seen.

Top senders, narrowed for an agent

gmail-pp-cli senders --account personal --top 25 --agent --select senders.email,senders.count,senders.unread_rate

Dotted --select keeps the payload to the three fields a triage decision needs.

Unsubscribe audit before acting

gmail-pp-cli unsub audit --account ads --min-count 5 --agent

Ranks subscription senders by volume and classifies each as one-click (actionable) or mailto-only (desk list).

Preview a year-old promotions purge

gmail-pp-cli cleanup plan --q "category:promotions older_than:1y" --action trash --account personal --agent

Counts and samples first; the printed plan token is required by cleanup apply, and every apply is undoable.

Verify last week's unsubscribes stuck

gmail-pp-cli unsub verify --account ads --since 7d --agent

Joins the unsubscribe ledger to fresh arrivals — violators come back with an escalation query.

Auth Setup

Installed-app OAuth with named multi-account profiles (per-profile token store, consented-account verification). The only scope ever requested is gmail.modify; send/draft/settings endpoints do not exist in this binary, and permanent deletion is impossible under this scope — Google enforces the Trash ceiling, not us.

Run gmail-pp-cli doctor to verify setup.

Agent Mode

Add --agent to any command. Expands to: --json --compact --no-input --no-color --yes.

• Pipeable — JSON on stdout, errors on stderr

• Filterable — --select keeps a subset of fields. Dotted paths descend into nested structures; arrays traverse element-wise. Critical for keeping context small on verbose APIs:

  gmail-pp-cli labels list me --agent --select id,name

• Previewable — --dry-run shows the request without sending

• Offline-friendly — sync/search commands can use the local SQLite store when available

• Non-interactive — never prompts, every input is a flag

• Explicit retries — use --idempotent only when an already-existing create should count as success (labels create already matches by name)

Response envelope

Commands that read from the local store or the API wrap output in a provenance envelope:

{
  "meta": {"source": "live" | "local", "synced_at": "...", "reason": "..."},
  "results": <data>
}

Parse .results for data and .meta.source to know whether it's live or local. A human-readable N results (live) summary is printed to stderr only when stdout is a terminal AND no machine-format flag (--json, --csv, --compact, --quiet, --plain, --select) is set — piped/agent consumers and explicit-format runs get pure JSON on stdout.

Paths and state

Agents should treat the CLI's path resolver as part of the runtime contract:

• Use --home <dir> for one invocation, or set GMAIL_HOME=<dir> to relocate all four path kinds under one root.

• Use per-kind env vars only when a specific kind must diverge: GMAIL_CONFIG_DIR, GMAIL_DATA_DIR, GMAIL_STATE_DIR, GMAIL_CACHE_DIR.

• Resolution order is per-kind env var, --home, GMAIL_HOME, XDG (XDG_CONFIG_HOME, XDG_DATA_HOME, XDG_STATE_HOME, XDG_CACHE_HOME), then platform defaults.

• config contains settings like config.toml and profiles. data contains credentials.toml, data.db, cookies, and auth sidecars. state contains persisted queries, jobs, and teach.log. cache contains regenerable HTTP/cache files.

• Stored secrets live in credentials.toml under the data dir. Existing legacy config.toml secrets are read for compatibility and leave config.toml on the first auth write.

• Run gmail-pp-cli doctor --fail-on warn to surface path and credential-location warnings. agent-context exposes a schema v4 paths block for agents that need the resolved dirs.

• For MCP, pass relocation through the MCP host config. The MCP binary does not inherit CLI flags:

  {
    "mcpServers": {
      "gmail": {
        "command": "gmail-pp-mcp",
        "env": {
          "GMAIL_HOME": "/srv/gmail"
        }
      }
    }
  }

Fleet precedence: an inherited per-kind env var overrides an explicit --home for that kind. Use GMAIL_HOME or per-kind vars as durable fleet levers, and use --home only for a single invocation. Relocation is not reversible by unsetting env vars; move files manually before clearing GMAIL_HOME, or doctor will not find credentials left under the former root.

Automatic learning

This CLI ships a self-capturing learning loop. The CLI does its own bookkeeping: every invocation is journaled locally, a failed flag followed by a corrected retry auto-derives a flag_alias candidate, and a teach on a query family without a playbook auto-synthesizes a playbook_candidate from the session's journal. Your job is judgment only: recall first, act on surfaced candidates, teach the final answer, playbook amend when you observe a correction. You never record failures by hand.

Step 1: recall before any discovery

Before list/search/drill commands on a new user question, run:

gmail-pp-cli recall "<user's question>" --agent

The response envelope:

{
  "query": "...",
  "normalized": "<normalized form>",
  "query_entities": ["..."],
  "found": true | false,
  "match_score": 0.0,
  "results": [
    { "resource_id": "...", "resource_type": "...", "venue": "...",
      "confidence": 2, "entity_match": "exact|partial|unknown",
      "source": "taught|preseed|pattern", "warnings": ["..."] }
  ],
  "mismatches": [ /* only when --debug-mismatches */ ],
  "warnings": [ /* top-level */ ],
  "candidates": [
    { "id": 12, "class": "flag_alias | playbook_candidate",
      "summary": "...", "sightings": 3, "last_seen": "...",
      "rationale": "...",
      "next_action": ["<trial command>", "gmail-pp-cli learnings confirm 12"] }
  ],
  "playbook": {
    "query_family": "...",
    "playbook": {
      "steps": [ { "cmd": "<command with {slot} substitution>", "purpose": "..." } ],
      "entity_slots": ["$ENTITY"],
      "expected_tool_calls": 3
    },
    "slots_resolved": { "$ENTITY": { "token": "<live token>", "canonical": "<canonical>" } },
    "notes": "<workarounds + gotchas for this query family>"
  },
  "notes": "<duplicate surface for non-playbook callers>"
}

Empty-store short-circuit: if the store has no learnings, playbooks, or candidates yet (recall finds nothing and learnings list and learnings candidates are both empty), skip recall for the rest of this session instead of taxing every query; resume recall-first once something has been taught.

Step 2: decision tree

Read candidates, playbook, notes, results[0], and warnings in that order:

if Candidates present (warnings include "candidates_present"):
    -> candidates are try-then-confirm, never facts. Follow each candidate's
       two-step next_action verbatim: run the trial command first, then run
       `learnings confirm <id>` only after the trial verified the behavior.
       Reject a wrong candidate with `learnings reject <id>`.
    -> NEVER re-teach something recall surfaced as a candidate; confirm or
       reject that candidate instead of teaching a duplicate.
    -> candidates ride alongside playbooks and resource hits, not instead of
       them; continue with the branches below after acting on them.

if Playbook present:
    -> READ Playbook.notes verbatim FIRST (workarounds + gotchas the CLI surface doesn't expose)
    -> replay Playbook.steps in order, substituting Playbook.slots_resolved entries
       for the entity slot tokens. If a step's slot is unresolved, fall back to
       discovery for that step only.
    -> the Playbook's expected_tool_calls is a budget; if you find yourself running
       materially more, record the divergence via `gmail-pp-cli playbook amend`
       at end-of-session.

elif Notes present (no Playbook):
    -> read Notes verbatim before any discovery step; they carry known gotchas
       for this query family even when no structured choreography exists yet.

elif Found AND Results[0].EntityMatch == "exact" AND Results[0].Confidence >= 2:
    -> skip discovery; fetch live data for Results[*].ResourceID in parallel

elif Found AND Results[0].EntityMatch == "partial":
    -> candidate hint, NOT a hit; read the resource title to validate before trusting

elif (any row in Mismatches[] when --debug-mismatches was passed):
    -> treat as cold start; the stored learning is for a different entity
       (different canonical resolved from query_entities)

else:  // Found == false, no playbook, no notes
    -> cold start; run discovery normally; teach the answer afterward (Step 4).
       If the family has no playbook yet, that teach auto-synthesizes a
       playbook candidate from this session's journal - you do not need to
       record one by hand.

Playbook and Notes are orthogonal to the per-resource path. A recall response can carry both a Playbook AND a Results[] hit - use both: the Playbook tells you which choreography to run; the resource hits short-circuit specific steps. Default to skipping mismatches; pass --debug-mismatches only when investigating cold-start surprises.

Candidate judgment details: learnings confirm <id> prints the candidate's full payload before materializing it - check that the printed payload matches the behavior you verified. learnings reject <id> tombstones the derivation signature so the same candidate does not resurface. The envelope carries only the few candidates worth acting on now; gmail-pp-cli learnings candidates lists the full open set.

Graceful degradation: if learnings confirm is an unknown command, you are driving an older binary - ignore the candidates guidance and follow the rest of the protocol.