pp-superhuman

What this skill does

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

# Superhuman — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `superhuman-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 superhuman --cli-only
   ```
2. Verify: `superhuman-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/superhuman/cmd/superhuman-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

Pick the Superhuman CLI when you want email read/draft/respond access from a terminal or Claude Code, scriptable thread search backed by a local store, capability discovery via `which`, or Ask AI semantic search piped into other tools.

## Unique Capabilities

These capabilities aren't available in any other tool for this API.
- **`workflow`** — Compound commands that combine multiple API operations into one verb (see `workflow --help`).

  ```bash
  superhuman-pp-cli workflow --help
  ```
- **`which`** — Resolve a natural-language capability query to the best matching command from this CLI's curated feature index.

  ```bash
  superhuman-pp-cli which 'snooze a thread for tomorrow'
  ```
- **`lookup`** — Live contact enrichment for an email: name, bio, location, timezone, avatar, social links, and Twitter handle from Superhuman's profile service. Optional `--photo` downloads the contact's avatar.

  ```bash
  superhuman-pp-cli lookup [email protected] --agent --select name,location,twitterHandle
  ```
- **`userdata write`** — Low-level escape hatch over Superhuman's CRDT mutation endpoint for paths the typed commands don't cover. Dry-run by default; `--apply` to fire; path must start with `users/`.

  ```bash
  superhuman-pp-cli userdata write "users/<google-id>/settings/<key>" '{"value":true}' --apply
  ```

## Command Reference

**ai** — Semantic search via Ask AI

- `superhuman-pp-cli ai` — Ask AI semantic search (SSE stream)

**attachments** — Upload, list, download attachments

- `superhuman-pp-cli attachments` — Upload an attachment for a draft

**drafts** — Drafts — create, update, send, delete

- `superhuman-pp-cli drafts list` — List drafts
- `superhuman-pp-cli drafts new` — Create a fresh outbound draft with generated IDs
- `superhuman-pp-cli drafts write` — Create or update a draft (write to draft path)

**messages** — Individual messages within threads

- `superhuman-pp-cli messages get` — Fetch one message by id
- `superhuman-pp-cli messages get-by-rfc822` — Lookup a message by RFC822 Message-ID
- `superhuman-pp-cli messages list` — List messages with Gmail search syntax
- `superhuman-pp-cli messages query` — Semantic email search

**lookup** — Live contact enrichment for an email address

- `superhuman-pp-cli lookup <email>` — Fetch live profile (name, bio, location, timezone, avatar, links, Twitter handle); `--photo <path>` also downloads the photo

**participants** — Local correspondent analytics

- `superhuman-pp-cli participants list` — List email participants from the local store
- `superhuman-pp-cli participants show <email>` — Show participant details

**reminders** — Snooze reminders for threads

- `superhuman-pp-cli reminders cancel` — Cancel a snooze (un-snooze a thread)
- `superhuman-pp-cli reminders create` — Create a snooze reminder for a thread

**teams** — Team and account info

- `superhuman-pp-cli teams` — List teams the user belongs to

**threads** — Email threads — read, list, search, archive, label

- `superhuman-pp-cli threads get` — Get a thread by ID
- `superhuman-pp-cli threads list` — List recent threads

**send** — Send, schedule, and remind from one command

- `superhuman-pp-cli send` — Send a real email through Superhuman's backend

**snippets** — Reusable Superhuman UI snippets

- `superhuman-pp-cli snippets list` — List saved snippets
- `superhuman-pp-cli snippets get <name>` — Show a snippet
- `superhuman-pp-cli snippets create --name <name>` — Create a snippet
- `superhuman-pp-cli snippets update <name>` — Update a snippet
- `superhuman-pp-cli snippets delete <name>` — Delete a snippet

**awaiting-reply** — Threads that need attention

- `superhuman-pp-cli awaiting-reply` — List threads where the latest message awaits your reply

**watch** — Gmail history stream

- `superhuman-pp-cli watch` — Emit Gmail history deltas as NDJSON

**users** — User account state

- `superhuman-pp-cli users` — User achievements / gamification state

**userdata** — Low-level Superhuman CRDT surface (advanced)

- `superhuman-pp-cli userdata write <path> <json>` — Write a raw value to a CRDT path; dry-run by default, `--apply` to fire, path must start with `users/`


### Finding the right command

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

```bash
superhuman-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


### Fast triage view across recent threads

```bash
superhuman-pp-cli threads list --limit 100 --json --select id,subject,snippet,participants
```

Pull a wide swath of recent threads with only the fields you need; pipe to jq or an LLM for further triage.

### Folder views and thread filters

```bash
superhuman-pp-cli threads list --type sent --limit 20 --json
superhuman-pp-cli threads list --type starred --label IMPORTANT --json
superhuman-pp-cli threads list --participants-file participants.txt --intersect-with-stdin < thread-ids.txt --json
```

Use `--type` for common mailbox folders: `inbox`, `sent`, `done`, `starred`, `archived`, `spam`, `trash`, and `important`. Add `--label`, `--participants-file`, or `--intersect-with-stdin` when composing local-store filters.

### Draft from stdin and send with an undo window

```bash
echo 'Body text here' | superhuman-pp-cli send --to [email protected] --subject 'Update' --body-stdin --undo 30s
```

Write a draft from a piped body, then send it with a 30s undo window: agents can abort before the send fires.

### Create a fresh draft without hand-building IDs

```bash
superhuman-pp-cli drafts new --to [email protected] --subject 'Update' --body-stdin < body.txt --json
```

`drafts new` creates a fresh outbound draft and generates the Superhuman-style draft, thread, and RFC822 identifiers.

### Snooze a thread for later

```bash
superhuman-pp-cli reminders create --thread-id <thread-id> --trigger-at 2026-05-13T09:00:00Z
```

Schedule a thread to resurface at a specific time; pair with `reminders cancel` to un-snooze.

### Send with follow-up reminders and scheduled delivery

```bash
superhuman-pp-cli send --to [email protected] --subject 'Proposal' --body-file proposal.txt --remind-in 3d --if-no-reply
superhuman-pp-cli send --to [email protected] --subject 'Tomorrow' --body 'See you then' --schedule-at '+1d'
superhuman-pp-cli send