pp-gumroad

What this skill does

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

# Gumroad — Printing Press CLI

## Prerequisites: Install the CLI

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

Use this skill when the user asks to inspect or operate a Gumroad seller account, especially products, sales, subscribers, payouts, licenses, offer codes, or tax data. Prefer sync/search/analytics for broad questions and direct endpoint commands for a specific object or mutation.

## Unique Capabilities

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

### Local seller intelligence

- **`sync --resources products,sales,subscribers,payouts --latest-only --json`** — Refresh a local SQLite snapshot of the seller-facing Gumroad resources that agents inspect most often.

  _Use this before research or reporting tasks so later searches and analytics are grounded in one consistent seller snapshot._

  ```bash
  gumroad-pp-cli sync --resources products,sales,subscribers,payouts --latest-only --json
  ```
- **`search`** — Search locally synced products, sales, subscribers, payouts, and tax records through one command.

  _Use this when the user remembers a buyer, product, license, or payout clue but not the exact Gumroad object ID._

  ```bash
  gumroad-pp-cli search "annual plan" --data-source local --json --limit 20
  ```
- **`analytics`** — Group and count synced Gumroad records locally for fast summaries without additional API traffic.

  _Use this for lightweight revenue, subscriber, product, and payout triage after a sync._

  ```bash
  gumroad-pp-cli analytics --type sales --group-by product_id --limit 10 --json
  ```

### Operational monitoring

- **`tail`** — Poll selected Gumroad resources and emit NDJSON changes for scripts or agent monitors.

  _Use this for one-off checks after a launch, refund, payout, or product update._

  ```bash
  gumroad-pp-cli tail --resource sales --interval 30s --json
  ```

## Command Reference

**earnings** — Manage earnings

- `gumroad-pp-cli earnings` — Retrieve an annual earnings breakdown for the authenticated user. Requires view_tax_data scope.

**files** — Manage files

- `gumroad-pp-cli files abort` — Cancel a multipart upload started by /files/presign. Requires edit_products scope.
- `gumroad-pp-cli files complete` — Finalize a multipart upload started by /files/presign. Requires edit_products scope.
- `gumroad-pp-cli files presign` — Start a multipart upload and return presigned URLs for each part. Requires edit_products scope.

**licenses** — Manage licenses

- `gumroad-pp-cli licenses decrement-uses-count` — Decrement the uses count of a license. Requires edit_products scope.
- `gumroad-pp-cli licenses disable` — Disable a license. Requires edit_products scope.
- `gumroad-pp-cli licenses enable` — Enable a license. Requires edit_products scope.
- `gumroad-pp-cli licenses rotate` — Rotate a license key. The old key will no longer be valid. Requires edit_products scope.
- `gumroad-pp-cli licenses verify` — Verify a license key.

**payouts** — Manage payouts

- `gumroad-pp-cli payouts get` — Retrieve details of a payout. Requires view_payouts scope.
- `gumroad-pp-cli payouts get-upcoming` — Retrieve upcoming payouts. Requires view_payouts scope.
- `gumroad-pp-cli payouts list` — Retrieve payouts for the authenticated user. Requires view_payouts scope.

**products** — Manage products

- `gumroad-pp-cli products create` — Create a new product as a draft. Requires edit_products or account scope.
- `gumroad-pp-cli products delete` — Permanently delete a product.
- `gumroad-pp-cli products get` — Retrieve details of a product.
- `gumroad-pp-cli products list` — Retrieve all existing products for the authenticated user.
- `gumroad-pp-cli products update` — Update an existing product. Collection fields such as files, tags, and rich_content replace the full collection.

**resource-subscriptions** — Manage resource subscriptions

- `gumroad-pp-cli resource-subscriptions create` — Subscribe to a resource webhook. Requires view_sales scope.
- `gumroad-pp-cli resource-subscriptions delete` — Unsubscribe from a resource.
- `gumroad-pp-cli resource-subscriptions list` — Show active subscriptions for the input resource. Requires view_sales scope.

**sales** — Manage sales

- `gumroad-pp-cli sales get` — Retrieve details of a sale. Requires view_sales scope.
- `gumroad-pp-cli sales list` — Retrieve successful sales by the authenticated user. Requires view_sales scope.

**subscribers** — Manage subscribers

- `gumroad-pp-cli subscribers <id>` — Retrieve details of a subscriber. Requires view_sales scope.

**tax-forms** — Manage tax forms

- `gumroad-pp-cli tax-forms` — Retrieve 1099 tax forms for the authenticated user. Requires view_tax_data scope.

**user** — Manage user

- `gumroad-pp-cli user` — Retrieve the authenticated user's data.


### Finding the right command

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

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


### List live products

```bash
gumroad-pp-cli products list --agent
```

Returns compact JSON for the authenticated seller's products.

### Find a buyer or license locally

```bash
gumroad-pp-cli search "customer query" --data-source local --json
```

Searches previously synced seller data without making additional API calls.

### Review payout history

```bash
gumroad-pp-cli payouts list --after 2026-01-01 --agent
```

Reads payout records with pagination metadata when the token has view_payouts scope.

## Auth Setup

Create a Gumroad OAuth application, authorize it with the scopes needed for your workflow, and provide the resulting access token as GUMROAD_ACCESS_TOKEN. The MCP bundle exposes this as a sensitive user configuration value.

Run `gumroad-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:

  ```bash
  gumroad-pp-cli earnings --year 42 --agent --select id,name,status
  ```
- **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
- **