Problem

There is no first-class gog command to embed a local image into a Google Doc.

Today the workflow for a markdown-to-Docs pipeline looks like:

1. Pre-process the markdown to extract ![alt](relative.png) references and replace each with a unique text placeholder.
2. gog docs write --replace --markdown (the placeholder survives the write).
3. gog drive upload <local.png> --parent <folderId> — gog covers this nicely.
4. gog drive share <fileId> --to anyone --role reader — gog covers this too.
5. Call raw Docs API documents.batchUpdate with insertInlineImage ← no gog equivalent.
6. gog drive unshare <fileId> <permId> — gog covers this.

Step 5 forces every consumer to import google-api-python-client (or equivalent) and re-implement: walk the doc body, find placeholder ranges, sort descending, then issue deleteContentRange + insertInlineImage batchUpdates.

Proposal

gog docs insert-image <docId> --file <localPath> [--at <placeholder|anchor>] [--width 540pt] [--alt 'text']

Semantics:

• Upload the image to a Drive folder of the caller's choosing (default: a sibling <doc-name>-images folder).
• Issue documents.batchUpdate with insertInlineImage at the requested anchor.
• Anchor resolution options:
  • --at <placeholder-string> — replace literal text matches (most useful for markdown pre-processing pipelines).
  • --at end — append at end of document.
  • --at heading=h.<id> — insert after a named heading (matches the anchor-link resolution gog already does in docs write).
• Handle the public-permission dance internally: temporarily share, embed, revoke. Caller doesn't have to think about it.

Workspace-policy fallback

Some Google Workspaces forbid anyone sharing (publishOutNotPermitted). In that case insertInlineImage will fail because Google's image fetcher needs anonymous access.

Suggested behaviour when public sharing is blocked:

• Detect the publishOutNotPermitted error and surface it clearly.
• Optional --on-restricted=link fallback: replace the placeholder with a clickable Drive link to the uploaded image, so the user can manually Insert > Image > Drive in the editor. Today every consumer reinvents this same fallback.

Related

• v0.19 added the markdown-conversion + page-size + margins primitives (docs write --pageless: also widen pageSize.width (or add --page-width flag) #629, docs write / page-layout: --margin-left, --margin-right, --margin-top, --margin-bottom #630, Drive markdown converter renders empty header row for '| | |' tables instead of dropping it #632, Drive markdown converter: resolve [text](#slug) to heading IDs instead of leaving raw fragment #633). insert-image is the natural next building block for image-bearing documents.
• Touches docs (insert) and drive (upload + share/unshare) — sits cleanly on top of existing surface.