Feature request: docs +insert-image helper to embed Drive-hosted images without requiring public sharing

Open
#856 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Quiet
Tech stack
google-cloud, rust
Domain
api, cli, cloud

Research direction

Start by reading the existing helpers pattern and the proposed gws docs +insert-image entry point, then review how insertInlineImage and authenticated Drive downloads are used. Compare the temporary GCS or Drive upload flow with the Apps Script DriveApp and DocumentApp alternative. Done means private Drive images can be inserted with optional width and index without public sharing, while temporary data is cleaned up.

Written by the indexing model from the issue text.

Description

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 forbidden
  • thumbnailLink from Drive API → 403 forbidden
  • drive.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:

  1. Download the image bytes via the Drive API (authenticated, using the caller's existing credentials)
  2. Upload them to a temporary GCS or Drive location scoped to the request
  3. 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.

Dominant language
Rust
Stars
32.3k
Forks
2k
Avg merge
16h 3m
Merged PRs (30d)
1

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from googleworkspace/cli

All issues in googleworkspace/cli

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.