gplay recovery (incident response for a bad release)

gplay recovery manages app recovery actions, Google's targeted incident-response remediation. When a shipped versionCode turns out to be bad, a recovery force-updates the impacted users to a safe version via a remote in-app update. Shared conventions (auth, output, exit codes, --dry-run/--confirm, --package pinning) are in gplay-cli-usage. The whole namespace is [experimental].

Two structural facts to hold onto:

• Keyed by package + versionCode, and it lives outside the Edit model

(no editId), a recovery has its own appRecoveryId and a draft → active → canceled lifecycle.

• --version-code is the bad version, the one users are stuck on that you

want them off.

The lifecycle, in order

bash
# 1. Stage a DRAFT (harmless, nothing is pushed yet, so no --confirm):
gplay recovery create --version-code 431 --all-users
gplay recovery create --version-code 431 --regions US,FR      # or scope it
gplay recovery create --version-code 431 --sdk-levels 30,31

# 2. Inspect the recoveries on that versionCode (find the appRecoveryId):
gplay recovery list --version-code 431

# 3. Activate; this force-updates impacted users. Production-impacting:
gplay recovery deploy <appRecoveryId> --confirm

# 4a. Widen the audience later (append-only, see below):
gplay recovery add-targeting <appRecoveryId> --regions DE,ES --confirm

# 4b. …or stop it (irreversible):
gplay recovery cancel <appRecoveryId> --confirm

create: a harmless draft

create stages a draft; nothing reaches a user until deploy. Because a draft is harmless it needs no --confirm (use --dry-run to validate inputs with no HTTP call). It requires --version-code and at least one audience selector: --all-users, --regions <CC,CC> (CLDR codes), or --sdk-levels <N,N>. The recovery type defaults to a remote in-app update (--remote-in-app-update, the only type Play models today).

deploy / cancel: the gated writes

• deploy <id> activates the draft, the production-impacting step that

force-pushes users off the bad build. Requires --confirm (missing → exit 3); rehearse with --dry-run.

• cancel <id> stops the action: it persists with status CANCELED and

cannot be resumed; this is irreversible. Requires --confirm. To target users again after a cancel you must create a new recovery.

• GPLAY_READONLY refuses both (exit 4).

add-targeting is append-only: it can only widen

The audience of a recovery can be widened but never narrowed. add-targeting <id> adds users/regions/SDK levels (--all-users, --regions, --sdk-levels), requires --confirm, and is append-only at the API level. There is no "remove targeting". To shrink the blast radius, you must cancel the recovery and create a fresh one, plan the initial audience conservatively for exactly this reason.

list, and the missing view

recovery list --version-code <N> shows each recovery's id, status, and creation time (--version-code required, recoveries are keyed by version). There is no recovery view; the API exposes only list, so list is how you read a recovery's state and find its appRecoveryId. --output json passes ListAppRecoveriesResponse through verbatim.