proton-drive-mcp 1.0.26 → 1.0.28

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 1.0.28 — 2026-08-11
+
+Closes the last 2 gaps found in the full CLI command audit — every scriptable Proton Drive CLI command now has a matching tool.
+
+### Added
+- **`drive_info`** — full node metadata for a single file/folder, including latest revision details (`filesystem info`). Raw pass-through of the CLI's node object — richer and less trimmed than `drive_list`'s per-item fields.
+- **`drive_rename`** — rename in place without moving to a different folder (`filesystem rename`). `drive_move` already reached this internally when source/destination share a parent; it's now also directly addressable and documented as the cheaper option for pure renames.
+- **`validateName`** utility — guards bare name/filename CLI arguments (not paths) against flag injection, used by `drive_rename`'s `newName`.
+
+### Coverage
+33 commands in the CLI's registry (verified against the `cli/v0.7.0` release tag) minus `auth login` (interactive browser flow, deliberately excluded) = 32 scriptable commands, all now covered 1:1 by a tool.
+
+## 1.0.27 — 2026-08-11
+
+A full audit against the Proton Drive CLI SDK source found that 9 existing tools called CLI commands or flags that don't exist, or had wrong semantics. This release fixes all of them and adds 7 new tools for public links, bulk access removal, album updates, and Photos timeline transfers.
+
+### Fixed (existing tools were broken — none of these worked correctly before)
+- **`drive_auth_status`** — `auth status` doesn't exist in the CLI at all; every call errored. Now probes by resolving `/my-files` and treats a not-authenticated error as the signal. The `email` field is removed — the CLI has no way to query the signed-in account's email.
+- **`drive_version`** — the CLI's `version` command ignores `--json` and always prints plain text; the tool was trying to JSON-parse it and always threw. Now parsed directly from stdout.
+- **`drive_mkdir`** — the CLI has no `mkdir`; it's `filesystem create-folder <parentPath> <name>`. The tool now splits the given path into parent + name automatically.
+- **`drive_move`** — the CLI's `move` only accepts a target *parent folder*; renaming is a separate `rename <path> <newName>` command. The tool still accepts a full destination path (unchanged external interface) but now composes `move`/`rename` correctly under the hood.
+- **`drive_delete`** — passed a `--confirm` flag that doesn't exist, and the CLI only permits deleting items already inside `/trash` or `/photos-trash` (it rejects live paths). Flag removed; description corrected.
+- **`drive_trash` / `drive_restore` / `drive_list_trash` / `drive_empty_trash`** — called a top-level `trash` command group that doesn't exist; trash operations are subcommands of `filesystem` (`filesystem trash`, `filesystem restore`, `filesystem empty-trash`), and listing trash is `filesystem list /trash`. `empty-trash` also had a nonexistent `--confirm` flag, removed.
+- **`drive_share_revoke`** — called `sharing revoke --user`, which doesn't exist; the real command is `sharing remove --email`.
+- **`drive_upload` / `drive_download`** — conflict strategy values were `skip`/`overwrite`/`rename`; the CLI's actual allowed values are `skip`/`replace`/`keep-both`/`merge` (`merge` is upload/folder-only). `drive_download` also gained a `conflictStrategy` parameter it never had.
+
+### Added
+- **`drive_share_set_url`** — create or update a public share link (`sharing set-url`), with optional role, password, and expiration
+- **`drive_share_remove_url`** — remove a public share link (`sharing remove-url`)
+- **`drive_share_remove_all`** — remove every member and pending invitation from a shared path in one call (`sharing remove --everyone`)
+- **`photos_update_album`** — rename an album or change its cover photo (`album update`)
+- **`photos_list_timeline`** — list photos in your full Photos library timeline, not scoped to an album (`photo timeline`)
+- **`photos_download`** — download one or more photos to a local folder (`photo download`)
+- **`photos_upload`** — upload local photos/videos directly into your Photos library (`photo upload`)
+
+### Not implemented
+- `sharing report` (abuse reporting) exists as source in the SDK but is not registered in the CLI's command registry — invoking it would fail with `CommandNotFoundError`. Excluded as dead code, not a gap.
+
 ## 1.0.25 — 2026-08-04
 
 ### Added

