The Docs API replaceImage request swaps the bytes behind an existing inline image while preserving its position, size, and surrounding paragraphs — only the pixels change. gog docs has no command for it. Today the only way to refresh a diagram is delete the positioned object + insert-image again, which loses the original placement and re-applies a default width, so every refresh needs manual re-positioning.

This is a common workflow: a doc embeds a generated diagram, the source regenerates, and you want to drop in new bytes without disturbing layout.

Proposed:

gog docs replace-image <docId> --file <local.png>          # upload, then ReplaceImageRequest
gog docs replace-image <docId> --url <https-url>
  --match-alt <substring>   # pick when the doc has multiple inline images (match on alt/description)
  --object-id <id>          # explicit positioned-object id (from `gog docs images list`)
  --tab <tab>

images list already enumerates the inline objects, so an --object-id selector falls out naturally; --match-alt is the ergonomic path. The upload half can reuse whatever insert-image --file already does for restricted-tenant embedding.

Ref: documents.batchUpdate ReplaceImageRequest (imageObjectId, uri, imageReplaceMethod).