pp-nylas

What this skill does

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/productivity/nylas/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/". -->

# Nylas — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `nylas-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:
   ```bash
   npx -y @mvanhorn/printing-press-library install nylas --cli-only
   ```
2. Verify: `nylas-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.3 or newer):

```bash
go install github.com/mvanhorn/printing-press-library/library/productivity/nylas/cmd/nylas-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.

## When to Use This CLI

Reach for nylas-pp-cli when you need to query Nylas data across multiple grants, run repeat 'what changed since' polls cheaply, compose SQL over messages and events, or sample the wire payload of a send before it goes out. For pure single-call API parity with the official SDK, the official nylas-cli is also a fine choice.

## Unique Capabilities

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

### Local state that compounds
- **`sync`** — Pull messages, events, threads, and contacts for one or all grants into a local SQLite mirror with per-(grant, resource) cursors so re-runs are incremental.

  _Reach for this when an agent needs to answer questions repeatedly without burning rate-limit on every call._

  ```bash
  nylas-pp-cli sync --resources messages,events --since 24h --agent
  ```
- **`since`** — Query the local mirror for resources changed in the last N (e.g. 2h, 24h) across all grants in one shot.

  _Cheapest path to 'what changed' polling without API round-trips._

  ```bash
  nylas-pp-cli since 2h --resource messages --agent --select id,subject,from,grant_id
  ```
- **`search`** — FTS5 search over messages, threads, events, and contacts spanning every connected grant in a single query (use --type to filter by resource).

  _Use this to find references anywhere across a tenant without N separate searches._

  ```bash
  nylas-pp-cli search "invoice overdue" --type messages --limit 50 --agent
  ```
- **`export`** — Stream the local mirror (or a filtered slice) to NDJSON for downstream analytics tools like DuckDB or notebooks.

  _Pipe Nylas data into duckdb or a notebook in one command._

  ```bash
  nylas-pp-cli export --resource messages --since 90d --format ndjson
  ```

### Cross-grant analytics
- **`gravity`** — Rank contacts by cross-grant interaction weight (sent + received + meeting-attended), unified by email address.

  _Surfaces 'who actually matters to this tenant' in one call for CRM hygiene or agent prioritisation._

  ```bash
  nylas-pp-cli gravity --top 25 --since 90d --agent
  ```
- **`response-time`** — Compute median and p90 first-response latency on threads where the grant-holder replied, sliced by grant or counterparty domain.

  _An SLA dashboard in one command, impossible against the live API in under five minutes of round-trips._

  ```bash
  nylas-pp-cli response-time --group-by domain --since 30d --agent
  ```

### Reliability & safety
- **`webhook-replay`** — Re-fire any past webhook delivery from the local store into a local handler URL, optionally filtered by trigger or grant.

  _Reproduce a production webhook bug in seconds without waiting for the next event to fire._

  ```bash
  nylas-pp-cli webhook-replay --since 24h --trigger message.created --to http://localhost:3000/hook
  ```
- **`grants messages send`** — Use --dry-run to print the exact wire payload for any grants messages send call; pair with --yes (or --agent) to bypass interactive confirmation only when you've reviewed the preview.

  _Every destructive action is reviewable; an agent can show the payload before sending._

  ```bash
  nylas-pp-cli grants messages send 550e8400-e29b-41d4-a716-446655440000 --to PII_EMAIL_EXAMPLE --body 'note' --dry-run
nylas-pp-cli grants messages send 550e8400-e29b-41d4-a716-446655440000 --to PII_EMAIL_EXAMPLE --body 'note' --yes
  ```
- **`grants messages send`** — Pass the global --idempotent flag so an already-existing create result is treated as a successful no-op, making the send safe to retry inside an agent loop.

  _Safe to call inside an agent retry loop._

  ```bash
  nylas-pp-cli grants messages send 550e8400-e29b-41d4-a716-446655440000 --to PII_EMAIL_EXAMPLE --body 'note' --idempotent --agent
  ```
- **`grants doctor`** — Health-check every grant: token expiry, missing scopes for advertised features, recent webhook failures, sync lag.

  _Tells you which mailboxes are quietly broken before users notice._

  ```bash
  nylas-pp-cli grants doctor --agent
  ```

### Agent-native plumbing
- **`sql`** — Read-only SQL query against the local mirror with --json output.

  _Anything we forgot to expose as a verb, an LLM can still answer through SQL._

  ```bash
  nylas-pp-cli sql "SELECT from_addr, COUNT(*) FROM messages GROUP BY 1 ORDER BY 2 DESC LIMIT 20" --agent
  ```
- **`--agent (global flag)`** — Single flag that forces --json --compact --no-input --no-color --yes defaults so any read command is LLM-safe in one switch.

  _One flag flips the entire CLI into LLM-safe mode; eliminates a class of prompt-eats-stdin bugs._

  ```bash
  nylas-pp-cli grants get-all --agent --limit 10
  ```

## Command Reference

**admin** — Manage admin

- `nylas-pp-cli admin create-api-key` — <div id='admonition-warning'>⚠️ <b>Before you can use the Manage API Keys endpoints, you need to <a...
- `nylas-pp-cli admin create-domain` — <div id='admonition-warning'>⚠️ <b>Before you can use the Manage Domains endpoints, you need a <a...
- `nylas-pp-cli admin delete-api-key` — <div id='admonition-warning'>⚠️ <b>Before you can use the Manage API Keys endpoints, you need to <a...
- `nylas-pp-cli admin delete-domain` — <div id='admonition-warning'>⚠️ <b>Before you can use the Manage Domains endpoints, you need a <a...
- `nylas-pp-cli admin get-api-key` — <div id='admonition-warning'>⚠️ <b>Before you can use the Manage API Keys endpoints, you need to <a...
- `nylas-pp-cli admin get-api-keys` — <div id='admonition-warning'>⚠️ <b>Before you can use the Manage API Keys endpoints, you need to <a...
- `nylas-pp-cli admin get-domain` — <div id='admonition-warning'>⚠️ <b>Before you can use the Manage Domains endpoints, you need a <a...
- `nylas-pp-cli admin get-domain-info` — <div id='admonition-warning'>⚠️ <b>Before you can use the Manage Domains endpoints, you need a <a...
- `nylas-pp-cli admin list-domains` — <div id='admonition-warning'>⚠️ <b>Before you can use the Manage Domains endpoints, you need a <a...
- `nylas-pp-cli admin update-domain` — <div id='admonition-warning'>⚠️ <b>Before you can use the Manage Domains endpoints, you need a <a...
- `nylas-pp-cli admin verify-domain` — <div id='admonition-warning'>⚠️ <b>Before you can use the Manage Domains endpoints, you need a <a...

**applications** — In the context of the Nylas APIs, an "application" is the object record of your Nylas application.

<div id="admonition-info">🔍 <b>The term "application" can refer to any of three concepts</b>: your Nylas application, the project you're building ("your application" or "your app"), and applications that you use to connect t