feat(docs): add layout-preserving image replacement

steipete · steipete · commit 87029ed0507c · 2026-06-19T13:21:36.000-04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 ### Added
 
+- Docs: add `replace-image` with exact object-ID, alt-text, single-image, tab, public-URL, and local-file targeting while preserving the original image position and bounds. (#853) — thanks @sebsnyk.
 - Docs: add `insert --markdown` to convert markdown to Google Docs formatting and place the converted block at a position resolved by `--index`/`--at`/`--occurrence`, giving `insert` parity with the existing `update --markdown` and `write --markdown` paths. (#851, #854) — thanks @sebsnyk.
 
 ## 0.29.0 - 2026-06-19
diff --git a/docs/commands.generated.md b/docs/commands.generated.md
@@ -270,6 +270,7 @@ Generated from `gog schema --json`.
       - [`gog docs (doc) paragraphs list (ls) <docId> [flags]`](commands/gog-docs-paragraphs-list.md) - List paragraphs
     - [`gog docs (doc) raw <docId> [flags]`](commands/gog-docs-raw.md) - Dump raw Google Docs API response as JSON (Documents.Get; lossless; for scripting and LLM consumption)
     - [`gog docs (doc) rename-tab <docId> [flags]`](commands/gog-docs-rename-tab.md) - Rename a tab in a Google Doc
+    - [`gog docs (doc) replace-image <docId> [flags]`](commands/gog-docs-replace-image.md) - Replace an existing image without changing its position or bounds
     - [`gog docs (doc) sed <docId> [<expression>] [flags]`](commands/gog-docs-sed.md) - Regex find/replace (sed-style: s/pattern/replacement/g)
     - [`gog docs (doc) structure (struct) <docId> [flags]`](commands/gog-docs-structure.md) - Show document structure with numbered paragraphs
     - [`gog docs (doc) table-column <command>`](commands/gog-docs-table-column.md) - Insert or delete native table columns
diff --git a/docs/commands/README.md b/docs/commands/README.md
@@ -2,7 +2,7 @@
 
 Every `gog` command has a generated docs page. The source of truth is the live CLI schema; run `make docs-commands` after changing command names, flags, help text, aliases, or arguments.
 
-Generated pages: 679.
+Generated pages: 680.
 
 ## Top-level Commands
 
@@ -321,6 +321,7 @@ Generated pages: 679.
       - [gog docs paragraphs list](gog-docs-paragraphs-list.md) - List paragraphs
     - [gog docs raw](gog-docs-raw.md) - Dump raw Google Docs API response as JSON (Documents.Get; lossless; for scripting and LLM consumption)
     - [gog docs rename-tab](gog-docs-rename-tab.md) - Rename a tab in a Google Doc
+    - [gog docs replace-image](gog-docs-replace-image.md) - Replace an existing image without changing its position or bounds
     - [gog docs sed](gog-docs-sed.md) - Regex find/replace (sed-style: s/pattern/replacement/g)
     - [gog docs structure](gog-docs-structure.md) - Show document structure with numbered paragraphs
     - [gog docs table-column](gog-docs-table-column.md) - Insert or delete native table columns
diff --git a/docs/commands/gog-docs-replace-image.md b/docs/commands/gog-docs-replace-image.md
@@ -0,0 +1,52 @@
+# `gog docs replace-image`
+
+> Generated from `gog schema --json`. Do not edit this page by hand; run `make docs-commands`.
+
+Replace an existing image without changing its position or bounds
+
+## Usage
+
+```bash
+gog docs (doc) replace-image <docId> [flags]
+```
+
+## Parent
+
+- [gog docs](gog-docs.md)
+
+## Flags
+
+| Flag | Type | Default | Help |
+| --- | --- | --- | --- |
+| `--access-token` | `string` |  | Use provided access token directly (bypasses stored refresh tokens; token expires in ~1h) |
+| `-a`<br>`--account`<br>`--acct` | `string` |  | Account email, alias, or auto for authenticated Google API commands |
+| `--client` | `string` |  | OAuth client name (selects stored credentials + token bucket) |
+| `--color` | `string` | auto | Color output: auto\|always\|never |
+| `--disable-commands` | `string` |  | Comma-separated list of disabled commands; dot paths allowed |
+| `-n`<br>`--dry-run`<br>`--dryrun`<br>`--noop`<br>`--preview` | `bool` |  | Do not make changes; print intended actions and exit successfully |
+| `--enable-commands` | `string` |  | Comma-separated list of enabled command prefixes; dot paths allowed (restricts CLI) |
+| `--enable-commands-exact` | `string` |  | Comma-separated list of exact enabled commands; dot paths allowed and parent commands do not enable children |
+| `--file` | `string` |  | Local PNG, JPEG, or GIF image to upload and use |
+| `-y`<br>`--force`<br>`--assume-yes`<br>`--yes` | `bool` |  | Skip confirmations for destructive commands |
+| `--gmail-no-send` | `bool` | false | Block Gmail send operations (agent safety) |
+| `-h`<br>`--help` | `kong.helpFlag` |  | Show context-sensitive help. |
+| `--home` | `string` |  | Override gogcli config/data/state/cache root (equivalent to GOG_HOME) |
+| `-j`<br>`--json`<br>`--machine` | `bool` | false | Output JSON to stdout (best for scripting) |
+| `--match-alt` | `string` |  | Select the image whose alt text contains this value (case-insensitive) |
+| `--name` | `string` |  | Override the uploaded Drive filename |
+| `--no-input`<br>`--non-interactive`<br>`--noninteractive` | `bool` |  | Never prompt; fail instead (useful for CI) |
+| `--object-id` | `string` |  | Exact image object ID from docs images list |
+| `--parent` | `string` |  | Drive folder ID for an uploaded local image |
+| `-p`<br>`--plain`<br>`--tsv` | `bool` | false | Output stable, parseable text to stdout (TSV; no colors) |
+| `--results-only` | `bool` |  | In JSON mode, emit only the primary result (drops envelope fields like nextPageToken) |
+| `--select`<br>`--pick`<br>`--project` | `string` |  | In JSON mode, select comma-separated fields (best-effort; supports dot paths). Desire path: use --fields for most commands. |
+| `--tab` | `string` |  | Target a specific tab by title or ID (see docs list-tabs) |
+| `--url` | `string` |  | Public HTTPS image URL to use directly |
+| `-v`<br>`--verbose` | `bool` |  | Enable verbose logging |
+| `--version` | `kong.VersionFlag` |  | Print version and exit |
+| `--wrap-untrusted` | `bool` | false | In JSON/raw output, wrap fetched text fields in external untrusted-content markers |
+
+## See Also
+
+- [gog docs](gog-docs.md)
+- [Command index](README.md)
diff --git a/docs/commands/gog-docs.md b/docs/commands/gog-docs.md
@@ -47,6 +47,7 @@ gog docs (doc) <command> [flags]
 - [gog docs paragraphs](gog-docs-paragraphs.md) - List document paragraphs
 - [gog docs raw](gog-docs-raw.md) - Dump raw Google Docs API response as JSON (Documents.Get; lossless; for scripting and LLM consumption)
 - [gog docs rename-tab](gog-docs-rename-tab.md) - Rename a tab in a Google Doc
+- [gog docs replace-image](gog-docs-replace-image.md) - Replace an existing image without changing its position or bounds
 - [gog docs sed](gog-docs-sed.md) - Regex find/replace (sed-style: s/pattern/replacement/g)
 - [gog docs structure](gog-docs-structure.md) - Show document structure with numbered paragraphs
 - [gog docs table-column](gog-docs-table-column.md) - Insert or delete native table columns
diff --git a/docs/docs-editing.md b/docs/docs-editing.md
@@ -191,9 +191,21 @@ Both modes accept `--tab`, `--width`, and `--height`. Omit anchor flags or use
 `--at end` to append. `--at <text>` deletes and replaces the first literal text
 match; use `--before <text>` or `--after <text>` to preserve the anchor text.
 
-Command page:
+Replace an existing image without changing its position or rendered bounds:
+
+```bash
+gog docs replace-image <docId> --object-id <imageObjectId> --url https://example.com/chart.png
+gog docs replace-image <docId> --match-alt "Quarterly chart" --file chart.png
+```
+
+Get image object IDs and alt text from `docs images list`. When the selected tab
+contains exactly one image, omit both selector flags. Local replacement files
+use the same temporary Drive sharing and permission cleanup as `insert-image`.
+
+Command pages:
 
 - [`gog docs insert-image`](commands/gog-docs-insert-image.md)
+- [`gog docs replace-image`](commands/gog-docs-replace-image.md)
 
 ## Page Breaks
 
diff --git a/internal/cmd/docs.go b/internal/cmd/docs.go
@@ -38,6 +38,7 @@ type DocsCmd struct {
 	TableUnmerge     DocsTableUnmergeCmd     `cmd:"" name:"table-unmerge" aliases:"table-split" help:"Unmerge the region containing a native table cell"`
 	TableColumnWidth DocsTableColumnWidthCmd `cmd:"" name:"table-column-width" aliases:"table-width,column-width" help:"Set or reset native table column widths"`
 	InsertImage      DocsInsertImageCmd      `cmd:"" name:"insert-image" help:"Insert a public image URL or upload a local image into a Google Doc"`
+	ReplaceImage     DocsReplaceImageCmd     `cmd:"" name:"replace-image" help:"Replace an existing image without changing its position or bounds"`
 	InsertPerson     DocsInsertPersonCmd     `cmd:"" name:"insert-person" help:"Insert a native person smart chip"`
 	InsertFileChip   DocsInsertFileChipCmd   `cmd:"" name:"insert-file-chip" aliases:"insert-rich-link" help:"Insert a native Drive file smart chip"`
 	InsertDateChip   DocsInsertDateChipCmd   `cmd:"" name:"insert-date-chip" help:"Insert a native date smart chip"`
diff --git a/internal/cmd/docs_enumerators.go b/internal/cmd/docs_enumerators.go
@@ -271,6 +271,19 @@ func loadDocsEnumeratorDocument(
 	if err != nil {
 		return nil, "", err
 	}
+	return loadDocsEnumeratorDocumentWithService(ctx, svc, id, tabQuery)
+}
+
+func loadDocsEnumeratorDocumentWithService(
+	ctx context.Context,
+	svc *docs.Service,
+	docID string,
+	tabQuery string,
+) (*docs.Document, string, error) {
+	id := normalizeGoogleID(strings.TrimSpace(docID))
+	if id == "" {
+		return nil, "", usage("empty docId")
+	}
 	tabQuery = strings.TrimSpace(tabQuery)
 	call := svc.Documents.Get(id).Context(ctx)
 	if tabQuery != "" {
diff --git a/internal/cmd/docs_insert_image.go b/internal/cmd/docs_insert_image.go
@@ -254,11 +254,7 @@ func (c *DocsInsertImageCmd) runFile(ctx context.Context, docsSvc *docs.Service,
 	result.uploadedFileID = uploaded.Id
 	result.uploadedFileName = uploaded.Name
 
-	perm, err := driveSvc.Permissions.Create(uploaded.Id, &drive.Permission{Type: "anyone", Role: drivePermRoleReader}).
-		SupportsAllDrives(true).
-		Fields("id,type,role").
-		Context(ctx).
-		Do()
+	perm, err := shareDocsImagePublicly(ctx, driveSvc, uploaded.Id)
 	if err != nil {
 		if strings.EqualFold(c.OnRestricted, "link") && isDrivePublicSharingRestricted(err) {
 			return c.insertRestrictedImageFallback(ctx, docsSvc, docID, uploaded, target, result)
@@ -271,18 +267,7 @@ func (c *DocsInsertImageCmd) runFile(ctx context.Context, docsSvc *docs.Service,
 		if perm.Id == "" {
 			return
 		}
-		cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second)
-		defer cancel()
-		revokeErr := driveSvc.Permissions.Delete(uploaded.Id, perm.Id).SupportsAllDrives(true).Context(cleanupCtx).Do()
-		if revokeErr == nil {
-			result.revoked = true
-			return
-		}
-		if err != nil {
-			err = fmt.Errorf("%w; additionally failed to revoke temporary public permission %s on %s: %w", err, perm.Id, uploaded.Id, revokeErr)
-			return
-		}
-		err = fmt.Errorf("revoke temporary public permission %s on %s: %w", perm.Id, uploaded.Id, revokeErr)
+		result.revoked, err = finishDocsImagePublicShare(ctx, driveSvc, uploaded.Id, perm.Id, err)
 	}()
 
 	imageURL := driveImageDownloadURL(uploaded.Id)
@@ -348,6 +333,36 @@ func uploadDocsInlineImage(ctx context.Context, svc *drive.Service, localPath, n
 	return created, nil
 }
 
+func shareDocsImagePublicly(ctx context.Context, svc *drive.Service, fileID string) (*drive.Permission, error) {
+	return svc.Permissions.Create(fileID, &drive.Permission{Type: "anyone", Role: drivePermRoleReader}).
+		SupportsAllDrives(true).
+		Fields("id,type,role").
+		Context(ctx).
+		Do()
+}
+
+func finishDocsImagePublicShare(
+	ctx context.Context,
+	svc *drive.Service,
+	fileID string,
+	permissionID string,
+	operationErr error,
+) (bool, error) {
+	if permissionID == "" {
+		return false, operationErr
+	}
+	cleanupCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second)
+	defer cancel()
+	revokeErr := svc.Permissions.Delete(fileID, permissionID).SupportsAllDrives(true).Context(cleanupCtx).Do()
+	if revokeErr == nil {
+		return true, operationErr
+	}
+	if operationErr != nil {
+		return false, fmt.Errorf("%w; additionally failed to revoke temporary public permission %s on %s: %w", operationErr, permissionID, fileID, revokeErr)
+	}
+	return false, fmt.Errorf("revoke temporary public permission %s on %s: %w", permissionID, fileID, revokeErr)
+}
+
 func (c *DocsInsertImageCmd) buildInsertRequests(ctx context.Context, svc *docs.Service, docID string, target docsImageTarget, imageURL string) ([]*docs.Request, int64, string, error) {
 	index, placeholder, tabID, err := c.resolveImageTarget(ctx, svc, docID, target)
 	if err != nil {
diff --git a/internal/cmd/docs_replace_image.go b/internal/cmd/docs_replace_image.go
diff --git a/internal/cmd/docs_replace_image_test.go b/internal/cmd/docs_replace_image_test.go