package/README.md

@@ -30,7 +30,8 @@ Give Claude Desktop (or any MCP client) full access to your Proton Drive and Pro
 
 - **Claude manages your Proton Drive** — list, upload, download, move, share, trash, restore
 - **Proton Photos album management** — list albums, create/delete albums, add and remove photos
-- **Full CLI** — same 29 operations, scriptable and pipeable, works in cron and shell scripts
+- **Full CLI** — same 38 operations, scriptable and pipeable, works in cron and shell scripts
+- **100% CLI coverage** — every scriptable Proton Drive CLI command has a matching tool (verified against the CLI's own source; `auth login` is the one command excluded, since it's an interactive browser flow)
 - **Zero credential exposure** — auth is handled entirely by the official Proton Drive CLI; this MCP never touches your password or session token
 - **Shell injection safe** — all CLI calls use `execFile` with discrete argument arrays, never string interpolation
 - **Privacy-native** — end-to-end encryption is handled by Proton's own CLI; this server is just a thin MCP wrapper
@@ -147,7 +148,7 @@ proton-drive-cli <command> [args]
 ### Auth & info
 
 ```bash
-proton-drive-cli auth status          # check if authenticated
+proton-drive-cli auth status          # probes /my-files; the CLI has no dedicated status command
 proton-drive-cli auth logout          # log out (clears OS keychain session)
 proton-drive-cli version              # CLI and SDK version
 ```
