gumroad

gumroad CLI

Use gumroad (Gumroad CLI) to query and manage Gumroad data.

Agent invariants

Always follow these rules:

• Always pass --no-input to prevent interactive prompts from blocking.
• Always pass --json for programmatic access.
• Use --json --jq <expr> together to extract exactly what you need.
• For operations that can prompt for confirmation (delete, refund, workflow step adds, workflow delay changes, mutating admin actions, files abort, files complete replay, product updates that remove files, or products content set when omitted page IDs will be deleted), add --yes to skip confirmation.
• Pass --quiet to suppress spinners and status messages.
• Pass --dry-run to preview mutating requests without executing them.
• Use --page-delay 200ms with --all to avoid rate limits on large datasets.
• Prices are in whole currency units (e.g. --price 10.00 for $10), not cents. The CLI converts internally. Use --currency eur to change currency.
• Products are published immediately on create. Pass --draft to save an unpublished draft instead, then gumroad products publish <id> to make it live; gumroad products unpublish <id> takes a published product down. If the account cannot publish yet (unconfirmed email, no payout method), create still succeeds but saves a draft and prints the reason.
• Product cover and thumbnail uploads support JPEG, PNG, and GIF. WebP is not supported by the API and the CLI rejects it before upload.
• Product custom HTML landing pages use gumroad products page preview <id> ./landing.html to run the backend sanitizer without writing, gumroad products page publish <id> ./landing.html to store the page, gumroad products page clear <id> --yes to remove it, and gumroad products page url <id> to print the live URL. --dry-run only previews the CLI request body; it does not call the backend sanitizer. Inspect .sanitization_report in preview and publish JSON output for server-side changes.
• Profile custom HTML landing pages mirror the product commands without a product id and without checkout: gumroad user page preview ./landing.html, gumroad user page publish ./landing.html (read from stdin with -), gumroad user page clear --yes, and gumroad user page url (prints the public profile URL and its /landing/embed URL). A profile has no buy button, so omit data-gumroad-action="buy" and the checkout data attributes; link to products instead.
• Storefront pages (slugged pages serving at <username>.gumroad.com/<slug>) use gumroad pages list, gumroad pages create --title <title> [--slug <slug>] [path] (with an HTML path or - the page is created as custom HTML; without one it starts empty for the in-app editor), gumroad pages pull <slug> to download a page's existing custom HTML so pull → edit → push is a real round trip (writes <slug>.html; -o <path> to choose, -o - for stdout; refuses to overwrite without --force; errors with a hint when the page has no custom HTML), gumroad pages scaffold <slug> to generate starter HTML for a rich-text page or a default profile from a static snapshot of its current render (same flags as pull; pushing the scaffold converts the page to custom HTML and replaces the dynamic storefront/editor experience), gumroad pages push <slug> ./page.html to replace a page with custom HTML, and gumroad pages preview ./page.html to run the backend sanitizer without publishing. The loop for going custom: pull (or scaffold when there's no custom HTML yet) → edit → preview → push. --json/--jq on pull/scaffold still write the file and additionally print the raw API response; combining them with -o - is rejected since both would own stdout. The special slug profile targets the profile landing page (pull profile downloads your published custom HTML, scaffold profile snapshots the default storefront render when none is published; push uses the same endpoints as user page publish). Custom HTML pages require the seller's custom_html_pages feature to be enabled; without it writes fail with an access message. Writes to slugged pages (pages create/pages push <slug>) also require the token to carry the edit_profile scope — tokens minted before the CLI requested that scope get a 403 telling them to re-run gumroad auth login.
• Product rich content uses gumroad products content list <id> --json --no-input to inspect page IDs, gumroad products content get <id> --json --no-input to dump the shared rich_content page array, and gumroad products content set <id> content.json --dry-run --json --no-input to preview a whole-document replacement. Without an explicit path, whole-document set reads ./content.json; set --page reads ./page.json. Use --page <page_id> with get/set to edit one matching page object; set --page still sends a merged whole-document PUT. For a multi-page course, products content upload <id> course.json takes a manifest of {pages:[{id,title,files:[path|{path,name,description}]}]} and writes the product once per page instead of once per file, recording finished uploads and pages in a resume file (--state) so a rerun after an interruption never uploads or places anything twice. For per-variant content, pass both --variant <variant_id> and --category <cat_id>. Whole-document set deletes existing pages omitted from the JSON.
• Custom HTML pages can use data-gumroad-field="name", data-gumroad-field="price", data-gumroad-field="description", and data-gumroad-action="buy". To preselect checkout state, add data-gumroad-option="<variant name>", data-gumroad-quantity="<integer>", data-gumroad-price="<decimal>", or data-gumroad-recurrence="monthly|quarterly|biannually|yearly|every_two_years". Production validates these values and falls back to product defaults when invalid. Prefer anchors for buy CTAs so production can add a checkout href; non-anchor buy elements also post to checkout.
• Custom HTML pages cannot embed a video player from YouTube, Vimeo, or any other site. The page sandbox blocks those players, so the server removes every <iframe> and says why in .sanitization_report. A video file hosted by Gumroad still plays in a <video> tag. To show a video from another site, link to it with target="_blank" so it opens in a new tab. To show a YouTube thumbnail in that link, download https://i.ytimg.com/vi/<video-id>/hqdefault.jpg, upload it with gumroad media upload, and use the returned .media.url in an <img> inside the link.
• Audience emails are created as drafts by default. Use gumroad emails send-preview <id> --json --no-input and inspect .preview_url before gumroad emails send <id> --yes --json --no-input. Creating with --send publishes and blasts immediately, so use --dry-run first and require explicit human approval. To schedule a send instead of blasting immediately, create the draft then gumroad emails schedule <id> --at "<RFC3339>" --json --no-input; gumroad emails unschedule <id> returns a scheduled email to draft.
• Workflow email writes do not change the workflow publication state. Adding a step to a published workflow can schedule eligible past recipients. Changing a delay can reschedule recipients. Use --dry-run before each write.
• If a command fails with a seller auth error, run gumroad auth status --json --no-input first. Agents can start seller auth with gumroad auth login --no-input and hand the printed approval URL to a human, or use an existing seller token via GUMROAD_ACCESS_TOKEN or gumroad auth login --with-token.
• For admin commands in agents/CI, pass --non-interactive and set GUMROAD_ADMIN_TOKEN; interactive shells can store an admin token with gumroad auth login --web.