gumroad-cli

README

Gumroad CLI

CLI for the Gumroad API. Designed for humans and AI agents alike.

Install

brew install antiwork/cli/gumroad

Other installation methods

# Shell script
curl -fsSL https://gumroad.com/install-cli.sh | bash

# Go
go install github.com/antiwork/gumroad-cli/cmd/gumroad@latest

# From source (default prefix)
make install
# From source (custom prefix)
make install PREFIX="$HOME/.local"

Quick start

# Authenticate with device approval
gumroad auth login

# Or use an environment variable for CI / agents
export GUMROAD_ACCESS_TOKEN=your-token

# View your account
gumroad user

# View or set your account refund policy
gumroad refund-policy view
gumroad refund-policy set --period 30 --fine-print "Refund requests are reviewed within 2 business days."

# List products, then inspect one
gumroad products list
gumroad products view abc123

# Fetch all sales, filter with jq
gumroad sales list --all --json --jq '.sales[] | {email, formatted_total_price}'

# Show sales totals
gumroad sales summary --group-by month --from 2026-01-01 --to 2026-05-21

# Preview a refund without executing it
gumroad sales refund abc123 --amount 5.00 --dry-run

Authentication

gumroad auth login starts OAuth device authorization. It prints a Gumroad approval URL, waits while you approve in the browser, then stores the seller token locally.

gumroad auth login          # Device authorization (default)
gumroad auth login --web    # Local browser OAuth
gumroad auth login --with-token < token.txt
gumroad auth status         # Check seller auth and stored admin auth
gumroad auth token          # Print the active seller token
gumroad auth logout         # Revoke/delete stored tokens

For CI and agents with an existing token, set GUMROAD_ACCESS_TOKEN or pipe the token into gumroad auth login --with-token; GUMROAD_ACCESS_TOKEN takes precedence over stored seller config and needs no interactive login. Use --web only when you specifically want the local browser PKCE flow.

Commands

Run gumroad --help and gumroad <command> --help for subcommands, usage details, and examples.

Admin commands use a separate internal token. Run gumroad auth login --web and check the admin box to store one locally, or use GUMROAD_ADMIN_TOKEN with --non-interactive in CI and agent runs. For local testing, set GUMROAD_ADMIN_API_BASE_URL.

Refund policy

# Read the store-wide refund policy shown to buyers
gumroad refund-policy view

# Set the refund period and fine print
gumroad refund-policy set --period 30 --fine-print "Refund requests are reviewed within 2 business days."

# Clear fine print and allow no refunds
gumroad refund-policy set --period none --fine-print ""

Refund policy is account-level, not per-product. Allowed periods are none, 7, 14, 30, and 183; --fine-print is optional and capped by the API at 3000 characters.

Product categories

# Find the category path to use on create/update
gumroad products categories --search figma

# Set a product category by path
gumroad products create --name "Figma Kit" --category design/ui-and-web/figma
gumroad products update <product_id> --category design/ui-and-web/figma

Use the path from gumroad products categories with --category. The older numeric --taxonomy-id flag still works when you already have an API taxonomy ID, but it cannot be combined with --category.

File attachments

# Upload a file and print the canonical Gumroad URL
gumroad files upload ./pack.zip

# Create a product with an attached file
gumroad products create --name "Art Pack" --price 10.00 --file ./pack.zip --file-name "Art Pack.zip"

# Add a new file to a product while keeping its current attachments
gumroad products update <product_id> --file ./pack.zip

gumroad files upload prints the canonical file_url; product create/update commands accept repeatable --file flags. Run command help for metadata, removal, replacement, and per-variant Content options.

Product media

# Create a draft product, then attach cover and thumbnail images
gumroad products create --name "Art Pack" --price 10.00 --cover-image ./cover.jpg --thumbnail ./thumb.jpg

# Add preview/gallery images to an existing product
gumroad products update <product_id> --preview-image ./gallery-1.jpg --preview-image ./gallery-2.jpg

# Set a thumbnail from a public image URL
gumroad products thumbnail set <product_id> --url https://example.com/thumb.png

Product media upload supports JPEG, PNG, and GIF. Use gumroad products covers --help and gumroad products thumbnail --help for full-control resource commands.

Output modes

Flag	Output	Use case
(default)	Colored, formatted output	Human reading
--json	JSON	Programmatic access
--jq <expr>	Filtered JSON	Extract specific fields
--plain	Tab-separated, control chars escaped	Piping to grep/awk
--quiet	Minimal	Scripts

Paginated commands (sales list, payouts list, subscribers list) accept --all to fetch every page. Use --page-delay 200ms to pace large fetches.

AI agents

gumroad is built to work with AI agents. The --json, --jq, --no-input, and --non-interactive flags make it easy to query Gumroad data programmatically. Agents can start fresh seller auth with gumroad auth login and hand the printed approval URL to a human, or use GUMROAD_ACCESS_TOKEN for a no-persistence auth path when a token already exists.

An agent skill is included. Run gumroad skill to install or refresh it.

Development

make build        # Compile to ./gumroad
make test         # Run all tests
make test-cover   # Tests with per-package coverage gates (85% cmd, 90% infra)
make test-smoke   # Live read-only smoke test against real API
make lint         # golangci-lint
make man          # Generate man pages
make snapshot     # Build release snapshot via goreleaser

Live smoke test:

GUMROAD_ACCESS_TOKEN=your-token make test-smoke

License

MIT