Command reference

Run goopdl COMMAND --help for the same information in your terminal.

#Common flags

Most commands that talk to Google Play accept these:

--country only sets region headers. To get a region's actual APK variant, also route traffic through a proxy in that region with --proxy.

#download

Downloads the base APK. Add --splits for split APKs and --extras for OBB files and Play Asset Delivery packs.

goopdl download com.whatsapp                            # base APK, latest version
goopdl download com.whatsapp --splits                   # + split APKs
goopdl download com.whatsapp --splits --extras          # + OBB files and asset packs
goopdl download com.whatsapp -o ./apks                  # custom output directory
goopdl download com.whatsapp -a arm64,armv7             # one download per architecture
goopdl download com.google.android.katniss -a tv        # Android TV build
goopdl download com.whatsapp -v 231205015               # exact version code
goopdl download com.instagram.android -v 434.0.0.44.74  # exact version string
goopdl download com.whatsapp --splits -l de,fr,zh-CN    # extra language splits
goopdl download com.whatsapp --dm                       # DEX metadata for faster first launch
goopdl download com.whatsapp -c IN -p socks5://host:1080  # regional variant

Also accepts the common flags.

#Output files

{vc} is the version code. After a split download, goopdl prints an adb install-multiple command listing exactly the APK and .dm files it downloaded, quoted for your shell (PowerShell on Windows):

adb install-multiple com.whatsapp-231205015.apk com.whatsapp-231205015-config.arm64_v8a.apk

#Integrity manifest

--integrity-manifest PATH makes the download fail unless Google sends size and digest metadata for every requested base and split APK. goopdl:

1. Verifies each file against that metadata before moving it into place. It prefers SHA-256 and uses SHA-1 only when SHA-256 is missing.
2. Writes the manifest atomically: relative file name, size, algorithm, and Base64url digest for each file.

With several architectures, one manifest lists the files of all of them. Google sends no digests for OBB files and asset packs, so --extras files are downloaded unverified and left out of the manifest. The manifest never contains download URLs, cookies, headers, or tokens.

If a check fails, goopdl prints the reason and exits with code 1.

#Rate limits

Google Play sometimes answers delivery requests with HTTP 429. goopdl retries the delivery request up to twice with backoff. It does not retry file downloads. If throttling continues, it exits with code 5. Wait, or switch account, network, or dispenser.

#fast-download

Downloads the latest version using one token: a valid pooled token for the --country if one exists, otherwise a single fresh one. Unlike download, it doesn't fill the 5-token pool or try several device profiles. Use it for crawlers and other high-volume callers, where hitting the dispenser on every call gets your IP blocked.

goopdl fast-download com.whatsapp -o ./apks --splits

Also accepts --country, --proxy, and --dispenser. --proxy applies only to Google Play calls; dispenser requests rotate proxy regions on their own.

#latest

Finds the newest version available by asking Google Play through several GSF IDs and keeping the highest version code. Finding the latest version explains why one device isn't enough.

goopdl latest com.instagram.android
goopdl latest com.instagram.android --stable 5
goopdl latest com.instagram.android -s 4 -c US -p socks5://host:1080

Also accepts the common flags. --proxy applies to both dispenser and Google Play calls.

The output is a table with each probe's GSF ID prefix, version name, and version code. The highest version is highlighted and printed last.

#inspect-delivery

Asks Google Play what it would deliver for an exact version code, without downloading any APK. Use it to check that a device profile gets the ABI you want before you start a large download.

goopdl inspect-delivery com.whatsapp --arch armv7 --version 231205015 --json
goopdl inspect-delivery com.whatsapp --version 231205015 -o delivery.json

{
  "architecture": "armv7",
  "package": "com.whatsapp",
  "splits": ["base", "config.armeabi_v7a", "config.en"],
  "version": {"code": 231205015, "name": "2.23.26.15"}
}

Also accepts the common flags. The command authenticates and "purchases" the version (see how it works), but downloads nothing.

#info

Shows an app's name, version, developer, rating, download count, and Play Store URL.

goopdl info com.whatsapp
goopdl info com.whatsapp -c IN -p socks5://host:1080
goopdl info com.whatsapp --raw    # full decoded protobuf response as JSON

Also accepts the common flags.

#search

goopdl search "whatsapp"
goopdl search "file manager" --limit 5
goopdl search "whatsapp" --country IN

Also accepts the common flags.

#list-splits

Lists an app's split APKs (ABI, density, and language configs) without downloading anything.

goopdl list-splits com.whatsapp

Accepts --arch and --dispenser.

#profiles

Lists the bundled device profiles. Pass a value from the Key column to --profile in any command.

goopdl profiles              # every profile
goopdl profiles --arch arm64 # one architecture

--arch accepts arm64, armv7, x86, x86_64, tv, or all (default).

#auth

Manages credentials. Run goopdl auth alone for the list of subcommands. Authentication explains both auth modes.

#auth login

Signs in to a Google account in a browser and saves it for Google account mode. Later commands use it until you run auth logout. GOOPDL_ACCOUNT_EMAIL and GOOPDL_AAS_TOKEN take precedence over it. The AAS token goes to the system keyring, or to account.json if there is none. The last line says which.

goopdl auth login                     # isolated browser window, recommended
goopdl auth login --manual            # your usual browser, paste the oauth_token
goopdl auth login --insecure-storage  # keep the token in account.json
TOKEN=$(goopdl auth login --print)    # print the AAS token, save nothing

Getting an AAS token walks through both modes. goopdl aastoken still works as a hidden, deprecated alias of auth login --print; it accepts only --browser and --oauth (same as --manual).

#auth logout

Deletes the saved account, its token in the system keyring, every cached token, and the account-mode device records. If the keyring entry can't be removed, it warns and deletes the rest anyway. If GOOPDL_ACCOUNT_EMAIL or GOOPDL_AAS_TOKEN is still set, it warns that goopdl keeps using them. To keep the account and delete only the cache, use auth clear-cache.

goopdl auth logout

#auth clear-cache

Deletes every cached token and the account-mode device records. The saved account stays: it doesn't touch account.json or the system keyring. Use it when Google stops accepting a registered device: the next command registers a new one without signing in again. It has no flags.

goopdl auth clear-cache

#auth status

Shows the active mode (environment, saved account, or anonymous), the account email, where the saved token is (system keyring and its backend, or file), and a summary of the cache. It never prints a token. For a token in the keyring it checks that the token is there; if not, the mode reads saved account (unusable) and the reason goes to stderr. With the account variables set it doesn't open the keyring. Exits 2 if only one of the account variables is set.

goopdl auth status

#auth token

Gets an anonymous token from the dispenser and caches it. With a Google account it signs in to Google instead and caches nothing but the device registration.

goopdl auth token
goopdl auth token --arch armv7
goopdl auth token --country IN
goopdl auth token --profile "Galaxy S25 Ultra"

Also accepts the common flags.

#Exit codes

When the dispenser answers but rejects every profile, goopdl prints Authentication failed — all profiles rejected (last dispenser response: …) with the last HTTP status, or no authToken. A dispenser that is down prints … It may be down; retry later. instead.

If another goopdl process holds the token pool lock for more than 180 seconds, goopdl prints Token pool is busy (another goopdl process holds the lock); retry later. and exits with 3 from download, or 1 from latest and fast-download. Retry once the other process finishes.