Problem
The Google Docs REST API's insertInlineImage requires a publicly accessible URL — it does a server-side fetch with no authentication context. This makes it impossible to programmatically insert images stored in private Google Drive files into a document, even when the caller has full Drive and Docs scopes.
Workarounds all hit dead ends:
drive.google.com/uc?export=download URLs → 403 forbiddenthumbnailLink from Drive API → 403 forbiddendrive.google.com/thumbnail?id=... → retrieval error- HTML upload with base64 data URI → images silently stripped during conversion
- HTML upload with Drive
<img src> → blank image placeholder (fetch needs public access)
The only working path is Google Apps Script (DriveApp.getFileById().getBlob() → doc.getBody().insertImage(blob)), which runs server-side as the authenticated user and doesn't need a public URL. But that requires enabling the Apps Script API separately — significant friction for a common task.
Proposal
Add a gws docs +insert-image helper that handles private Drive images transparently:
# Insert a Drive-hosted image at the start of a document
gws docs +insert-image --document <DOC_ID> --file <DRIVE_FILE_ID>
# With explicit size
gws docs +insert-image --document <DOC_ID> --file <DRIVE_FILE_ID> --width 468 --index 5
Under the hood it could:
- Download the image bytes via the Drive API (authenticated, using the caller's existing credentials)
- Upload them to a temporary GCS or Drive location scoped to the request
- Insert via
insertInlineImage and immediately clean up
Or, if Apps Script is available, use DriveApp + DocumentApp to insert the blob directly — similar to how #686 suggests using Apps Script for pageless mode.
Why it matters
Inserting architecture diagrams, charts, and other locally-generated images into Docs is a core use case for AI agents and automation workflows. Right now any agent that renders a diagram locally (e.g. via mmdc) has no clean path to embed it in a private document — the only options are making files public (unacceptable for sensitive content) or manual copy-paste.
The helpers pattern exists precisely to paper over gaps like this in the underlying API surface.
Problem
The Google Docs REST API's
insertInlineImagerequires a publicly accessible URL — it does a server-side fetch with no authentication context. This makes it impossible to programmatically insert images stored in private Google Drive files into a document, even when the caller has full Drive and Docs scopes.Workarounds all hit dead ends:
drive.google.com/uc?export=downloadURLs → 403 forbiddenthumbnailLinkfrom Drive API → 403 forbiddendrive.google.com/thumbnail?id=...→ retrieval error<img src>→ blank image placeholder (fetch needs public access)The only working path is Google Apps Script (
DriveApp.getFileById().getBlob()→doc.getBody().insertImage(blob)), which runs server-side as the authenticated user and doesn't need a public URL. But that requires enabling the Apps Script API separately — significant friction for a common task.Proposal
Add a
gws docs +insert-imagehelper that handles private Drive images transparently:Under the hood it could:
insertInlineImageand immediately clean upOr, if Apps Script is available, use
DriveApp + DocumentAppto insert the blob directly — similar to how #686 suggests using Apps Script for pageless mode.Why it matters
Inserting architecture diagrams, charts, and other locally-generated images into Docs is a core use case for AI agents and automation workflows. Right now any agent that renders a diagram locally (e.g. via
mmdc) has no clean path to embed it in a private document — the only options are making files public (unacceptable for sensitive content) or manual copy-paste.The helpers pattern exists precisely to paper over gaps like this in the underlying API surface.