Gumroad's seller API as an agent-ready CLI and MCP server.
This tool wraps Gumroad's documented OAuth API for products, files, covers, variants, offer codes, custom fields, resource subscriptions, sales, subscribers, licenses, payouts, tax forms, and earnings. It also adds the Printing Press local sync/search/analytics layer so agents can answer seller questions from a consistent local snapshot instead of repeatedly walking paginated endpoints.
Printed by @bheemreddy181 (Bheem Reddy).
Authentication
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.
Quick Start
# Confirm the token is present and the API is reachable.
gumroad-pp-cli doctor
# List products in agent-friendly JSON.
gumroad-pp-cli products list --agent
# Sync seller data for local search and analytics.
gumroad-pp-cli sync --resources products,sales,subscribers,payouts --latest-only --json
Unique Features
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.
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.
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.
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.
gumroad-pp-cli tail --resource sales --interval 30s --json
Usage
Run gumroad-pp-cli --help for the full command reference and flag list.
Commands
earnings
Manage earnings
gumroad-pp-cli earnings get - 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 get - Retrieve details of a subscriber. Requires view_sales scope.
tax-forms
Manage tax forms
gumroad-pp-cli tax-forms list - Retrieve 1099 tax forms for the authenticated user. Requires view_tax_data scope.
user
Manage user
gumroad-pp-cli user get - Retrieve the authenticated user's data.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
gumroad-pp-cli earnings --year 42
# JSON for scripting and agents
gumroad-pp-cli earnings --year 42 --json
# Filter to specific fields
gumroad-pp-cli earnings --year 42 --json --select id,name,status
# Dry run — show the request without sending
gumroad-pp-cli earnings --year 42 --dry-run
# Agent mode — JSON + compact + no prompts in one flag
gumroad-pp-cli earnings --year 42 --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Explicit retries - add
--idempotent to create retries and --ignore-missing to delete retries when a no-op success is acceptable
- Confirmable -
--yes for explicit confirmation of destructive actions
- Piped input - write commands can accept structured input when their help lists
--stdin
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
gumroad-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/gumroad-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
GUMROAD_ACCESS_TOKEN | per_call | Yes | Set to your API credential. |
Troubleshooting
Authentication errors (exit code 4)
- Run
gumroad-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $GUMROAD_ACCESS_TOKEN
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
API-specific
- Gumroad returns a scope error. — Re-authorize the OAuth application with the endpoint scope shown in the command help, such as view_sales, edit_sales, edit_products, view_payouts, or view_tax_data.
- File upload completion fails after a retry. — Start a new /files/presign flow; Gumroad upload IDs are one-use after /files/complete.
Sources & Inspiration
This CLI was built by studying these projects and resources:
Generated by CLI Printing Press