@@ -157,17 +158,20 @@ proton-drive-cli version              # CLI and SDK version
 ```bash
 proton-drive-cli list /my-files
 proton-drive-cli list /my-files/Reports
+proton-drive-cli info /my-files/report.pdf       # full metadata, incl. revision details
 
 proton-drive-cli mkdir /my-files/NewFolder
 
 proton-drive-cli upload ./report.pdf /my-files/Reports
-proton-drive-cli upload ./dist /my-files/Releases --conflict overwrite
+proton-drive-cli upload ./dist /my-files/Releases --conflict replace
 
 proton-drive-cli download /my-files/report.pdf ./local/report.pdf
-proton-drive-cli download /my-files/Reports ./local/Reports
+proton-drive-cli download /my-files/Reports ./local/Reports --conflict keep-both
 
+proton-drive-cli rename /my-files/old-name.pdf new-name.pdf   # in place, no move
 proton-drive-cli move /my-files/old-name.pdf /my-files/new-name.pdf
-proton-drive-cli delete /my-files/obsolete-draft.pdf
+proton-drive-cli copy /my-files/report.pdf /my-files/Archive
+proton-drive-cli delete /trash/obsolete-draft.pdf --confirm   # only works on items already in trash
 
 # Machine-readable output (pipe-friendly)
 proton-drive-cli list /my-files --json | jq '.[].name'
@@ -180,22 +184,39 @@ proton-drive-cli share status /my-files/Reports
 proton-drive-cli share invite /my-files/Reports alice@pm.me editor
 proton-drive-cli share invite /my-files/Reports bob@pm.me viewer --message "FYI"
 proton-drive-cli share revoke /my-files/Reports alice@pm.me
+proton-drive-cli share remove-all /my-files/Reports --confirm   # strip every member + pending invite
+
+proton-drive-cli share set-url /my-files/Reports --role viewer --expiration 2026-06-06
+proton-drive-cli share remove-url /my-files/Reports
 ```
 
 ### Trash
 
 ```bash
-proton-drive-cli trash /my-files/old-draft.pdf   # move to trash
-proton-drive-cli trash list                       # see what's in trash
-proton-drive-cli restore /my-files/old-draft.pdf # restore from trash
-proton-drive-cli trash empty                      # permanently delete all trashed items
+proton-drive-cli trash /my-files/old-draft.pdf        # move to trash
+proton-drive-cli trash list                            # see what's in trash
+proton-drive-cli restore /my-files/old-draft.pdf       # restore from trash
+proton-drive-cli trash empty --confirm                  # permanently delete all trashed items
+```
+
+### Photos
+
+```bash
+proton-drive-cli album list
+proton-drive-cli album create "Summer 2026"
+proton-drive-cli album update /albums/Summer2026 --name "Summer Trip"
+proton-drive-cli album add-photo /albums/Summer2026 /photos/IMG_001.jpg
+
+proton-drive-cli photo timeline
+proton-drive-cli photo download /photos/IMG_001.jpg ./local/photos --conflict keep-both
+proton-drive-cli photo upload ./camera-roll --conflict skip
 ```
 
 ### Pipe and script
 
 ```bash
 # Backup build output after CI
-proton-drive-cli upload ./dist /my-files/Releases/$(date +%Y-%m-%d) --conflict rename
+proton-drive-cli upload ./dist /my-files/Releases/$(date +%Y-%m-%d) --conflict keep-both
 
 # Download all contracts for audit
 proton-drive-cli download /my-files/Contracts ./audit/contracts
@@ -215,10 +236,10 @@ proton-drive-cli share status /my-files/Projects
 `drive_auth_status` · `drive_auth_logout` · `drive_version`
 
 ### Filesystem
-`drive_list` · `drive_mkdir` · `drive_upload` · `drive_download` · `drive_move` · `drive_delete`
+`drive_list` · `drive_info` · `drive_mkdir` · `drive_upload` · `drive_download` · `drive_rename` · `drive_move` · `drive_delete`
 
 ### Sharing
-`drive_share_status` · `drive_share_invite` · `drive_share_revoke`
+`drive_share_status` · `drive_share_invite` · `drive_share_revoke` · `drive_share_remove_all` · `drive_share_set_url` · `drive_share_remove_url`
 
 ### Trash
 `drive_list_trash` · `drive_trash` · `drive_restore` · `drive_empty_trash`
@@ -233,7 +254,7 @@ proton-drive-cli share status /my-files/Projects
 `drive_list_invitations` · `drive_invitation_accept` · `drive_invitation_reject` · `drive_share_leave`
 
 ### Photos
-`photos_list_albums` · `photos_create_album` · `photos_delete_album` · `photos_list_album_photos` · `photos_add_to_album` · `photos_remove_from_album`
+`photos_list_albums` · `photos_create_album` · `photos_update_album` · `photos_delete_album` · `photos_list_album_photos` · `photos_add_to_album` · `photos_remove_from_album` · `photos_list_timeline` · `photos_download` · `photos_upload`
 
 ---
 
@@ -241,35 +262,44 @@ proton-drive-cli share status /my-files/Projects
 
 | Tool | Description | Key parameters |
 |------|-------------|----------------|
-| `drive_auth_status` | Check if CLI is authenticated | — |
+| `drive_auth_status` | Check if authenticated (probes `/my-files` — no native status command) | — |
 | `drive_auth_logout` | Log out (clear session) | — |
 | `drive_version` | CLI and SDK version info | — |
 | `drive_list` | List files and folders at a path | `path` |
+| `drive_info` | Get full metadata for one file/folder, including revision details | `path` |
 | `drive_mkdir` | Create a new empty folder | `path` |
-| `drive_upload` | Upload local file or folder | `localPath`, `remotePath`, `conflictStrategy` (skip/overwrite/rename) |
-| `drive_download` | Download to local path | `remotePath`, `localPath` |
-| `drive_move` | Move or rename | `sourcePath`, `destinationPath` |
-| `drive_delete` | Permanently delete ⚠️ | `path`, `confirmed: true` |
+| `drive_upload` | Upload local file or folder | `localPath`, `remotePath`, `conflictStrategy` (skip/replace/keep-both/merge) |
+| `drive_download` | Download to local path | `remotePath`, `localPath`, `conflictStrategy` (skip/replace/keep-both) |
+| `drive_rename` | Rename in place, no move | `path`, `newName` |
+| `drive_move` | Move and/or rename | `sourcePath`, `destinationPath` |
+| `drive_copy` | Copy file or folder to another Drive location | `sourcePath`, `destinationPath` |
+| `drive_delete` | Permanently delete an item already in trash ⚠️ | `path`, `confirmed: true` |
 | `drive_list_trash` | List items currently in trash | — |
 | `drive_share_status` | Get sharing members and URL | `path` |
 | `drive_share_invite` | Invite a user | `path`, `email`, `role` (viewer/editor/admin), `message?` |
-| `drive_share_revoke` | Revoke access | `path`, `email` |
+| `drive_share_revoke` | Revoke one person's access | `path`, `email` |
+| `drive_share_remove_all` | Remove every member + pending invitation at once ⚠️ | `path`, `confirmed: true` |
+| `drive_share_set_url` | Create/update a public share link | `path`, `role?` (viewer/editor), `password?`, `expiration?` |
+| `drive_share_remove_url` | Remove the public share link ⚠️ | `path` |
 | `drive_trash` | Move to trash | `path` |
 | `drive_restore` | Restore from trash | `path` |
 | `drive_empty_trash` | Permanently delete all trash ⚠️ | `confirmed: true` |
 | `drive_read_file` | Read text file from local sync folder | `path` |
 | `drive_write_file` | Write text file to local sync folder ⚠️ | `path`, `content` |
-| `drive_copy` | Copy file or folder to another Drive location | `sourcePath`, `destinationPath` |
 | `drive_list_invitations` | List pending sharing invitations received | — |
 | `drive_invitation_accept` | Accept a pending invitation | `uid` (from `drive_list_invitations`) |
 | `drive_invitation_reject` | Reject a pending invitation ⚠️ | `uid` (from `drive_list_invitations`) |
 | `drive_share_leave` | Leave a shared folder shared with you ⚠️ | `path` |
 | `photos_list_albums` | List all Proton Photos albums | — |
 | `photos_create_album` | Create a new empty album | `name` |
+| `photos_update_album` | Rename an album or change its cover photo | `albumPath`, `name?`, `coverPhotoUid?` |
 | `photos_delete_album` | Delete an album ⚠️ | `albumPath`, `confirmed: true`, `force?`, `save?` |
 | `photos_list_album_photos` | List photos in an album | `albumPath` |
 | `photos_add_to_album` | Add a photo from your library to an album | `albumPath`, `photoPath` |
 | `photos_remove_from_album` | Remove a photo from an album (keeps it in library) ⚠️ | `albumPath`, `photoPath` |
+| `photos_list_timeline` | List photos in your full library timeline | `loadDetails?` |
+| `photos_download` | Download photos to a local folder | `photoPaths`, `localFolder`, `conflictStrategy?` (skip/replace/keep-both) |
+| `photos_upload` | Upload local files directly into your Photos library | `localPaths`, `conflictStrategy?` (skip/keep-both) |
 
 > ⚠️ **Destructive tools** require `confirmed: true`. Use `drive_list_trash` first so you know what will be deleted, then pass `confirmed: true` to proceed.
 
@@ -291,9 +321,11 @@ proton-drive-cli share status /my-files/Projects
 ## Operational notes
 
 - `drive_upload` passes `--skip-thumbnails` by default. Remove it from the subprocess args if you want WebP preview generation (requires Bun 1.3.14+ installed).
-- `drive_move` and `drive_delete` are best-effort — the Proton Drive CLI documentation does not guarantee these commands exist in v1. If a command returns a CLI error, the MCP tool surfaces it cleanly.
+- `drive_move` accepts a full destination path (parent + new name) for a familiar interface, but the underlying CLI only has separate `move` (change parent) and `rename` (change name) commands — this MCP translates automatically, issuing one or both as needed.
+- `drive_delete` only works on items already in `/trash` or `/photos-trash` — the CLI rejects live paths. Trash an item first with `drive_trash`, or use `drive_empty_trash` to clear everything at once.
+- `drive_auth_status` has no native CLI equivalent — it probes by resolving `/my-files` and reports authenticated based on whether that succeeds.
 - Paths are always Drive-absolute: `/my-files/folder/file.pdf`. Relative paths are not supported.
-- All calls include `--json` automatically — you never need to pass it manually via the CLI wrapper.
+- All calls include `--json` automatically, except `drive_version`, whose underlying CLI command ignores `--json` and always prints plain text — this MCP parses it directly.
 
 ---
 

package/dist/cli.js

@@ -4,30 +4,12 @@
  * Provides a human-friendly interface to the same DriveService used by the MCP server.
  *
  * Usage: proton-drive-cli <command> [args]
- *   auth status
- *   auth logout
- *   version
- *   list <remote-path>
- *   mkdir <remote-path>
- *   upload <local-path> <remote-path> [--conflict skip|overwrite|rename]
- *   download <remote-path> <local-path>
- *   move <src> <dst>
- *   delete <path>
- *   share status <path>
- *   share invite <path> <email> <role> [--message "..."]
- *   share revoke <path> <email>
- *   trash <path>
- *   trash list
- *   trash empty
- *   restore <path>
- *
- * Global flags:
- *   --json   Machine-readable JSON output
+ * Run with --help (or see usage() below) for the full command list.
  */
 import { DriveService } from "./services/drive.js";
 import { DriveCliError, DriveCliNotFoundError, DriveNotAuthenticatedError, DriveParseError } from "./utils/errors.js";
 import { checkCliAvailable } from "./utils/subprocess.js";
-import { validateRemotePath, validateLocalPath, validateEmail, validateMessage } from "./utils/validation.js";
+import { validateRemotePath, validateLocalPath, validateEmail, validateMessage, validateName } from "./utils/validation.js";
 const drive = new DriveService();
 const args = process.argv.slice(2);
 const jsonMode = args.includes("--json");
@@ -36,28 +18,42 @@ function usage() {
 proton-drive-cli — Proton Drive companion CLI
 
 Commands:
-  auth status                              Check authentication status
+  auth status                              Check authentication status (probes /my-files)
   auth logout                              Log out
   version                                  Show CLI/SDK version
   list <path>                              List files at path
+  info <path>                              Show full node metadata for one path
   mkdir <path>                             Create a new folder
-  upload <local> <remote> [--conflict X]  Upload file/folder (skip/overwrite/rename)
-  download <remote> <local>               Download file/folder
-  move <src> <dst>                         Move/rename
-  delete <path>                            Delete file/folder permanently
+  upload <local> <remote> [--conflict X]  Upload file/folder (skip/replace/keep-both/merge)
+  download <remote> <local> [--conflict X] Download file/folder (skip/replace/keep-both)
+  rename <path> <new-name>                 Rename in place, no move
+  move <src> <dst>                         Move and/or rename
+  delete <path> --confirm                  Delete a file/folder already in trash, permanently
   share status <path>                      Show sharing info
   share invite <path> <email> <role>       Invite user (viewer/editor/admin)
-  share revoke <path> <email>              Revoke access
+  share revoke <path> <email>              Revoke one user's access
+  share remove-all <path> --confirm        Remove everyone's access + pending invitations
+  share set-url <path> [--role] [--password] [--expiration]  Create/update public link
+  share remove-url <path>                  Remove public link
+  share leave <path>                       Leave a folder shared with you
+  copy <src> <dst>                         Copy file/folder
   trash <path>                             Move to trash
   trash list                               List trash contents
-  trash empty                              Permanently delete all trash
+  trash empty --confirm                    Permanently delete all trash
   restore <path>                           Restore from trash
+  invitation list                          List pending invitations
+  invitation accept <uid>                  Accept an invitation
+  invitation reject <uid>                  Reject an invitation
   album list                               List all photo albums
   album create <name>                      Create a new album
-  album delete <path> [--force] [--save]  Delete an album
+  album update <path> [--name] [--cover-photo-uid]  Rename/update album cover
+  album delete <path> --confirm [--force] [--save]  Delete an album
   album photos <path>                      List photos in an album
   album add-photo <album> <photo>          Add a photo to an album
   album remove-photo <album> <photo>       Remove a photo from an album
+  photo timeline [--load-details]          List photos in your timeline
+  photo download <photo>... <local> [--conflict X]  Download photos (skip/replace/keep-both)
+  photo upload <local>... [--conflict X]   Upload photos to your library (skip/keep-both)
 
 Flags:
   --json                                   Machine-readable JSON output (one line)
@@ -143,6 +139,9 @@ async function run() {
         case "list":
             print(await drive.list(requirePath(sub, "list <path>")));
             break;
+        case "info":
+            print(await drive.info(requirePath(sub, "info <path>")));
+            break;
         case "upload": {
             const rawLocal = sub;
             if (!rawLocal) {
@@ -160,8 +159,8 @@ async function run() {
             }
             const remote = requirePath(rest[0], "upload <local> <remote>");
             const conflictRaw = getFlag("--conflict") ?? "skip";
-            if (!["skip", "overwrite", "rename"].includes(conflictRaw)) {
-                console.error(`Invalid --conflict value: ${conflictRaw}. Must be skip, overwrite, or rename.`);
+            if (!["skip", "replace", "keep-both", "merge"].includes(conflictRaw)) {
+                console.error(`Invalid --conflict value: ${conflictRaw}. Must be skip, replace, keep-both, or merge.`);
                 process.exit(1);
             }
             const conflict = conflictRaw;
@@ -185,7 +184,28 @@ async function run() {
                 process.exit(1);
                 return;
             }
-            print(await drive.download(remote, local));
+            const dConflictRaw = getFlag("--conflict") ?? "skip";
+            if (!["skip", "replace", "keep-both"].includes(dConflictRaw)) {
+                console.error(`Invalid --conflict value: ${dConflictRaw}. Must be skip, replace, or keep-both.`);
+                process.exit(1);
+            }
+            print(await drive.download(remote, local, dConflictRaw));
+            break;
+        }
+        case "rename": {
+            const renamePath = requirePath(sub, "rename <path> <new-name>");
+            const rawNewName = rest[0];
+            let newName;
+            try {
+                newName = validateName(rawNewName);
+            }
+            catch (e) {
+                console.error(e instanceof Error ? e.message : String(e));
+                process.exit(1);
+                return;
+            }
+            await drive.rename(renamePath, newName);
+            console.log(`Renamed: ${renamePath} → ${newName}`);
             break;
         }
         case "move": {
@@ -202,7 +222,7 @@ async function run() {
         case "delete": {
             const delPath = requirePath(sub, "delete <path> --confirm");
             if (!args.includes("--confirm")) {
-                console.error(`This will permanently delete: ${delPath}\nPass --confirm to proceed.`);
+                console.error(`This permanently deletes an item already in trash: ${delPath}\nPass --confirm to proceed.`);
                 process.exit(1);
             }
             await drive.delete(delPath);
@@ -241,6 +261,31 @@ async function run() {
                 await drive.shareRevoke(revokePath, revokeEmail);
                 console.log(`Revoked access for ${revokeEmail}.`);
             }
+            else if (sub === "remove-all") {
+                const removeAllPath = requirePath(rest[0], "share remove-all <path> --confirm");
+                if (!args.includes("--confirm")) {
+                    console.error(`This removes everyone's access to: ${removeAllPath}\nPass --confirm to proceed.`);
+                    process.exit(1);
+                }
+                await drive.shareRemove(removeAllPath, [], true);
+                console.log(`Removed all access to: ${removeAllPath}`);
+            }
+            else if (sub === "set-url") {
+                const setUrlPath = requirePath(rest[0], "share set-url <path> [--role] [--password] [--expiration]");
+                const roleRaw = getFlag("--role") ?? "viewer";
+                if (!["viewer", "editor"].includes(roleRaw)) {
+                    console.error(`Invalid --role value: ${roleRaw}. Must be viewer or editor.`);
+                    process.exit(1);
+                }
+                const password = getFlag("--password");
+                const expiration = getFlag("--expiration");
+                print(await drive.shareSetUrl(setUrlPath, roleRaw, password, expiration));
+            }
+            else if (sub === "remove-url") {
+                const removeUrlPath = requirePath(rest[0], "share remove-url <path>");
+                await drive.shareRemoveUrl(removeUrlPath);
+                console.log(`Public link removed: ${removeUrlPath}`);
+            }
             else if (sub === "leave") {
                 const leavePath = requirePath(rest[0], "share leave <path>");
                 await drive.shareLeave(leavePath);
@@ -323,6 +368,17 @@ async function run() {
                 await drive.createAlbum(albumName);
                 console.log(`Album created: ${albumName}`);
             }
+            else if (sub === "update") {
+                const albumPath = requirePath(rest[0], "album update <path> [--name] [--cover-photo-uid]");
+                const newName = getFlag("--name");
+                const coverPhotoUid = getFlag("--cover-photo-uid");
+                if (!newName && !coverPhotoUid) {
+                    console.error("Usage: album update <path> [--name <name>] [--cover-photo-uid <uid>] (at least one required)");
+                    process.exit(1);
+                }
+                await drive.updateAlbum(albumPath, newName, coverPhotoUid);
+                console.log(`Album updated: ${albumPath}`);
+            }
             else if (sub === "delete") {
                 const albumPath = requirePath(rest[0], "album delete <path> [--force] [--save] --confirm");
                 if (!args.includes("--confirm")) {
@@ -349,10 +405,72 @@ async function run() {
                 console.log(`Removed ${photoPath} from ${albumPath}`);
             }
             else {
-                console.error("Usage: album list | album create <name> | album delete <path> | album photos <path> | album add-photo <album> <photo> | album remove-photo <album> <photo>");
+                console.error("Usage: album list | album create <name> | album update <path> | album delete <path> | album photos <path> | album add-photo <album> <photo> | album remove-photo <album> <photo>");
+                process.exit(1);
+            }
+            break;
+        case "photo": {
+            // Strip --conflict <value> out of a variadic positional list.
+            const conflictFlagIdx = rest.indexOf("--conflict");
+            const positionals = conflictFlagIdx === -1
+                ? rest
+                : [...rest.slice(0, conflictFlagIdx), ...rest.slice(conflictFlagIdx + 2)];
+            const conflictRaw = getFlag("--conflict") ?? "skip";
+            if (sub === "timeline") {
+                print(await drive.photoTimeline(args.includes("--load-details")));
+            }
+            else if (sub === "download") {
+                if (positionals.length < 2) {
+                    console.error("Usage: photo download <photo>... <local-folder> [--conflict X]");
+                    process.exit(1);
+                    return;
+                }
+                const localFolder = positionals[positionals.length - 1];
+                const photoPaths = positionals.slice(0, -1).map((p) => requirePath(p, "photo download <photo>... <local-folder>"));
+                let localFolderValidated;
+                try {
+                    localFolderValidated = validateLocalPath(localFolder);
+                }
+                catch (e) {
+                    console.error(e instanceof Error ? e.message : String(e));
+                    process.exit(1);
+                    return;
+                }
+                if (!["skip", "replace", "keep-both"].includes(conflictRaw)) {
+                    console.error(`Invalid --conflict value: ${conflictRaw}. Must be skip, replace, or keep-both.`);
+                    process.exit(1);
+                }
+                print(await drive.photoDownload(photoPaths, localFolderValidated, conflictRaw));
+            }
+            else if (sub === "upload") {
+                if (positionals.length === 0) {
+                    console.error("Usage: photo upload <local>... [--conflict X]");
+                    process.exit(1);
+                    return;
+                }
+                const localPaths = [];
+                for (const p of positionals) {
+                    try {
+                        localPaths.push(validateLocalPath(p));
+                    }
+                    catch (e) {
+                        console.error(e instanceof Error ? e.message : String(e));
+                        process.exit(1);
+                        return;
+                    }
+                }
+                if (!["skip", "keep-both"].includes(conflictRaw)) {
+                    console.error(`Invalid --conflict value: ${conflictRaw}. Must be skip or keep-both.`);
+                    process.exit(1);
+                }
+                print(await drive.photoUpload(localPaths, conflictRaw));
+            }
+            else {
+                console.error("Usage: photo timeline [--load-details] | photo download <photo>... <local> | photo upload <local>...");
                 process.exit(1);
             }
             break;
+        }
         default:
             console.error(`Unknown command: ${cmd}`);
             usage();