Prompts Used for the creation of this issue.

1. How can I update a PDF on Google Drive if that Google Drive PDF already has shared links? As in, how can I replace the old version with the updated version, and the same link works?
2. Look through https://github.com/steipete/gogcli/issues and https://github.com/steipete/gogcli/pulls and see whether or not this is an issue that is already being discussed or worked on regarding the re-uploading of Google Drive files of new existing versions of the existing files to make sure that the same links are functioning.
3. Can you check whether the Google Drive API actually works for this, or if that functionality is not integrated into the API? I'm assuming this CLI basically wraps the API.
4. Create a detailed issue that we can submit in the GOG CLI GitHub to request this functionality.

Summary

Add Drive in-place content replacement (API files.update) so users can upload a new version to an existing fileId without link/permission churn (Drive UI equivalent: Manage versions -> Upload new version).

Problem

gog drive upload uses create semantics (files.create), generating a new fileId; shared links/bookmarks/embeds tied to the old ID break.

Expected behavior

Given {fileId, localPath}, gog updates content in place:

• preserves fileId
• preserves sharing/ACLs
• preserves shared URL
• creates a new Drive revision

Proposed CLI

Option A (new command):

gog drive replace <fileId> <localPath>

Option B (upload flag):

gog drive upload <localPath> --replace <fileId>

Optional flags:

• --name <newName> (metadata rename)
• --keep-revision-forever (Drive keepRevisionForever)
• --mime-type <mime> (override inference)
• --json

API mapping

Use Drive API v3 files.update media upload on existing fileId (not files.create):

• content: upload endpoint (/upload/drive/v3/files/{fileId})
• metadata: patch fields if requested
• shared drives: always set supportsAllDrives=true
• return: id,name,mimeType,modifiedTime,webViewLink

Scope

Initial support: binary/non-native files (PDF/DOCX/XLSX/PPTX/images/etc.).
If target is native Google Workspace doc, either:

1. explicit unsupported error with guidance, or
2. defined native behavior (documented).

Output

Human:

• id, name, mimeType, modified, link, replaced=true

JSON:

{
  "file": {},
  "replaced": true,
  "preservedFileId": true
}

Errors

• invalid/missing fileId (404)
• permission/scope failure (403)
• shared-drive access issues
• local path/read/upload failures
• unsupported target type (if scoped)

Why

Enables stable-link publishing (recurring reports/artifacts) and automation without URL updates.

Context

Related Drive upload/convert/sync work exists; no dedicated issue for "replace existing file content while preserving ID/link."

Acceptance criteria

• Command supports in-place replace by fileId
• Shared link unchanged post-replace
• Permissions unchanged
• New revision created
• Works on shared drives (supportsAllDrives=true)
• Tests cover success + failure cases