gumroad-cli

README

Gumroad CLI

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

Install

brew install antiwork/cli/gumroad

If you previously installed the cask, switch once with:

brew uninstall --cask antiwork/cli/gumroad
brew install antiwork/cli/gumroad

Other installation methods

Shell script (macOS, Linux, Windows via Git Bash):

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

Go:

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

From source with man pages and completions:

make install

# Or install into a custom prefix
make install PREFIX="$HOME/.local"

Under the selected PREFIX, make install places the binary in bin/, man pages in share/man/man1/, and shell completions under share/.

Quick start

# Authenticate (opens browser for OAuth)
gumroad auth login

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

# View your account
gumroad user

# 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}'

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

Authentication

gumroad auth login opens your browser for OAuth authorization. After you approve, the CLI stores the seller token locally. Team members can also check the admin box in the same browser approval; that stores a separate admin token in admin.token.

gumroad auth login          # Browser-based OAuth (default)
gumroad auth login --web    # Force browser OAuth, no fallback
gumroad auth status         # Check seller auth and stored admin auth
gumroad auth logout         # Revoke/delete stored tokens

When a browser isn't available (SSH, containers), the CLI falls back to a manual flow: it prints the authorize URL and you paste the redirect URL back.

For CI and agents, set GUMROAD_ACCESS_TOKEN instead — it takes precedence over stored seller config and needs no interactive login. Piped stdin also works: echo $TOKEN | gumroad auth login.

Commands

gumroad auth          login, status, logout
gumroad admin         Internal admin API commands
gumroad user          View your account info
gumroad products      create, update, list, view, delete, publish, unpublish, skus
gumroad sales         list, view, refund, ship, resend-receipt
gumroad payouts       list, view, upcoming
gumroad subscribers   list, view
gumroad licenses      verify, enable, disable, decrement, rotate
gumroad offer-codes   list, view, create, update, delete
gumroad variant-categories list, view, create, update, delete
gumroad variants      list, view, create, update, delete
gumroad custom-fields list, create, update, delete
gumroad files         upload, complete, abort
gumroad webhooks      list, create, delete
gumroad skill         Install or refresh the Claude Code skill
gumroad completion    bash, zsh, fish, powershell

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

Admin commands use a separate internal token. Run gumroad auth login and check the admin box to store one locally. Mutating admin commands use that stored token in normal interactive runs so the acting admin can be shown before the request; CI and agents can pass --non-interactive with GUMROAD_ADMIN_TOKEN. For local testing, set GUMROAD_ADMIN_API_BASE_URL.

gumroad admin users info --email seller@example.com --json
gumroad admin users watch --user-id 2245593582708 --expected-email seller@example.com --revenue-threshold 200 --note "Review next buyers"
gumroad admin users update-watch --user-id 2245593582708 --expected-email seller@example.com --revenue-threshold 500
gumroad admin users unwatch --user-id 2245593582708 --expected-email seller@example.com

File attachments

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

# Recover an upload after a state-unknown complete failure
gumroad files upload ./pack.zip --json > err.json
jq '.error.recovery' err.json | gumroad files complete --recovery - --yes

# Abort an orphaned multipart upload from saved recovery fields
gumroad files abort --upload-id up-123 --key attachments/u/k/original/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

# Replace the current file set, preserving only the IDs you keep explicitly
gumroad products update <product_id> --replace-files --keep-file <file_id> --file ./new-pack.zip

gumroad files upload and gumroad files complete both print the canonical file_url. Product create/update accept repeatable --file flags, with matching --file-name and --file-description values when you need custom attachment metadata. gumroad products update also supports --remove-file, and --replace-files with --keep-file, when you need to remove existing attachments.

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, and GUMROAD_ACCESS_TOKEN gives agents a no-persistence seller auth path.

A Claude Code 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