feat(cli,core): shell completions with live values from the service

`pdfs completions <shell>` prints a completion script for bash, zsh, fish, elvish or PowerShell, built on clap_complete's dynamic engine: on Tab the shell calls `pdfs` back, which completes commands and options and also the values the running service knows, each with a description: paths in My files, synced-folder and queue ids, computers, trash, albums, items shared with me, invitations, bookmarks, conflict copies, and a file's versions or a share's members and public link once its path is typed. A completer that gets no answer from the service within two seconds offers nothing rather than hanging the prompt. Listings that ask Proton are kept for 30 s in $XDG_RUNTIME_DIR (0600), so repeated Tabs do not wait again. Completion is triggered by PDFS_COMPLETE rather than clap's generic COMPLETE, because the same binary runs the daemon. Share roles are now checked by the CLI before the request. The package recipes install the bash, zsh and fish scripts via packaging/completions.sh.
chore(release): 3.8.0
2026-11-12 17:27:03 +01:00 · 2026-11-12 11:47:29 +01:00 · 2026-11-12 10:22:04 +01:00 · 2026-11-12 00:55:19 +01:00 · 2026-11-12 00:38:50 +01:00
25 changed files with 1343 additions and 48 deletions
@@ -160,6 +160,7 @@ jobs:
          cp packaging/proton-drive.service deb/usr/lib/systemd/user/
          cp LICENSE deb/usr/share/licenses/proton-drive-linux/
          po/build.sh deb/usr/share/locale
+          packaging/completions.sh target/release/pdfs deb/usr/share

          # Stops the running daemon before removal, so the mount stops mirroring deletes
          install -m755 packaging/deb/prerm deb/DEBIAN/prerm
@@ -754,6 +754,18 @@ dependencies = [
 "strsim",
 ]

+[[package]]
+name = "clap_complete"
+version = "4.6.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "037e2a1a92236d0aff7e845093f64661d6df4c02c9fcc61a60e9e1d736fa392f"
+dependencies = [
+ "clap",
+ "clap_lex",
+ "is_executable",
+ "shlex",
+]
+
 [[package]]
 name = "clap_derive"
 version = "4.6.7"
@@ -2551,6 +2563,15 @@ version = "2.12.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "791930b43c0d5973160d90a8f3894509f2b273430f5c5c73b668636d0287c5c0"

+[[package]]
+name = "is_executable"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "82cb6a9f675da968c63b6208c641b9dca58fc0133ae53375736b1767b0cab8bd"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
 [[package]]
 name = "is_terminal_polyfill"
 version = "1.70.2"
@@ -3520,10 +3541,11 @@ checksum = "2ee67f1008b1ba2321834326597b8e186293b049a023cdef258527550b9935b4"

 [[package]]
 name = "pdfs-cli"
-version = "3.7.0"
+version = "3.8.0"
 dependencies = [
 "anyhow",
 "clap",
+ "clap_complete",
 "pdfs-core",
 "pdfs-fuse",
 "rpassword",
@@ -3536,7 +3558,7 @@ dependencies = [

 [[package]]
 name = "pdfs-core"
-version = "3.7.0"
+version = "3.8.0"
 dependencies = [
 "async-trait",
 "base64 0.23.1",
@@ -3563,7 +3585,7 @@ dependencies = [

 [[package]]
 name = "pdfs-fuse"
-version = "3.7.0"
+version = "3.8.0"
 dependencies = [
 "async-trait",
 "base64 0.23.1",
@@ -3585,7 +3607,7 @@ dependencies = [

 [[package]]
 name = "pdfs-gui"
-version = "3.7.0"
+version = "3.8.0"
 dependencies = [
 "anyhow",
 "async-channel",
@@ -3,7 +3,7 @@ resolver = "2"
 members = ["crates/pdfs-core", "crates/pdfs-fuse", "crates/pdfs-cli", "crates/pdfs-gui"]

 [workspace.package]
-version = "3.7.0"
+version = "3.8.0"
 edition = "2024"
 license = "MIT"
 authors = ["Nils Pukropp <contact@narl.io>"]
@@ -56,6 +56,9 @@ rusqlite = { version = "0.41", features = ["bundled"] }
 keyring-core = "1"
 dbus-secret-service-keyring-store = { version = "1", features = ["crypto-rust"] }
 clap = { version = "4", features = ["derive"] }
+# `unstable-dynamic`: Tab calls `pdfs` back, so arguments complete from the
+# running service. Only `pdfs-cli/src/complete.rs` uses it.
+clap_complete = { version = "4.6", features = ["unstable-dynamic"] }
 rpassword = "7"
 async-trait = "0.1"
 futures = "0.3"
@@ -125,7 +125,7 @@ The documentation is in [`docs/`](docs/README.md) and on the
 | [Getting started](docs/GETTING_STARTED.md) | From installing to your first synced folder |
 | [User guide](docs/USER_GUIDE.md) | Everything the app, tray and launcher do |
 | [FAQ](docs/FAQ.md) | Short answers to common questions |
-| [Command-line reference](docs/CLI.md) | Every `pdfs` command and scripting with `--json` |
+| [Command-line reference](docs/CLI.md) | Every `pdfs` command, Tab completion and scripting with `--json` |
 | [Configuration](docs/CONFIGURATION.md) | `config.json`, file locations, environment variables, the service |
 | [Troubleshooting](docs/TROUBLESHOOTING.md) | Diagnosing problems and fixing common ones |
 | [Recovering on a new computer](docs/RECOVERY.md) | Getting your synced folders back after a reinstall or a lost machine |
@@ -21,6 +21,7 @@ anyhow.workspace = true
 tracing.workspace = true
 tracing-subscriber.workspace = true
 clap.workspace = true
+clap_complete.workspace = true
 rpassword.workspace = true
 serde_json.workspace = true
 zeroize.workspace = true
@@ -0,0 +1,731 @@
+//! Shell completion for `pdfs`.
+//!
+//! Built on clap_complete's dynamic engine: the script a shell loads is a thin
+//! stub that calls `pdfs` back on every Tab with the words typed so far, and
+//! `pdfs` answers from its own clap definition. That lets an argument complete
+//! from the running service as well as from the command tree — `pdfs sync rm
+//! <Tab>` offers the synced-folder ids with their paths, `pdfs pin Doc<Tab>`
+//! walks My files.
+//!
+//! Every value that comes from the service is best effort. With no service, a
+//! slow one or an error, a completer offers nothing: a Tab that hangs or prints
+//! an error into the prompt is worse than one that does nothing.
+//!
+//! The engine sits behind clap_complete's `unstable-dynamic` feature, so all of
+//! this crate's use of it is kept to this module.
+
+use std::ffi::{OsStr, OsString};
+use std::path::{Path, PathBuf};
+use std::time::Duration;
+
+use clap::CommandFactory;
+use clap_complete::engine::{CompletionCandidate, PathCompleter, ValueCompleter};
+use clap_complete::env::{Bash, CompleteEnv, Elvish, EnvCompleter, Fish, Powershell, Zsh};
+use pdfs_core::control::{
+    AlbumInfo, BookmarkInfo, ConflictInfo, DeviceInfo, DirEntry, InvitationInfo, PendingOpInfo,
+    PublicLinkInfo, Request, Response, RevisionInfo, ShareEntry, ShareEntryKind, SyncFolderInfo,
+};
+
+/// The environment variable that turns a run of `pdfs` into a completion
+/// request. Not clap's generic `COMPLETE`: the same binary is the systemd
+/// daemon, and an unrelated `COMPLETE` in its environment must not stop it.
+pub const VAR: &str = "PDFS_COMPLETE";
+
+/// How long a completer waits for the service. A Tab is interactive, so a
+/// listing the service cannot give soon is better skipped. Long enough for the
+/// listings that ask Proton (computers take over a second).
+const SERVICE_TIMEOUT: Duration = Duration::from_secs(2);
+
+/// How long a listing that asks Proton is reused. Every Tab is a new `pdfs`, so
+/// without it `pdfs devices rm <Tab>`, a letter and another Tab would wait for
+/// Proton twice. A uid that went away in the meantime only fails the command.
+const CACHE_TTL: Duration = Duration::from_secs(30);
+
+/// Answer a completion request and exit, if this run is one. Must run before
+/// anything writes to stdout.
+pub fn handle_request() {
+    CompleteEnv::with_factory(crate::Cli::command)
+        .var(VAR)
+        .complete();
+}
+
+/// The shells `pdfs completions` writes a script for.
+#[derive(Clone, Copy, clap::ValueEnum)]
+pub enum ShellArg {
+    Bash,
+    Zsh,
+    Fish,
+    Elvish,
+    Powershell,
+}
+
+impl ShellArg {
+    fn completer(self) -> &'static dyn EnvCompleter {
+        match self {
+            ShellArg::Bash => &Bash,
+            ShellArg::Zsh => &Zsh,
+            ShellArg::Fish => &Fish,
+            ShellArg::Elvish => &Elvish,
+            ShellArg::Powershell => &Powershell,
+        }
+    }
+}
+
+/// Write the script that registers `pdfs` completion with `shell`.
+///
+/// The script calls `pdfs` from `PATH`, not this binary's path, so one written
+/// at packaging time keeps working once installed.
+pub fn write_script(shell: ShellArg, out: &mut dyn std::io::Write) -> std::io::Result<()> {
+    shell
+        .completer()
+        .write_registration(VAR, "pdfs", "pdfs", "pdfs", out)?;
+    if let ShellArg::Zsh = shell {
+        // Installed as `_pdfs` in site-functions, the script is autoloaded as
+        // that function's body on the first Tab. The body above only defines
+        // and registers the completer, so this line also runs it, or the first
+        // Tab would complete nothing. Sourced, `funcstack` names no `_pdfs`.
+        writeln!(
+            out,
+            "if [ \"$funcstack[1]\" = \"_pdfs\" ]; then\n    _clap_dynamic_completer_pdfs \"$@\"\nfi"
+        )?;
+    }
+    Ok(())
+}
+
+// ---------------------------------------------------------------------------
+// Talking to the service
+
+/// One request to the service, or `None` if there is no answer worth showing.
+fn ask(request: Request) -> Option<Response> {
+    let socket = pdfs_core::config::AppDirs::new().ok()?.control_socket();
+    ask_at(&socket, &request)
+}
+
+fn ask_at(socket: &Path, request: &Request) -> Option<Response> {
+    match pdfs_core::control::send_with_timeout(socket, request, SERVICE_TIMEOUT) {
+        Ok(Response::Error { .. }) | Err(_) => None,
+        Ok(response) => Some(response),
+    }
+}
+
+/// [`ask`] for a listing that comes from Proton rather than the local
+/// database, reusing an answer younger than [`CACHE_TTL`]. `key` names the
+/// listing's cache file.
+fn ask_cached(key: &str, request: Request) -> Option<Response> {
+    let file = cache_file(key);
+    if let Some(hit) = file.as_deref().and_then(read_fresh) {
+        return Some(hit);
+    }
+    let response = ask(request)?;
+    if let Some(file) = &file {
+        write_cache(file, &response);
+    }
+    Some(response)
+}
+
+/// In `$XDG_RUNTIME_DIR`: private to the user, in memory and gone at logout,
+/// which suits names from the account. With no runtime dir, nothing is cached.
+fn cache_file(key: &str) -> Option<PathBuf> {
+    let runtime = PathBuf::from(std::env::var_os("XDG_RUNTIME_DIR")?);
+    Some(
+        runtime
+            .join("proton-drive-linux")
+            .join(format!("completion-{key}.json")),
+    )
+}
+
+fn read_fresh(file: &Path) -> Option<Response> {
+    let age = std::fs::metadata(file)
+        .ok()?
+        .modified()
+        .ok()?
+        .elapsed()
+        .ok()?;
+    if age > CACHE_TTL {
+        return None;
+    }
+    serde_json::from_slice(&std::fs::read(file).ok()?).ok()
+}
+
+/// Best effort: a cache that cannot be written only costs the next Tab a wait.
+fn write_cache(file: &Path, response: &Response) {
+    use std::os::unix::fs::{DirBuilderExt, OpenOptionsExt};
+
+    let (Some(dir), Ok(json)) = (file.parent(), serde_json::to_vec(response)) else {
+        return;
+    };
+    let _ = std::fs::DirBuilder::new()
+        .recursive(true)
+        .mode(0o700)
+        .create(dir);
+    let staging = file.with_extension(format!("{}.tmp", std::process::id()));
+    let written = std::fs::OpenOptions::new()
+        .write(true)
+        .create_new(true)
+        .mode(0o600)
+        .open(&staging)
+        .and_then(|mut f| std::io::Write::write_all(&mut f, &json));
+    if written.is_err() || std::fs::rename(&staging, file).is_err() {
+        let _ = std::fs::remove_file(&staging);
+    }
+}
+
+fn candidate(value: impl Into<OsString>, help: impl Into<String>) -> CompletionCandidate {
+    let help = help.into();
+    let candidate = CompletionCandidate::new(value);
+    if help.is_empty() {
+        candidate
+    } else {
+        candidate.help(Some(help.into()))
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Paths in Proton Drive
+
+/// A path in the mount: an absolute path completes from the local filesystem
+/// (through the mount), anything else from the service's listing of My files,
+/// which is what the commands resolve a relative path against.
+pub fn drive_path(current: &OsStr) -> Vec<CompletionCandidate> {
+    complete_drive(current, false)
+}
+
+/// [`drive_path`] for an argument that must be a folder.
+pub fn drive_dir(current: &OsStr) -> Vec<CompletionCandidate> {
+    complete_drive(current, true)
+}
+
+/// `pdfs refresh`: a folder, or one of the two named caches.
+pub fn refresh_target(current: &OsStr) -> Vec<CompletionCandidate> {
+    let typed = current.to_string_lossy();
+    let mut candidates: Vec<_> = [
+        ("trash", "the trash listing"),
+        ("photos", "the photos timeline"),
+    ]
+    .into_iter()
+    .filter(|(name, _)| name.starts_with(typed.as_ref()))
+    .map(|(name, help)| candidate(name, help))
+    .collect();
+    candidates.extend(drive_dir(current));
+    candidates
+}
+
+fn complete_drive(current: &OsStr, dirs_only: bool) -> Vec<CompletionCandidate> {
+    let Some(word) = current.to_str() else {
+        return Vec::new();
+    };
+    if word.starts_with('/') || word.starts_with('~') {
+        let local = if dirs_only {
+            PathCompleter::dir()
+        } else {
+            PathCompleter::any()
+        };
+        return local.complete(current);
+    }
+    let (parent, prefix) = split_drive_word(word);
+    let listing = Request::ListDir {
+        path: parent.trim_end_matches('/').to_owned(),
+    };
+    match ask(listing) {
+        Some(Response::Entries { entries }) => {
+            drive_candidates(parent, prefix, &entries, dirs_only)
+        }
+        _ => Vec::new(),
+    }
+}
+
+/// Split a typed drive path into the folder to list (with its trailing `/`)
+/// and the start of the name being completed in it.
+fn split_drive_word(word: &str) -> (&str, &str) {
+    match word.rfind('/') {
+        Some(at) => word.split_at(at + 1),
+        None => ("", word),
+    }
+}
+
+/// The entries of `parent` whose name starts with `prefix`. A folder ends in
+/// `/`, which tells every shell not to add a space after it, so the next Tab
+/// goes on into it.
+fn drive_candidates(
+    parent: &str,
+    prefix: &str,
+    entries: &[DirEntry],
+    dirs_only: bool,
+) -> Vec<CompletionCandidate> {
+    entries
+        .iter()
+        .filter(|e| e.name.starts_with(prefix) && (e.is_dir || !dirs_only))
+        .map(|e| {
+            let slash = if e.is_dir { "/" } else { "" };
+            CompletionCandidate::new(format!("{parent}{}{slash}", e.name))
+                .hide(e.name.starts_with('.') && !prefix.starts_with('.'))
+        })
+        .collect()
+}
+
+// ---------------------------------------------------------------------------
+// Ids and uids from the service's listings
+
+pub fn sync_folder_id() -> Vec<CompletionCandidate> {
+    match ask(Request::ListSyncFolders) {
+        Some(Response::SyncFolders { items }) => sync_folder_candidates(&items),
+        _ => Vec::new(),
+    }
+}
+
+fn sync_folder_candidates(items: &[SyncFolderInfo]) -> Vec<CompletionCandidate> {
+    items
+        .iter()
+        .map(|f| candidate(f.id.to_string(), format!("{} ({})", f.local_path, f.mode)))
+        .collect()
+}
+
+pub fn queue_id() -> Vec<CompletionCandidate> {
+    match ask(Request::ListPendingOps) {
+        Some(Response::PendingOps { items }) => queue_candidates(&items),
+        _ => Vec::new(),
+    }
+}
+
+fn queue_candidates(items: &[PendingOpInfo]) -> Vec<CompletionCandidate> {
+    items
+        .iter()
+        .map(|op| candidate(op.id.to_string(), format!("{} {}", op.kind, op.path)))
+        .collect()
+}
+
+pub fn device_uid() -> Vec<CompletionCandidate> {
+    match ask_cached("devices", Request::ListDevices) {
+        Some(Response::Devices { items }) => device_candidates(&items),
+        _ => Vec::new(),
+    }
+}
+
+fn device_candidates(items: &[DeviceInfo]) -> Vec<CompletionCandidate> {
+    items
+        .iter()
+        .map(|d| {
+            let this = if d.this_device {
+                " (this computer)"
+            } else {
+                ""
+            };
+            candidate(d.uid.as_str(), format!("{}{this}", d.name))
+        })
+        .collect()
+}
+
+pub fn trash_uid() -> Vec<CompletionCandidate> {
+    match ask_cached("trash", Request::ListTrash) {
+        Some(Response::Entries { entries }) => trash_candidates(&entries),
+        _ => Vec::new(),
+    }
+}
+
+fn trash_candidates(entries: &[DirEntry]) -> Vec<CompletionCandidate> {
+    entries
+        .iter()
+        .map(|e| {
+            let help = match e.trashed_from.as_deref() {
+                Some(from) if !from.is_empty() => format!("{} (from {from})", e.name),
+                _ => e.name.clone(),
+            };
+            candidate(e.uid.as_str(), help)
+        })
+        .collect()
+}
+
+pub fn album_uid() -> Vec<CompletionCandidate> {
+    match ask_cached("albums", Request::PhotoAlbums) {
+        Some(Response::Albums { items, .. }) => album_candidates(&items),
+        _ => Vec::new(),
+    }
+}
+
+fn album_candidates(items: &[AlbumInfo]) -> Vec<CompletionCandidate> {
+    items
+        .iter()
+        .map(|a| candidate(a.uid.as_str(), a.name.as_str()))
+        .collect()
+}
+
+pub fn shared_uid() -> Vec<CompletionCandidate> {
+    match ask_cached("shared-with-me", Request::ListSharedWithMe) {
+        Some(Response::Entries { entries }) => shared_candidates(&entries),
+        _ => Vec::new(),
+    }
+}
+
+fn shared_candidates(entries: &[DirEntry]) -> Vec<CompletionCandidate> {
+    entries
+        .iter()
+        .map(|e| {
+            let help = if e.shared_by.is_empty() {
+                e.name.clone()
+            } else {
+                format!("{} (from {})", e.name, e.shared_by)
+            };
+            candidate(e.uid.as_str(), help)
+        })
+        .collect()
+}
+
+pub fn invitation_id() -> Vec<CompletionCandidate> {
+    match ask_cached("invitations", Request::ListInvitations) {
+        Some(Response::Invitations { items }) => invitation_candidates(&items),
+        _ => Vec::new(),
+    }
+}
+
+fn invitation_candidates(items: &[InvitationInfo]) -> Vec<CompletionCandidate> {
+    items
+        .iter()
+        .map(|i| {
+            let help = match i.name.as_deref() {
+                Some(name) => format!("{name} from {}", i.inviter_email),
+                None => format!("from {}", i.inviter_email),
+            };
+            candidate(i.id.as_str(), help)
+        })
+        .collect()
+}
+
+pub fn bookmark_token() -> Vec<CompletionCandidate> {
+    match ask_cached("bookmarks", Request::ListBookmarks) {
+        Some(Response::Bookmarks { items }) => bookmark_candidates(&items),
+        _ => Vec::new(),
+    }
+}
+
+fn bookmark_candidates(items: &[BookmarkInfo]) -> Vec<CompletionCandidate> {
+    items
+        .iter()
+        .map(|b| candidate(b.token.as_str(), b.name.as_deref().unwrap_or(&b.url)))
+        .collect()
+}
+
+pub fn conflict_path() -> Vec<CompletionCandidate> {
+    match ask(Request::ListConflicts) {
+        Some(Response::Conflicts { items }) => conflict_candidates(&items),
+        _ => Vec::new(),
+    }
+}
+
+fn conflict_candidates(items: &[ConflictInfo]) -> Vec<CompletionCandidate> {
+    items
+        .iter()
+        .map(|c| candidate(c.path.as_str(), format!("copy of {}", c.original_path)))
+        .collect()
+}
+
+// ---------------------------------------------------------------------------
+// Ids that belong to the path typed before them
+
+/// A version of the file named earlier on the line (`pdfs versions restore
+/// <path> <Tab>`).
+pub fn version_id(current: &OsStr) -> Vec<CompletionCandidate> {
+    let Some(path) = typed_path() else {
+        return Vec::new();
+    };
+    match ask(Request::ListRevisions { path }) {
+        Some(Response::Revisions { items }) => starting_with(current, revision_candidates(&items)),
+        _ => Vec::new(),
+    }
+}
+
+fn revision_candidates(items: &[RevisionInfo]) -> Vec<CompletionCandidate> {
+    items
+        .iter()
+        .map(|r| {
+            let current = if r.is_active { ", current" } else { "" };
+            let size = r.claimed_size.unwrap_or(r.size_on_storage).max(0);
+            candidate(
+                r.id.as_str(),
+                format!(
+                    "{}, {}{current}",
+                    crate::format_epoch_utc(r.created),
+                    crate::human_bytes(size as u64)
+                ),
+            )
+        })
+        .collect()
+}
+
+/// A member or invitation on the share of the path typed earlier on the line.
+pub fn share_entry_id(current: &OsStr) -> Vec<CompletionCandidate> {
+    match share_of_typed_path() {
+        Some((entries, _)) => starting_with(current, share_entry_candidates(&entries)),
+        None => Vec::new(),
+    }
+}
+
+fn share_entry_candidates(entries: &[ShareEntry]) -> Vec<CompletionCandidate> {
+    entries
+        .iter()
+        .map(|e| {
+            // The kind is the next argument, so the help names it in the words
+            // that argument takes.
+            let kind = match e.kind {
+                ShareEntryKind::Member => "member",
+                ShareEntryKind::ProtonInvite => "proton",
+                ShareEntryKind::ExternalInvite => "external",
+            };
+            candidate(e.id.as_str(), format!("{} ({}, {kind})", e.email, e.role))
+        })
+        .collect()
+}
+
+/// The public link of the path typed earlier on the line.
+pub fn public_link_id(current: &OsStr) -> Vec<CompletionCandidate> {
+    match share_of_typed_path() {
+        Some((_, Some(link))) => starting_with(current, vec![public_link_candidate(&link)]),
+        _ => Vec::new(),
+    }
+}
+
+/// Described without its URL: the fragment is the link's password, and a Tab
+/// menu is on screen for anyone watching.
+fn public_link_candidate(link: &PublicLinkInfo) -> CompletionCandidate {
+    let help = match link.expires {
+        Some(expires) => format!(
+            "{} link, expires {}",
+            link.role,
+            crate::format_epoch_utc(expires)
+        ),
+        None => format!("{} link", link.role),
+    };
+    candidate(link.id.as_str(), help)
+}
+
+fn share_of_typed_path() -> Option<(Vec<ShareEntry>, Option<PublicLinkInfo>)> {
+    match ask(Request::ListShare {
+        path: typed_path()?,
+    })? {
+        Response::Share { entries, link } => Some((entries, link)),
+        _ => None,
+    }
+}
+
+/// [`clap_complete::engine::ArgValueCompleter`] candidates are not filtered by
+/// the engine, unlike [`clap_complete::engine::ArgValueCandidates`].
+fn starting_with(
+    current: &OsStr,
+    candidates: Vec<CompletionCandidate>,
+) -> Vec<CompletionCandidate> {
+    let typed = current.to_string_lossy();
+    candidates
+        .into_iter()
+        .filter(|c| c.get_value().to_string_lossy().starts_with(typed.as_ref()))
+        .collect()
+}
+
+/// The `path` argument of the command being completed, as the service takes
+/// it. A completer only receives the word under the cursor, so this reads the
+/// line from the process arguments, where the shell's stub passes it.
+fn typed_path() -> Option<String> {
+    let args: Vec<OsString> = std::env::args_os().collect();
+    let index = std::env::var("_CLAP_COMPLETE_INDEX")
+        .ok()
+        .and_then(|i| i.parse().ok());
+    path_in(words_before_cursor(&args, index))
+}
+
+/// The words of the line before the one being completed. The stub runs
+/// `pdfs -- <words>`; bash, zsh and elvish say which word the cursor is on,
+/// fish and PowerShell pass the line cut at the cursor, so it is the last.
+fn words_before_cursor(args: &[OsString], index: Option<usize>) -> Vec<OsString> {
+    let start = args
+        .iter()
+        .position(|a| a == "--")
+        .map_or(args.len(), |at| at + 1);
+    let mut words = args[start..].to_vec();
+    let index = index.unwrap_or(words.len().saturating_sub(1));
+    words.truncate(index);
+    words
+}
+
+/// Parse `words` as far as they go and take the innermost command's `path`.
+fn path_in(words: Vec<OsString>) -> Option<String> {
+    let matches = crate::Cli::command()
+        .ignore_errors(true)
+        .try_get_matches_from(words)
+        .ok()?;
+    let mut leaf = &matches;
+    while let Some((_, sub)) = leaf.subcommand() {
+        leaf = sub;
+    }
+    let path = leaf.try_get_one::<PathBuf>("path").ok().flatten()?;
+    crate::path_arg(path).ok()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn values(candidates: &[CompletionCandidate]) -> Vec<String> {
+        candidates
+            .iter()
+            .map(|c| c.get_value().to_string_lossy().into_owned())
+            .collect()
+    }
+
+    fn help(candidate: &CompletionCandidate) -> String {
+        candidate
+            .get_help()
+            .map(ToString::to_string)
+            .unwrap_or_default()
+    }
+
+    fn entry(name: &str, is_dir: bool) -> DirEntry {
+        serde_json::from_value(serde_json::json!({
+            "name": name,
+            "is_dir": is_dir,
+            "size": 0,
+            "modified": 0,
+            "pinned": false,
+            "uid": format!("vol~{name}"),
+        }))
+        .unwrap()
+    }
+
+    fn words(line: &[&str]) -> Vec<OsString> {
+        line.iter().map(OsString::from).collect()
+    }
+
+    #[test]
+    fn the_command_definition_is_valid() {
+        crate::Cli::command().debug_assert();
+    }
+
+    #[test]
+    fn completions_script_is_written_for_every_shell() {
+        for shell in [
+            ShellArg::Bash,
+            ShellArg::Zsh,
+            ShellArg::Fish,
+            ShellArg::Elvish,
+            ShellArg::Powershell,
+        ] {
+            let mut script = Vec::new();
+            write_script(shell, &mut script).unwrap();
+            let script = String::from_utf8(script).unwrap();
+            assert!(script.contains(VAR), "{script}");
+            assert!(script.contains("pdfs"), "{script}");
+        }
+    }
+
+    #[test]
+    fn drive_path_splits_parent_and_prefix() {
+        assert_eq!(split_drive_word(""), ("", ""));
+        assert_eq!(split_drive_word("Doc"), ("", "Doc"));
+        assert_eq!(split_drive_word("Documents/"), ("Documents/", ""));
+        assert_eq!(split_drive_word("Documents/Rep"), ("Documents/", "Rep"));
+        assert_eq!(split_drive_word("a/b/c"), ("a/b/", "c"));
+    }
+
+    #[test]
+    fn drive_dirs_end_in_a_slash() {
+        let entries = [
+            entry("Reports", true),
+            entry("Receipt.pdf", false),
+            entry("Other", true),
+        ];
+        let all = drive_candidates("Documents/", "Re", &entries, false);
+        assert_eq!(
+            values(&all),
+            ["Documents/Reports/", "Documents/Receipt.pdf"]
+        );
+        let dirs = drive_candidates("Documents/", "", &entries, true);
+        assert_eq!(values(&dirs), ["Documents/Reports/", "Documents/Other/"]);
+    }
+
+    #[test]
+    fn hidden_drive_entries_need_a_typed_dot() {
+        let entries = [entry(".git", true)];
+        assert!(drive_candidates("", "", &entries, false)[0].is_hide_set());
+        assert!(!drive_candidates("", ".", &entries, false)[0].is_hide_set());
+    }
+
+    #[test]
+    fn sync_folder_ids_complete_with_their_local_path() {
+        let folders: Vec<SyncFolderInfo> = serde_json::from_value(serde_json::json!([{
+            "id": 3,
+            "local_path": "/home/me/Documents",
+            "remote_uid": "vol~docs",
+            "mode": "mirror",
+            "state": "idle",
+            "last_sync": 0,
+        }]))
+        .unwrap();
+        let candidates = sync_folder_candidates(&folders);
+        assert_eq!(values(&candidates), ["3"]);
+        assert_eq!(help(&candidates[0]), "/home/me/Documents (mirror)");
+    }
+
+    #[test]
+    fn trash_uids_complete_with_their_name() {
+        let mut from_docs = entry("a.pdf", false);
+        from_docs.trashed_from = Some("Documents".into());
+        let candidates = trash_candidates(&[from_docs, entry("b", true)]);
+        assert_eq!(values(&candidates), ["vol~a.pdf", "vol~b"]);
+        assert_eq!(help(&candidates[0]), "a.pdf (from Documents)");
+        assert_eq!(help(&candidates[1]), "b");
+    }
+
+    #[test]
+    fn completer_without_a_service_offers_nothing() {
+        let dir = std::env::temp_dir().join(format!("pdfs-complete-{}", std::process::id()));
+        let socket = dir.join("control.sock");
+        assert!(ask_at(&socket, &Request::ListSyncFolders).is_none());
+    }
+
+    #[test]
+    fn cached_listing_is_reused_until_it_is_stale() {
+        let dir = std::env::temp_dir().join(format!("pdfs-complete-cache-{}", std::process::id()));
+        let file = dir.join("completion-devices.json");
+        write_cache(&file, &Response::Devices { items: Vec::new() });
+        assert!(matches!(read_fresh(&file), Some(Response::Devices { .. })));
+        let mode = std::os::unix::fs::PermissionsExt::mode(
+            &std::fs::metadata(&file).unwrap().permissions(),
+        );
+        assert_eq!(mode & 0o777, 0o600);
+
+        let stale = std::time::SystemTime::now() - CACHE_TTL - Duration::from_secs(1);
+        std::fs::File::options()
+            .write(true)
+            .open(&file)
+            .unwrap()
+            .set_modified(stale)
+            .unwrap();
+        assert!(read_fresh(&file).is_none());
+        std::fs::remove_dir_all(dir).unwrap();
+    }
+
+    #[test]
+    fn words_before_cursor_stop_at_the_cursor() {
+        let args = words(&[
+            "pdfs", "--", "pdfs", "versions", "restore", "a.txt", "", "x",
+        ]);
+        assert_eq!(
+            words_before_cursor(&args, Some(4)),
+            words(&["pdfs", "versions", "restore", "a.txt"])
+        );
+        // fish: the line arrives cut at the cursor, the current word last.
+        let fish = words(&["pdfs", "--", "pdfs", "versions", "restore", "a.txt", "ab"]);
+        assert_eq!(
+            words_before_cursor(&fish, None),
+            words(&["pdfs", "versions", "restore", "a.txt"])
+        );
+    }
+
+    #[test]
+    fn completing_words_finds_the_path_before_the_id() {
+        let line = words(&["pdfs", "versions", "restore", "Documents/a.txt"]);
+        assert_eq!(path_in(line).as_deref(), Some("Documents/a.txt"));
+        let line = words(&["pdfs", "--json", "share-role", "Shared/x"]);
+        assert_eq!(path_in(line).as_deref(), Some("Shared/x"));
+        let line = words(&["pdfs", "public-link", "update", "--role", "editor", "a"]);
+        assert_eq!(path_in(line).as_deref(), Some("a"));
+        assert_eq!(path_in(words(&["pdfs", "versions", "restore"])), None);
+    }
+}
@@ -8,7 +8,8 @@ use std::path::{Path, PathBuf};
 use std::sync::Arc;

 use anyhow::{Context, Result, anyhow, bail};
-use clap::{Parser, Subcommand};
+use clap::{Parser, Subcommand, ValueHint};
+use clap_complete::engine::{ArgValueCandidates, ArgValueCompleter};
 use pdfs_core::auth;
 use pdfs_core::cache::ContentCache;
 use pdfs_core::config::AppDirs;
@@ -20,6 +21,7 @@ use pdfs_core::control::{
 use pdfs_core::db::Db;
 use pdfs_core::service;

+mod complete;
 mod journal;

 /// `println!` for this binary, shadowing std's, which panics when stdout is
@@ -165,6 +167,7 @@ enum Command {
    /// Mount Proton Drive at the given (or default) path. Blocks until unmounted.
    Mount {
        /// Mountpoint; defaults to ~/ProtonDrive.
+        #[arg(value_hint = ValueHint::DirPath)]
        mountpoint: Option<PathBuf>,
    },
    /// Run the auto-mount daemon: wait for login, mount, and keep it mounted
@@ -172,6 +175,7 @@ enum Command {
    /// don't invoke it by hand.
    Daemon {
        /// Mountpoint; defaults to ~/ProtonDrive.
+        #[arg(value_hint = ValueHint::DirPath)]
        mountpoint: Option<PathBuf>,
    },
    /// Keep a file or folder on this device (download + cache it). A folder's
@@ -179,11 +183,13 @@ enum Command {
    /// Needs a running mount.
    Pin {
        /// File or folder path, inside the mountpoint or relative to it.
+        #[arg(add = ArgValueCompleter::new(complete::drive_path))]
        path: PathBuf,
    },
    /// Stop keeping a file or folder on this device, evicting its cached content.
    Unpin {
        /// File or folder path, inside the mountpoint or relative to it.
+        #[arg(add = ArgValueCompleter::new(complete::drive_path))]
        path: PathBuf,
    },
    /// List files and folders pinned to this device.
@@ -191,6 +197,7 @@ enum Command {
    /// List a directory via the running daemon (in-app browser backend).
    Ls {
        /// Directory path, inside the mountpoint or relative to it. Root if omitted.
+        #[arg(add = ArgValueCompleter::new(complete::drive_dir))]
        path: Option<PathBuf>,
    },
    /// List the photos timeline (newest first) via the running daemon.
@@ -224,7 +231,7 @@ enum Command {
    /// so an interrupted import can simply be run again.
    ImportGooglePhotos {
        /// The export's `.zip` files (e.g. `takeout-*.zip`).
-        #[arg(required = true)]
+        #[arg(required = true, value_hint = ValueHint::FilePath)]
        archives: Vec<PathBuf>,
        /// Report what would be imported without uploading anything.
        #[arg(long)]
@@ -277,6 +284,7 @@ enum Command {
    /// List the photos in one album (newest capture first).
    Album {
        /// Album node uid in `volume~link` form (from `pdfs albums`).
+        #[arg(add = ArgValueCandidates::new(complete::album_uid))]
        uid: String,
        /// Max photos to list.
        #[arg(long, default_value_t = 50)]
@@ -293,6 +301,7 @@ enum Command {
    /// Rename a photo album.
    RenameAlbum {
        /// Album node uid in `volume~link` form (from `pdfs albums`).
+        #[arg(add = ArgValueCandidates::new(complete::album_uid))]
        uid: String,
        /// New name.
        name: String,
@@ -300,6 +309,7 @@ enum Command {
    /// Delete a photo album. Its photos stay in the timeline.
    DeleteAlbum {
        /// Album node uid in `volume~link` form (from `pdfs albums`).
+        #[arg(add = ArgValueCandidates::new(complete::album_uid))]
        uid: String,
        /// Also delete photos that exist only in this album (saved from a
        /// shared album); without it the server refuses to delete such an album.
@@ -309,6 +319,7 @@ enum Command {
    /// Add photos to an album.
    AddToAlbum {
        /// Album node uid in `volume~link` form (from `pdfs albums`).
+        #[arg(add = ArgValueCandidates::new(complete::album_uid))]
        uid: String,
        /// Photo node uids (from `pdfs photos`).
        #[arg(required = true)]
@@ -317,6 +328,7 @@ enum Command {
    /// Take photos out of an album. They stay in the timeline.
    RemoveFromAlbum {
        /// Album node uid in `volume~link` form (from `pdfs albums`).
+        #[arg(add = ArgValueCandidates::new(complete::album_uid))]
        uid: String,
        /// Photo node uids (from `pdfs album <uid>`).
        #[arg(required = true)]
@@ -335,13 +347,14 @@ enum Command {
        #[arg(long, default_value_t = 50)]
        limit: usize,
        /// Only search below this folder (under the mountpoint).
-        #[arg(long = "in", value_name = "FOLDER")]
+        #[arg(long = "in", value_name = "FOLDER", add = ArgValueCompleter::new(complete::drive_dir))]
        scope: Option<PathBuf>,
    },
    /// Rename a file or folder via the running daemon.
    Rename {
        /// File/folder path, inside My files or an on-demand synced folder, or
        /// relative to the mountpoint.
+        #[arg(add = ArgValueCompleter::new(complete::drive_path))]
        path: PathBuf,
        /// New name (a single path component).
        new_name: String,
@@ -355,7 +368,7 @@ enum Command {
    Move {
        /// Files/folders to move, then the destination folder: each inside a
        /// location, or relative to the mountpoint.
-        #[arg(required = true, num_args = 2.., value_name = "PATH")]
+        #[arg(required = true, num_args = 2.., value_name = "PATH", add = ArgValueCompleter::new(complete::drive_path))]
        paths: Vec<PathBuf>,
    },
    /// Copy files or folders into another folder in My files via the running
@@ -367,7 +380,7 @@ enum Command {
    Copy {
        /// Files/folders to copy, then the destination folder: inside My files,
        /// or relative to the mountpoint.
-        #[arg(required = true, num_args = 2.., value_name = "PATH")]
+        #[arg(required = true, num_args = 2.., value_name = "PATH", add = ArgValueCompleter::new(complete::drive_path))]
        paths: Vec<PathBuf>,
    },
    /// Show how much a folder holds on Proton Drive.
@@ -376,18 +389,21 @@ enum Command {
    /// encrypted bytes on storage and includes items in the trash.
    Du {
        /// Folder path, inside My files or relative to the mountpoint.
+        #[arg(add = ArgValueCompleter::new(complete::drive_dir))]
        path: PathBuf,
    },
    /// Trash a file or folder via the running daemon.
    Rm {
        /// File/folder path, inside My files or an on-demand synced folder, or
        /// relative to the mountpoint.
+        #[arg(add = ArgValueCompleter::new(complete::drive_path))]
        path: PathBuf,
    },
    /// Create a folder via the running daemon.
    Mkdir {
        /// Parent folder path, inside My files or an on-demand synced folder,
        /// or relative to the mountpoint.
+        #[arg(add = ArgValueCompleter::new(complete::drive_dir))]
        parent: PathBuf,
        /// New folder name (a single path component).
        name: String,
@@ -397,10 +413,10 @@ enum Command {
    /// background; watch progress with `pdfs transfers`.
    Upload {
        /// Local files and/or folders to upload.
-        #[arg(required = true)]
+        #[arg(required = true, value_hint = ValueHint::AnyPath)]
        sources: Vec<PathBuf>,
        /// Destination folder, inside the mountpoint or relative to it.
-        #[arg(short = 't', long = "to", default_value = ".")]
+        #[arg(short = 't', long = "to", default_value = ".", add = ArgValueCompleter::new(complete::drive_dir))]
        parent: PathBuf,
    },
    /// Show the daemon's in-flight transfers (active uploads/downloads).
@@ -415,13 +431,13 @@ enum Command {
    /// Restore trashed items, by uid, to the folders they were trashed from.
    Restore {
        /// Node uids (`volume~link`), as printed by `pdfs trash`.
-        #[arg(required = true)]
+        #[arg(required = true, add = ArgValueCandidates::new(complete::trash_uid))]
        uids: Vec<String>,
    },
    /// Permanently delete trashed items by uid. This cannot be undone.
    DeleteForever {
        /// Node uids (`volume~link`), as printed by `pdfs trash`.
-        #[arg(required = true)]
+        #[arg(required = true, add = ArgValueCandidates::new(complete::trash_uid))]
        uids: Vec<String>,
    },
    /// Permanently delete everything in the trash. This cannot be undone.
@@ -433,6 +449,7 @@ enum Command {
    Refresh {
        /// What to refresh: a folder path (inside the mountpoint or relative to
        /// it), `trash`, or `photos`. The mount root if omitted.
+        #[arg(add = ArgValueCompleter::new(complete::refresh_target))]
        target: Option<String>,
        /// With `photos`: read every photo's metadata again instead of only what
        /// changed. Minutes on a large library; for a gallery that disagrees with
@@ -459,12 +476,13 @@ enum Command {
    /// Share a file or folder with Proton and/or external email addresses.
    Share {
        /// File/folder path, inside the mountpoint or relative to it.
+        #[arg(add = ArgValueCompleter::new(complete::drive_path))]
        path: PathBuf,
        /// One or more invitee emails (Proton or external, auto-detected).
        #[arg(required = true)]
        emails: Vec<String>,
        /// Role to grant: viewer, editor or admin.
-        #[arg(long, default_value = "viewer")]
+        #[arg(long, default_value = "viewer", value_parser = ["viewer", "editor", "admin"], ignore_case = true)]
        role: String,
        /// Optional message included in the invitation email.
        #[arg(long)]
@@ -473,17 +491,21 @@ enum Command {
    /// List a node's members, pending invitations and public link.
    Members {
        /// File/folder path, inside the mountpoint or relative to it.
+        #[arg(add = ArgValueCompleter::new(complete::drive_path))]
        path: PathBuf,
    },
    /// Change the role of a member or pending invitation on a node's share.
    ShareRole {
        /// File/folder path, inside the mountpoint or relative to it.
+        #[arg(add = ArgValueCompleter::new(complete::drive_path))]
        path: PathBuf,
        /// Entry id (membership or invitation id), from `pdfs members`.
+        #[arg(add = ArgValueCompleter::new(complete::share_entry_id))]
        id: String,
        /// Entry kind: member, proton or external.
        kind: ShareKindArg,
        /// New role: viewer, editor or admin.
+        #[arg(value_parser = ["viewer", "editor", "admin"], ignore_case = true)]
        role: String,
    },
    /// Stop sharing a node, or remove one member or pending invitation.
@@ -492,9 +514,10 @@ enum Command {
    /// member. With an id and kind (from `pdfs members`), removes that entry.
    Unshare {
        /// File/folder path, inside the mountpoint or relative to it.
+        #[arg(add = ArgValueCompleter::new(complete::drive_path))]
        path: PathBuf,
        /// Entry id (membership or invitation id), from `pdfs members`.
-        #[arg(requires = "kind")]
+        #[arg(requires = "kind", add = ArgValueCompleter::new(complete::share_entry_id))]
        id: Option<String>,
        /// Entry kind: member, proton or external.
        kind: Option<ShareKindArg>,
@@ -515,18 +538,22 @@ enum Command {
    SharedWithMe {
        /// Folder uid to list into, in `volume~link` form (from a previous run).
        /// Omit for the top level.
+        #[arg(add = ArgValueCandidates::new(complete::shared_uid))]
        uid: Option<String>,
    },
    /// Download a file shared with me by its uid (from `pdfs shared-with-me`).
    SharedGet {
        /// Node uid in `volume~link` form.
+        #[arg(add = ArgValueCandidates::new(complete::shared_uid))]
        uid: String,
        /// Where to write it. Omit to leave it in the cache and print the path.
+        #[arg(value_hint = ValueHint::AnyPath)]
        dest: Option<PathBuf>,
    },
    /// Leave a shared node by its uid (from `pdfs shared-with-me`).
    Leave {
        /// Node uid in `volume~link` form.
+        #[arg(add = ArgValueCandidates::new(complete::shared_uid))]
        uid: String,
    },
    /// Manage invitations addressed to me.
@@ -557,6 +584,17 @@ enum Command {
    /// Runs without a daemon on purpose: the state worth diagnosing is usually
    /// the state where the daemon will not start.
    Diagnose,
+    /// Print the shell completion script for bash, zsh, fish, elvish or
+    /// PowerShell.
+    ///
+    /// Besides commands and options, it completes values from the running
+    /// service: paths in My files, synced-folder and queue ids, computers,
+    /// trash, albums, shares and versions. Load it with, for example,
+    /// `pdfs completions fish | source` or `source <(pdfs completions bash)`.
+    Completions {
+        /// The shell to write the script for.
+        shell: complete::ShellArg,
+    },
 }

 #[derive(Subcommand)]
@@ -604,6 +642,7 @@ enum VersionCmd {
    /// List a file's versions, newest first.
    List {
        /// File path, inside the mountpoint or relative to it.
+        #[arg(add = ArgValueCompleter::new(complete::drive_path))]
        path: PathBuf,
    },
    /// Make an earlier version the file's current content.
@@ -612,25 +651,32 @@ enum VersionCmd {
    /// moment to show up in the mount.
    Restore {
        /// File path, inside the mountpoint or relative to it.
+        #[arg(add = ArgValueCompleter::new(complete::drive_path))]
        path: PathBuf,
        /// Version id, from `pdfs versions list`.
+        #[arg(add = ArgValueCompleter::new(complete::version_id))]
        id: String,
    },
    /// Write an earlier version to a local file, leaving the file untouched.
    Save {
        /// File path, inside the mountpoint or relative to it.
+        #[arg(add = ArgValueCompleter::new(complete::drive_path))]
        path: PathBuf,
        /// Version id, from `pdfs versions list`.
+        #[arg(add = ArgValueCompleter::new(complete::version_id))]
        id: String,
        /// Where to write it. Must not already exist.
+        #[arg(value_hint = ValueHint::AnyPath)]
        dest: PathBuf,
    },
    /// Permanently delete an earlier version. The content is unrecoverable, and
    /// the version that is currently active cannot be deleted.
    Rm {
        /// File path, inside the mountpoint or relative to it.
+        #[arg(add = ArgValueCompleter::new(complete::drive_path))]
        path: PathBuf,
        /// Version id, from `pdfs versions list`.
+        #[arg(add = ArgValueCompleter::new(complete::version_id))]
        id: String,
    },
 }
@@ -640,13 +686,21 @@ enum DeviceCmd {
    /// List registered devices.
    List,
    /// Rename a device by uid.
-    Rename { uid: String, name: String },
+    Rename {
+        #[arg(add = ArgValueCandidates::new(complete::device_uid))]
+        uid: String,
+        name: String,
+    },
    /// Delete (deregister) a device by uid.
-    Rm { uid: String },
+    Rm {
+        #[arg(add = ArgValueCandidates::new(complete::device_uid))]
+        uid: String,
+    },
    /// Adopt an existing device as this machine's, so a hostname change or a
    /// reinstall re-attaches to it instead of registering a duplicate.
    Adopt {
        /// Device uid (from `devices list`). Omit with `--clear`.
+        #[arg(add = ArgValueCandidates::new(complete::device_uid))]
        uid: Option<String>,
        /// Drop the adoption and go back to matching by hostname.
        #[arg(long, conflicts_with = "uid")]
@@ -657,6 +711,7 @@ enum DeviceCmd {
    /// here. Both computers keep them in step.
    Join {
        /// Device uid (from `devices list`).
+        #[arg(add = ArgValueCandidates::new(complete::device_uid))]
        uid: String,
        /// Skip the confirmation and accept every proposed local path.
        #[arg(long)]
@@ -666,6 +721,7 @@ enum DeviceCmd {
    /// them here. The other computer stays registered, without those folders.
    Migrate {
        /// Device uid (from `devices list`).
+        #[arg(add = ArgValueCandidates::new(complete::device_uid))]
        uid: String,
        /// Skip the confirmation and accept every proposed local path.
        #[arg(long)]
@@ -678,6 +734,7 @@ enum ConflictCmd {
    /// Decide which side of a conflict to keep. Whatever is removed goes to Trash.
    Resolve {
        /// The conflict copy, absolute or relative to the mountpoint.
+        #[arg(add = ArgValueCandidates::new(complete::conflict_path))]
        path: PathBuf,
        /// `original` trashes the copy; `copy` trashes the original and gives the
        /// copy its name; `both` renames the copy to `--name`.
@@ -694,15 +751,17 @@ enum SyncCmd {
    /// Add a local folder to this machine's device and upload its contents.
    Add {
        /// Local directory to sync.
+        #[arg(value_hint = ValueHint::DirPath)]
        path: PathBuf,
    },
    /// Sync a real local folder with an existing folder in My files.
    /// The first pass preserves local-only files and keeps differing versions.
    Attach {
        /// Existing local directory; it remains a real local directory.
+        #[arg(value_hint = ValueHint::DirPath)]
        path: PathBuf,
        /// Existing folder in My files, relative to the cloud mount or inside it.
-        #[arg(long)]
+        #[arg(long, add = ArgValueCompleter::new(complete::drive_dir))]
        to: PathBuf,
    },
    /// List this machine's synced folders.
@@ -710,6 +769,7 @@ enum SyncCmd {
    /// Remove a synced folder by id.
    Rm {
        /// Synced-folder id (from `sync list`).
+        #[arg(add = ArgValueCandidates::new(complete::sync_folder_id))]
        id: i64,
        /// Also delete the folder's copy in Proton Drive.
        #[arg(long)]
@@ -718,6 +778,7 @@ enum SyncCmd {
    /// Force a sync pass now (all folders, or one by id).
    Now {
        /// Optional synced-folder id; omit to reconcile every folder.
+        #[arg(add = ArgValueCandidates::new(complete::sync_folder_id))]
        id: Option<i64>,
    },
    /// Forget what a synced folder synced before and compare it with Proton
@@ -725,6 +786,7 @@ enum SyncCmd {
    /// that differs keeps both versions. Nothing is deleted.
    Reset {
        /// Synced-folder id (from `sync list`).
+        #[arg(add = ArgValueCandidates::new(complete::sync_folder_id))]
        id: i64,
    },
    /// Pause syncing: queued uploads and mirror folders wait, reads keep working.
@@ -734,13 +796,13 @@ enum SyncCmd {
        #[arg(long = "for", value_parser = parse_pause_duration, conflicts_with = "folder")]
        duration: Option<u64>,
        /// Pause only this mirror folder (id from `sync list`) until resumed.
-        #[arg(long)]
+        #[arg(long, add = ArgValueCandidates::new(complete::sync_folder_id))]
        folder: Option<i64>,
    },
    /// Resume syncing after `pdfs sync pause`.
    Resume {
        /// Resume only this folder, paused with `sync pause --folder`.
-        #[arg(long)]
+        #[arg(long, add = ArgValueCandidates::new(complete::sync_folder_id))]
        folder: Option<i64>,
    },
    /// Cap upload and download speed, or show the caps with no options.
@@ -759,8 +821,10 @@ enum SyncCmd {
    /// Save the content of a queued upload (by id from `sync queue`) to a file.
    Export {
        /// Queue id.
+        #[arg(add = ArgValueCandidates::new(complete::queue_id))]
        id: i64,
        /// Where to save it: a new file, or an existing folder to save it in.
+        #[arg(value_hint = ValueHint::AnyPath)]
        dest: PathBuf,
    },
    /// Drop a queued change (by id from `sync queue`) and undo it here: a new file
@@ -768,6 +832,7 @@ enum SyncCmd {
    /// content is lost unless saved with `sync export` first.
    Discard {
        /// Queue id.
+        #[arg(add = ArgValueCandidates::new(complete::queue_id))]
        id: i64,
        /// Do not ask first.
        #[arg(long)]
@@ -776,11 +841,13 @@ enum SyncCmd {
    /// Retry a queued operation now (by id from `sync queue`), or every failed one.
    Retry {
        /// Queue id; omit to retry every failed operation.
+        #[arg(add = ArgValueCandidates::new(complete::queue_id))]
        id: Option<i64>,
    },
    /// Switch a folder between full-copy sync and on-demand (FUSE, no local storage).
    Mode {
        /// Synced-folder id (from `sync list`).
+        #[arg(add = ArgValueCandidates::new(complete::sync_folder_id))]
        id: i64,
        /// `mirror` (full local copy) or `ondemand` (FUSE mount, reclaims disk).
        #[arg(value_parser = ["mirror", "ondemand"])]
@@ -794,7 +861,7 @@ enum SyncCmd {
        yes: bool,
        /// Restore another computer's folders instead, by device uid (from
        /// `pdfs devices list`).
-        #[arg(long)]
+        #[arg(long, add = ArgValueCandidates::new(complete::device_uid))]
        device: Option<String>,
    },
 }
@@ -804,9 +871,10 @@ enum PublicLinkCmd {
    /// Create a public link on a node.
    Create {
        /// File/folder path, inside the mountpoint or relative to it.
+        #[arg(add = ArgValueCompleter::new(complete::drive_path))]
        path: PathBuf,
        /// Role: viewer or editor.
-        #[arg(long, default_value = "viewer")]
+        #[arg(long, default_value = "viewer", value_parser = ["viewer", "editor"], ignore_case = true)]
        role: String,
        /// Optional custom password protecting the link.
        #[arg(long)]
@@ -819,11 +887,13 @@ enum PublicLinkCmd {
    /// given is kept.
    Update {
        /// File/folder path, inside the mountpoint or relative to it.
+        #[arg(add = ArgValueCompleter::new(complete::drive_path))]
        path: PathBuf,
        /// Public-link id, from `pdfs members`.
+        #[arg(add = ArgValueCompleter::new(complete::public_link_id))]
        id: String,
        /// New role: viewer or editor.
-        #[arg(long)]
+        #[arg(long, value_parser = ["viewer", "editor"], ignore_case = true)]
        role: Option<String>,
        /// New custom password protecting the link.
        #[arg(long, conflicts_with = "no_password")]
@@ -841,8 +911,10 @@ enum PublicLinkCmd {
    /// Remove a node's public link.
    Remove {
        /// File/folder path, inside the mountpoint or relative to it.
+        #[arg(add = ArgValueCompleter::new(complete::drive_path))]
        path: PathBuf,
        /// Public-link id, from `pdfs members`.
+        #[arg(add = ArgValueCompleter::new(complete::public_link_id))]
        id: String,
    },
 }
@@ -852,9 +924,15 @@ enum InvitationCmd {
    /// List invitations addressed to me.
    List,
    /// Accept an invitation by id.
-    Accept { id: String },
+    Accept {
+        #[arg(add = ArgValueCandidates::new(complete::invitation_id))]
+        id: String,
+    },
    /// Reject an invitation by id.
-    Reject { id: String },
+    Reject {
+        #[arg(add = ArgValueCandidates::new(complete::invitation_id))]
+        id: String,
+    },
 }

 #[derive(Subcommand)]
@@ -870,7 +948,10 @@ enum BookmarkCmd {
        password: Option<String>,
    },
    /// Remove a saved bookmark by its token.
-    Rm { token: String },
+    Rm {
+        #[arg(add = ArgValueCandidates::new(complete::bookmark_token))]
+        token: String,
+    },
 }

 /// Render a daemon failure for a terminal.
@@ -890,6 +971,9 @@ fn cli_error(kind: ErrorKind, message: &str) -> String {
 }

 fn main() -> Result<()> {
+    // First: a completion request answers on stdout and exits, so nothing may
+    // write there before it.
+    complete::handle_request();
    let filter = tracing_subscriber::EnvFilter::try_from_default_env()
        // `pgp` logs a benign WARN when it re-serializes a Proton secret-key
        // packet with a longer (but equivalent) length encoding than the
@@ -1030,6 +1114,7 @@ fn main() -> Result<()> {
        Command::Activity { limit } => cmd_activity(limit),
        Command::Quota => cmd_quota(),
        Command::Cache { action } => cmd_cache(action),
+        Command::Completions { shell } => cmd_completions(shell),
        Command::Diagnose => cmd_diagnose(),
    }
 }
@@ -2520,7 +2605,10 @@ fn mount_once(mountpoint: Option<PathBuf>) -> Result<pdfs_fuse::MountOutcome> {
    // An explicit `--mountpoint` wins; otherwise honor the Settings-page choice
    // (config), falling back to the default location.
    let mountpoint = mountpoint.unwrap_or_else(|| dirs.resolved_mountpoint(&config));
-    std::fs::create_dir_all(&mountpoint)
+    // Hydrating a large account and remounting its folders can outlast the
+    // unit's watchdog before the supervisor sends its first ping (B279).
+    pdfs_fuse::stretch_watchdog_for_startup();
+    pdfs_fuse::prepare_mountpoint(&mountpoint)
        .with_context(|| format!("create mountpoint {}", mountpoint.display()))?;

    let username = auth::load().map(|s| s.username).unwrap_or_default();
@@ -3803,6 +3891,15 @@ fn writable_probe(dir: &Path) -> std::io::Result<()> {
    result.and(remove)
 }

+/// Print the completion script for `shell`. Touches no account state, so
+/// packaging can run it at build time.
+fn cmd_completions(shell: complete::ShellArg) -> Result<()> {
+    let mut script = Vec::new();
+    complete::write_script(shell, &mut script)?;
+    print!("{}", String::from_utf8_lossy(&script));
+    Ok(())
+}
+
 /// Self-check the installation, reporting each finding and exiting non-zero if
 /// any check failed.
 ///
@@ -2405,9 +2405,17 @@ impl Request {
 ///
 /// Shared by the CLI and GUI so both speak the wire format identically.
 pub fn send(socket: &Path, req: &Request) -> Result<Response> {
+    send_with_timeout(socket, req, req.read_timeout())
+}
+
+/// [`send`] with a caller-chosen limit on how long the daemon may take to
+/// answer, which also bounds the write. For a caller that must never keep a
+/// person waiting, such as shell completion, where a slow answer is worth less
+/// than none.
+pub fn send_with_timeout(socket: &Path, req: &Request, timeout: Duration) -> Result<Response> {
    let mut stream = UnixStream::connect(socket)?;
-    stream.set_read_timeout(Some(req.read_timeout()))?;
-    stream.set_write_timeout(Some(WRITE_TIMEOUT))?;
+    stream.set_read_timeout(Some(timeout))?;
+    stream.set_write_timeout(Some(timeout.min(WRITE_TIMEOUT)))?;
    let mut line = serde_json::to_vec(req)?;
    line.push(b'\n');
    stream.write_all(&line)?;
@@ -119,13 +119,14 @@ mod workers;
 use background::{forget_and_notify, run_event_sync, run_local_index, run_photos_event_sync};
 use link::BATCH_CALL_TIMEOUT;
 pub(crate) use mount::is_stale_mount;
+pub use mount::prepare_mountpoint;
 pub use mount::{MountOptions, MountOutcome, mount};
 use mount::{
    SecondaryInsertRejection, SecondaryMount, clear_stale_mount, fuse_connection_id, spawn_session,
 };
 use reads::{BlockFlight, BlockRing, PREFETCH_BUDGET, Prefetch, ReaderSlot, STREAM_BYPASS_MIN};
 use state::{Entry, Intervals, PendingRevision, State, StateGuard, WriteHandle};
-pub use systemd::{idle_sleep, status as notify_status};
+pub use systemd::{idle_sleep, status as notify_status, stretch_watchdog_for_startup};
 use tracing::{debug, error, info, warn};
 use transfers::{CountingWriter, JobGuard, OwnedCountingReader, TransferRegistry};
 use r#virtual::{
@@ -196,6 +196,20 @@ pub(super) fn clear_stale_mount(mountpoint: &Path) {
    }
 }

+/// Make sure `mountpoint` is a directory a mount can go on, clearing a dead
+/// mount a killed daemon left there first.
+///
+/// A dead mount answers `ENOTCONN`, which `create_dir_all` takes for "absent";
+/// it then tries `mkdir` and fails with `EEXIST`. The daemon retried that error
+/// forever and never got as far as [`check_mountpoint`], which would have
+/// cleared the mount (`docs/BUGS.md` B279).
+pub fn prepare_mountpoint(mountpoint: &Path) -> std::io::Result<()> {
+    if is_stale_mount(mountpoint) {
+        clear_stale_mount(mountpoint);
+    }
+    std::fs::create_dir_all(mountpoint)
+}
+
 /// Refuse to mount My files over a folder that already has files in it: FUSE
 /// would hide them, unsent and out of sight, until the service stops
 /// (`docs/BUGS.md` B277). Runs before the root fetch and before any worker
@@ -72,6 +72,105 @@ const UPLOAD_THUMB_QUALITIES: [u8; 4] = [65, 50, 35, 20];
 /// Largest still image read whole to render the thumbnail its upload carries.
 const UPLOAD_IMAGE_MAX_BYTES: u64 = 256 * 1024 * 1024;

+/// How much memory every thumbnail decode in the daemon may hold at once:
+/// the encoded file plus its decoded pixels.
+///
+/// Without a limit, each of the 16 drain workers decoded its own full-size
+/// photo. A batch of 100-megapixel JPEGs then held about 9 GiB, which swapped the
+/// machine until the watchdog killed the daemon, on every restart
+/// (`docs/BUGS.md` B280). With this budget, a phone photo still decodes beside
+/// several others, and a 100-megapixel one decodes alone.
+const DECODE_BUDGET_BYTES: u64 = 512 * 1024 * 1024;
+
+/// The process-wide [`DecodeBudget`] every thumbnail decode draws from.
+static DECODE_BUDGET: DecodeBudget = DecodeBudget::new(DECODE_BUDGET_BYTES);
+
+/// A counting gate over bytes: [`acquire`](Self::acquire) waits until the cost
+/// fits beside what is already held.
+struct DecodeBudget {
+    limit: u64,
+    used: std::sync::Mutex<u64>,
+    freed: std::sync::Condvar,
+}
+
+/// A share of a [`DecodeBudget`], given back on drop.
+struct DecodePermit<'a> {
+    budget: &'a DecodeBudget,
+    cost: u64,
+}
+
+impl DecodeBudget {
+    const fn new(limit: u64) -> Self {
+        Self {
+            limit,
+            used: std::sync::Mutex::new(0),
+            freed: std::sync::Condvar::new(),
+        }
+    }
+
+    /// Wait until `cost` bytes fit, and hold them. A cost above the limit is
+    /// cut down to the limit, so the largest image waits for an idle budget
+    /// and then runs alone, instead of waiting forever.
+    fn acquire(&self, cost: u64) -> DecodePermit<'_> {
+        let cost = cost.clamp(1, self.limit);
+        let mut used = self
+            .used
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        while *used + cost > self.limit {
+            used = self
+                .freed
+                .wait(used)
+                .unwrap_or_else(std::sync::PoisonError::into_inner);
+        }
+        *used += cost;
+        DecodePermit { budget: self, cost }
+    }
+}
+
+impl Drop for DecodePermit<'_> {
+    fn drop(&mut self) {
+        let mut used = self
+            .budget
+            .used
+            .lock()
+            .unwrap_or_else(std::sync::PoisonError::into_inner);
+        *used -= self.cost;
+        self.budget.freed.notify_all();
+    }
+}
+
+/// What decoding an image of `encoded_len` bytes and `dimensions` costs in
+/// memory: the encoded bytes, the decoded pixels at up to 4 bytes each, and a
+/// second copy of the pixels when [`decode_upright`] rotates them. When the
+/// header gives no dimensions, assume the image is compressed 16 to 1.
+fn decode_cost(encoded_len: u64, dimensions: Option<(u32, u32)>) -> u64 {
+    let pixels = match dimensions {
+        Some((width, height)) => u64::from(width) * u64::from(height) * 4 * 2,
+        None => encoded_len.saturating_mul(16),
+    };
+    encoded_len.saturating_add(pixels)
+}
+
+/// The pixel dimensions in the header of an encoded image, without decoding it.
+fn dimensions_of(bytes: &[u8]) -> Option<(u32, u32)> {
+    image::ImageReader::new(std::io::Cursor::new(bytes))
+        .with_guessed_format()
+        .ok()?
+        .into_dimensions()
+        .ok()
+}
+
+/// [`dimensions_of`] for an image file. Reads only the header.
+fn dimensions_of_file(path: &Path) -> Option<(u32, u32)> {
+    image::ImageReader::open(path)
+        .ok()?
+        .with_guessed_format()
+        .ok()?
+        .into_dimensions()
+        .ok()
+}
+
 /// The aspect ratio (w/h) of an encoded image, read from its header alone — no
 /// pixels are decoded. `None` when the format is unknown or the header is torn.
 fn ratio_of(bytes: &[u8]) -> Option<f64> {
@@ -209,7 +308,14 @@ fn thumbnail_build_may_start(status: &ThumbnailBuildStatus, path: &str) -> CoreR
 /// formats return an undecodable verdict.
 ///
 /// CPU-bound (a 20 MP JPEG is real work), so callers run it on the blocking pool.
+/// Waits for its share of [`DECODE_BUDGET`] first.
 fn scale_thumbnail(bytes: &[u8], name: &str, staging_dir: &Path) -> ScaleAttempt {
+    let _permit = DECODE_BUDGET.acquire(decode_cost(bytes.len() as u64, dimensions_of(bytes)));
+    scale_thumbnail_unbudgeted(bytes, name, staging_dir)
+}
+
+/// [`scale_thumbnail`] for a caller that already holds its [`DecodePermit`].
+fn scale_thumbnail_unbudgeted(bytes: &[u8], name: &str, staging_dir: &Path) -> ScaleAttempt {
    scale_thumbnail_with_exiftool(
        bytes,
        name,
@@ -544,11 +650,20 @@ fn upload_thumbnails_with(
        }
        video_file_thumbnail(path, ffmpeg, FFMPEG_TIMEOUT)
    } else if is_thumbnail_image_name(name) {
-        let fits = std::fs::metadata(path).is_ok_and(|meta| meta.len() <= UPLOAD_IMAGE_MAX_BYTES);
-        let Some(bytes) = fits.then(|| std::fs::read(path).ok()).flatten() else {
+        let Some(len) = std::fs::metadata(path)
+            .ok()
+            .map(|meta| meta.len())
+            .filter(|len| *len <= UPLOAD_IMAGE_MAX_BYTES)
+        else {
            return Vec::new();
        };
-        scale_thumbnail(&bytes, name, staging_dir)
+        // Taken before the read, so the encoded bytes count against the
+        // budget too.
+        let _permit = DECODE_BUDGET.acquire(decode_cost(len, dimensions_of_file(path)));
+        let Ok(bytes) = std::fs::read(path) else {
+            return Vec::new();
+        };
+        scale_thumbnail_unbudgeted(&bytes, name, staging_dir)
    } else {
        return Vec::new();
    };
@@ -2116,6 +2231,66 @@ impl Core {
    }
 }

+#[cfg(test)]
+mod decode_budget_tests {
+    use super::{DecodeBudget, decode_cost};
+    use std::sync::Arc;
+    use std::sync::atomic::{AtomicBool, Ordering};
+    use std::time::Duration;
+
+    /// A decode that does not fit beside the ones running waits for them,
+    /// instead of every drain worker decoding at once (`docs/BUGS.md` B280).
+    #[test]
+    fn a_decode_over_the_budget_waits_for_the_running_one() {
+        let budget = Arc::new(DecodeBudget::new(100));
+        let first = budget.acquire(60);
+        let started = Arc::new(AtomicBool::new(false));
+        let waiter = {
+            let (budget, started) = (budget.clone(), started.clone());
+            std::thread::spawn(move || {
+                let _second = budget.acquire(60);
+                started.store(true, Ordering::SeqCst);
+            })
+        };
+        std::thread::sleep(Duration::from_millis(100));
+        assert!(
+            !started.load(Ordering::SeqCst),
+            "second decode ran over budget"
+        );
+        drop(first);
+        waiter.join().expect("waiter");
+        assert!(started.load(Ordering::SeqCst));
+    }
+
+    /// Decodes that fit together run together.
+    #[test]
+    fn small_decodes_share_the_budget() {
+        let budget = DecodeBudget::new(100);
+        let _a = budget.acquire(30);
+        let _b = budget.acquire(30);
+        let _c = budget.acquire(30);
+    }
+
+    /// An image bigger than the whole budget still decodes, alone, rather than
+    /// waiting forever.
+    #[test]
+    fn an_image_over_the_whole_budget_still_decodes() {
+        let budget = DecodeBudget::new(100);
+        drop(budget.acquire(10_000));
+        let _again = budget.acquire(100);
+    }
+
+    /// The cost of the 102-megapixel JPEG that set off B280 fills the real
+    /// budget, so it never decodes beside another one.
+    #[test]
+    fn a_hundred_megapixel_photo_costs_the_whole_budget() {
+        let cost = decode_cost(97_266_141, Some((11_656, 8_742)));
+        assert!(cost >= super::DECODE_BUDGET_BYTES);
+        let phone = decode_cost(4_000_000, Some((4_000, 3_000)));
+        assert!(phone * 4 < super::DECODE_BUDGET_BYTES);
+    }
+}
+
 #[cfg(test)]
 mod thumb_tests {
    use super::{
@@ -57,7 +57,10 @@ pub(crate) fn run(core: Core, control_socket: PathBuf) {
    }

    let mut last_rss = Instant::now();
-    let mut last_ping = Instant::now();
+    // `None` until the first probe, which runs on the first tick: startup has
+    // already used up much of the watchdog's time (`docs/BUGS.md` B279).
+    let mut last_ping: Option<Instant> = None;
+    let mut restored = false;
    // Per-lane completion counts from the previous tick, to tell a queue that is
    // being worked through from one that is not moving at all.
    let mut last_completed = (0_u64, 0_u64);
@@ -84,16 +87,22 @@ pub(crate) fn run(core: Core, control_socket: PathBuf) {
        // throw away in-flight uploads. The probe decides that; a stall only
        // gets said out loud.
        if let Some(period) = watchdog
-            && last_ping.elapsed() >= period
+            && ping_due(last_ping, period)
        {
            if probe(&control_socket) {
+                if !restored {
+                    // Startup ran on the longer timeout the daemon asked for.
+                    // The socket answers now, so the unit's own one applies.
+                    systemd::restore_watchdog();
+                    restored = true;
+                }
                systemd::watchdog_ping();
            } else {
                warn!(
                    "daemon did not answer its own control socket; withholding the watchdog ping"
                );
            }
-            last_ping = Instant::now();
+            last_ping = Some(Instant::now());
        }
    }
 }
@@ -165,6 +174,11 @@ fn report_stalls(report: &pdfs_core::control::Diagnostics, last_completed: (u64,
    stalled
 }

+/// Whether the watchdog wants its next ping. The first one is due at once.
+fn ping_due(last_ping: Option<Instant>, period: Duration) -> bool {
+    last_ping.is_none_or(|at| at.elapsed() >= period)
+}
+
 /// One round trip over the control socket: connect, ask for the cheapest
 /// request there is, read the answer.
 ///
@@ -205,6 +219,18 @@ mod tests {
        }
    }

+    /// The first ping goes out on the first tick, not a full period after the
+    /// supervisor starts: startup has already spent most of the watchdog's time
+    /// (`docs/BUGS.md` B279).
+    #[test]
+    fn first_watchdog_ping_is_due_at_once() {
+        let period = Duration::from_secs(60);
+        assert!(ping_due(None, period));
+        assert!(!ping_due(Some(Instant::now()), period));
+        let long_ago = Instant::now().checked_sub(period).expect("uptime");
+        assert!(ping_due(Some(long_ago), period));
+    }
+
    /// A worker doing normal work must not be reported: a WARN every tick is a
    /// WARN nobody reads.
    #[test]
@@ -102,6 +102,37 @@ pub fn idle_sleep(duration: Duration) {
    }
 }

+/// How long a mount may take to start before the watchdog counts it as hung.
+///
+/// Startup has no control socket to probe yet, and on a large account it is
+/// long: hydrating 48 000 nodes took 70 s on 2026-11-12, and the secondary
+/// mounts followed. Under the 2-minute `WatchdogSec` that run was aborted just
+/// before its first ping, and left six dead mounts behind (`docs/BUGS.md` B279).
+const STARTUP_WATCHDOG: Duration = Duration::from_secs(600);
+
+/// Give the mount about to start [`STARTUP_WATCHDOG`] before the watchdog fires.
+///
+/// Sends `WATCHDOG_USEC=`, which replaces the unit's timeout and restarts its
+/// timer. The supervisor puts the configured timeout back with
+/// [`restore_watchdog`] once it can prove the daemon answers. A startup that
+/// wedges for good is still aborted, only later.
+pub fn stretch_watchdog_for_startup() {
+    if watchdog_period().is_some() {
+        notify(&format!("WATCHDOG_USEC={}\n", STARTUP_WATCHDOG.as_micros()));
+    }
+}
+
+/// Put back the timeout the unit configured, undoing
+/// [`stretch_watchdog_for_startup`].
+pub(crate) fn restore_watchdog() {
+    if watchdog_period().is_none() {
+        return;
+    }
+    if let Ok(usec) = std::env::var("WATCHDOG_USEC") {
+        notify(&format!("WATCHDOG_USEC={usec}\n"));
+    }
+}
+
 /// Tell the manager the daemon is stopping, so a slow teardown is not mistaken
 /// for a hang by the watchdog it is racing.
 pub(crate) fn stopping() {
@@ -109,6 +109,8 @@ a live account since.

 | Entry | Title |
 |---|---|
+| [B280](#b280--uploading-a-batch-of-large-photos-swaps-the-machine-until-the-daemon-is-killed) | Uploading a batch of large photos swaps the machine until the daemon is killed |
+| [B279](#b279--after-a-watchdog-kill-the-mount-never-comes-back) | After a watchdog kill the mount never comes back |
 | [B278](#b278--sync-list-and-devices-list-show-the-last-sync-as-epoch-seconds) | `sync list` and `devices list` show the last sync as epoch seconds |
 | [B277](#b277--my-files-mounted-over-a-folder-with-files-in-it-and-hid-them) | My files mounted over a folder with files in it, and hid them |
 | [B274](#b274--opening-a-file-for-writing-fails-with-eio-while-its-queued-revision-lands) | Opening a file for writing fails with EIO while its queued revision lands |
@@ -381,6 +383,76 @@ a live account since.

 Newest first.

+### B280 — Uploading a batch of large photos swaps the machine until the daemon is killed
+
+**Status:** Fixed, not verified live
+**Found:** 2026-11-12, after B279. 868 new pictures (15.6 GiB) were copied into
+`~/ProtonDrive/Pictures`. Each restart reached 1.7 GiB resident and 9.8 GiB of swap within 40 s.
+The 16 `pdfs-drain-*` threads were all busy, cgroup memory pressure (`full avg10`) was 77 %, and
+the system's 15 GiB of swap was full. The watchdog killed the daemon, and the next start did the
+same. The largest picture was a 97 MB JPEG of 11656×8742 pixels.
+**Where:** `upload_thumbnails_with` and `scale_thumbnail` in `crates/pdfs-fuse/src/photos.rs`
+
+**Repro:** Queue more large photos than there are drain workers, for example by copying a folder
+of 100-megapixel JPEGs into the mount, and start the daemon.
+
+**Cause.** Every upload of an image builds its thumbnail by decoding the whole file. Nothing
+limited how many of these decodes ran at once, so all 16 drain workers did it together. One
+102-megapixel JPEG holds about 300 MB of pixels, and twice that when it has to be turned upright.
+Sixteen of them do not fit in memory, and `MemoryHigh=2G` throttled the daemon into swap until it
+stopped answering.
+
+**Fix.** Each thumbnail decode first takes a share of a process-wide 512 MiB budget. The share is
+the encoded size plus 8 bytes per pixel, read from the image header. A 12-megapixel phone photo
+still decodes beside four others. A 100-megapixel photo waits until no other decode runs, and
+then runs alone. The upload path takes its share before it reads the file.
+
+**Test:** `decode_budget_tests` in `crates/pdfs-fuse/src/photos.rs`. On 2026-11-12 the same queue
+on the fixed build peaked at 1.3 GiB resident and 90 MB of swap, with memory pressure near 0 %.
+
+---
+
+### B279 — After a watchdog kill the mount never comes back
+
+**Status:** Fixed, not verified live
+**Found:** 2026-11-12, copying a folder of pictures into `~/ProtonDrive/Pictures`. The daemon
+stopped answering, the watchdog aborted it after 4 h 39 min (2.5 GiB memory peak, 11.8 GiB swap
+peak), and every restart then logged
+`create mountpoint /home/narl/ProtonDrive: File exists (os error 17)`. After the dead mounts were
+cleared by hand, the next start mounted all six folders and was aborted again, 120 s after it
+began, leaving six dead mounts behind once more.
+**Where:** `mount_once` in `crates/pdfs-cli/src/main.rs`; `prepare_mountpoint` in
+`crates/pdfs-fuse/src/mount.rs`; `crates/pdfs-fuse/src/supervisor.rs`;
+`crates/pdfs-fuse/src/systemd.rs`
+
+**Repro:** Kill the daemon with `SIGABRT` while it is mounted. Each restart fails with `EEXIST`
+until `fusermount3 -uz` clears every mount. Then restart on an account where hydrating the
+metadata cache takes about a minute: the watchdog aborts the new daemon before it pings.
+
+**Cause.** Two faults, one after the other.
+
+1. A dead FUSE mount answers `ENOTCONN`. `create_dir_all` in `mount_once` read that as "absent",
+   tried `mkdir`, and failed with `EEXIST`. The daemon retried that error forever and never
+   reached `check_mountpoint`, which clears a dead mount.
+2. systemd arms the watchdog when the process starts, but the supervisor sent its first ping one
+   full period (60 s) after it started. The supervisor starts only once the mount is live: 74 s
+   in on this account (70 s of that is hydrating 47 958 nodes). 74 s + 60 s is past the 120 s
+   `WatchdogSec`, so the run was aborted just before its first ping.
+
+**Fix.** `mount_once` calls `prepare_mountpoint`, which clears a dead mount before it creates the
+directory. Before startup, the daemon sends `WATCHDOG_USEC=` to allow 10 minutes. When the
+supervisor first gets an answer from the control socket, it sends the unit's own timeout back.
+The supervisor also probes and pings on its first tick, not one period later. A startup that
+hangs for good is still aborted, only later.
+
+The daemon stopped answering during the copy because of
+[B280](#b280--uploading-a-batch-of-large-photos-swaps-the-machine-until-the-daemon-is-killed).
+
+**Test:** `first_watchdog_ping_is_due_at_once` in `crates/pdfs-fuse/src/supervisor.rs`. The
+stale-mount path and the watchdog handshake need a live systemd unit to check.
+
+---
+
 ### B278 — `sync list` and `devices list` show the last sync as epoch seconds

 **Status:** Fixed, not verified live
@@ -11,15 +11,48 @@ scratch (user data in `staging/` and `recovery/` is never touched by this).

 ## [Unreleased]

-Schema: **45**. Synced folders now distinguish device backups from My files attachments.
-Existing folders remain device backups; older builds cannot open the upgraded database.
+## [3.8.0] — 2026-11-12
+
+Schema: **45**. Synced folders now tell device backups apart from folders attached to My files.
+Existing folders stay device backups. Older builds cannot open the upgraded database.

 ### Added

- `pdfs sync attach PATH --to REMOTE` connects an existing local directory to an existing
-  My files folder. The first sync preserves one-sided files and differing versions (#67).
-  Attachments stay in mirror mode, are excluded from device profiles, and cannot delete
-  the remote root when syncing is stopped.
+- **Sync a local folder with a folder you already have in My files** (#67, #77).
+  `pdfs sync attach ~/Work --to Work` keeps `~/Work` an ordinary local folder and syncs it both
+  ways with My files/Work. The first sync uploads files that are only on this computer, downloads
+  files that are only on Proton Drive, and keeps both versions of a file that differs: the one on
+  Proton Drive keeps its name, and the local one becomes a conflict copy next to it and is
+  uploaded too. Attached folders are always kept on this computer, never online only. They are
+  listed apart from device backups and are not part of the device profile used to restore another
+  computer. Stopping one keeps both copies, and `--delete-remote` is refused for it. If the folder
+  on Proton Drive is trashed or moved out of My files, syncing stops with an error and the local
+  files stay. Attaching a folder is done from a terminal for now.
+
+- **Tab completion for `pdfs`** in bash, zsh and fish, installed by every package. Besides
+  commands and options it completes paths in My files (`pdfs pin Doc<Tab>`) and what the running
+  service knows, each with a description: synced folders, queued changes, computers, trash, albums,
+  items shared with you, invitations, bookmarks and conflict copies, and once a path is typed, the
+  file's versions or the share's members and link. Without the service it still completes commands
+  and options. Elvish and PowerShell load it from `pdfs completions SHELL`, and so does a source
+  build; the [command-line reference](CLI.md#shell-completion) has the line for each shell.
+  `pdfs share` and `pdfs share-role` now check the role (`viewer`, `editor` or `admin`) before
+  sending the request, and `pdfs public-link` does the same for `viewer` and `editor`.
+
+### Fixed
+
+- **My files comes back after the service was killed for hanging** (B279). A killed service left
+  its folders behind as dead mounts, and every restart then failed with `File exists` and retried
+  forever without opening anything, until the mounts were cleared by hand. The service now clears
+  a dead mount before it opens the folder. On a large account a restart that did open My files was
+  killed again, because loading the account took longer than the 2 minutes the service has to
+  report in. Startup now gets 10 minutes, and the 2 minutes apply again once the service answers.
+
+- **Uploading many large photos no longer runs the computer out of memory** (B280). Every image
+  upload decodes the whole picture to make its thumbnail, and up to 16 did so at once. A batch of
+  100-megapixel photos took about 9 GiB, filled the swap, and the service was killed on every
+  restart. Thumbnails now share 512 MiB between them: phone photos are still made side by side,
+  and a very large photo waits and is made on its own.

 ## [3.7.0] — 2026-11-02

@@ -8,6 +8,7 @@ talks to the running service (`proton-drive.service`); `login`, `logout`, `mount
 what the commands do in the app, see the [user guide](USER_GUIDE.md).

 - [Conventions](#conventions)
+- [Shell completion](#shell-completion)
 - [Account and service](#account-and-service)
 - [Files](#files)
 - [Available offline](#available-offline)
@@ -32,6 +33,36 @@ what the commands do in the app, see the [user guide](USER_GUIDE.md).
  service.
 - **Output** is English and stable enough for `grep`; use `--json` where it is available.

+## Shell completion
+
+Tab completes commands and options, and also the values the service knows. Paths complete
+from My files, and these complete with a description: synced-folder and queue ids, computers,
+trash items, albums, items shared with you, invitations, bookmarks, conflict copies, and a file's
+versions or a share's members and link once the path is typed. Values come from the running
+service. Without it, only commands, options and local paths complete.
+
+| Example | Completes |
+|---|---|
+| `pdfs pin Doc<Tab>` | `Documents/`; Tab again lists its contents |
+| `pdfs sync rm <Tab>` | `1  /home/me/Documents (mirror)` … |
+| `pdfs devices rm <Tab>` | computer uids, with their names |
+| `pdfs versions restore Documents/a.pdf <Tab>` | version ids, with date and size |
+
+The packages install completion for bash, zsh and fish, which these shells load by themselves. For
+a source build, or another shell, load the script that `pdfs completions <shell>` prints:
+
+| Shell | Add to |
+|---|---|
+| bash | `~/.bashrc`: `source <(pdfs completions bash)` |
+| zsh | `~/.zshrc`, after `compinit`: `source <(pdfs completions zsh)` |
+| fish | `~/.config/fish/config.fish`: `pdfs completions fish \| source` |
+| elvish | `~/.config/elvish/rc.elv`: `eval (pdfs completions elvish \| slurp)` |
+| PowerShell | `$PROFILE`: `pdfs completions powershell \| Out-String \| Invoke-Expression` |
+
+The script runs `pdfs` from `PATH` on every Tab, so it keeps working after an update. A
+`pdfs` that is not on `PATH` prints a script for its own location with
+`PDFS_COMPLETE=<shell> ./pdfs`.
+
 ## Account and service

 | Command | Description |
@@ -185,6 +216,7 @@ commands are for scripts and for cases where the mount is not available.
 | `pdfs cache inspect [--deep]` | Database size, reclaimable space, row counts, cache use against the limit. `--deep` also runs SQLite's integrity check (slow). |
 | `pdfs cache vacuum` | Compact the database. Needs free space for a second copy of it while it runs. |
 | `pdfs cache clear` | Delete cached file content. Files kept available offline stay. |
+| `pdfs completions SHELL` | Print the [shell completion](#shell-completion) script for bash, zsh, fish, elvish or powershell. |

 [Troubleshooting](TROUBLESHOOTING.md) explains when to use each of these.

@@ -102,7 +102,7 @@ That URL follows `main`. To stay on releases, pin the input to a release tag ins
 the tag to update:

 ```nix
-inputs.proton-drive-linux.url = "github:narrrl/proton-drive-linux/v3.7.0";
+inputs.proton-drive-linux.url = "github:narrrl/proton-drive-linux/v3.8.0";
 ```

 Each release tag is built with Nix before the release is published.
@@ -9,7 +9,7 @@
 # Build + install:   cd packaging && makepkg -fi

 pkgname=proton-drive-linux
-pkgver=3.7.0
+pkgver=3.8.0
 pkgrel=1
 pkgdesc="Unofficial Proton Drive client for Linux: files-on-demand FUSE mount, CLI, GTK4 app + tray"
 arch=('x86_64')
@@ -80,5 +80,8 @@ package() {
  # Translations: compiled from po/ into /usr/share/locale.
  po/build.sh "$pkgdir/usr/share/locale"

+  # Shell completion for bash, zsh and fish.
+  packaging/completions.sh "$rel/pdfs" "$pkgdir/usr/share"
+
  install -Dm644 "LICENSE" "$pkgdir/usr/share/licenses/$pkgname/LICENSE"
 }
@@ -64,6 +64,14 @@ package() {
  install -dm755 "$pkgdir/usr/share"
  cp -r --no-preserve=ownership "$srcdir/locale" "$pkgdir/usr/share/locale"

+  # Shell completion for bash, zsh and fish, written by the binary itself.
+  local share="$pkgdir/usr/share"
+  install -d "$share/bash-completion/completions" "$share/zsh/site-functions" \
+    "$share/fish/vendor_completions.d"
+  "$srcdir/pdfs" completions bash > "$share/bash-completion/completions/pdfs"
+  "$srcdir/pdfs" completions zsh > "$share/zsh/site-functions/_pdfs"
+  "$srcdir/pdfs" completions fish > "$share/fish/vendor_completions.d/pdfs.fish"
+
  install -Dm644 "$srcdir/LICENSE-$pkgver" "$pkgdir/usr/share/licenses/$pkgname/LICENSE"

  # pacman brings new releases, so the app never checks for them itself.
@@ -81,6 +81,9 @@ package() {
  # Translations: compiled from po/ into /usr/share/locale.
  po/build.sh "$pkgdir/usr/share/locale"

+  # Shell completion for bash, zsh and fish.
+  packaging/completions.sh target/release/pdfs "$pkgdir/usr/share"
+
  install -Dm644 LICENSE "$pkgdir/usr/share/licenses/$pkgname/LICENSE"
  install -Dm644 README.md "$pkgdir/usr/share/doc/$pkgname/README.md"

@@ -76,6 +76,9 @@ package() {
  # Translations: compiled from po/ into /usr/share/locale.
  po/build.sh "$pkgdir/usr/share/locale"

+  # Shell completion for bash, zsh and fish.
+  packaging/completions.sh target/release/pdfs "$pkgdir/usr/share"
+
  install -Dm644 LICENSE "$pkgdir/usr/share/licenses/$pkgname/LICENSE"
  install -Dm644 README.md "$pkgdir/usr/share/doc/$pkgname/README.md"

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# Write the shell completion scripts of a built `pdfs` into <datadir>, where
+# bash-completion, zsh and fish look for them. Packages pass their install
+# tree, e.g. "$pkgdir/usr/share". The scripts call `pdfs` from PATH on every
+# Tab, so they are the same for every version and need no rebuild per release.
+set -euo pipefail
+
+if [ $# -ne 2 ]; then
+  echo "usage: $0 <pdfs binary> <datadir>" >&2
+  exit 2
+fi
+pdfs="$1"
+datadir="$2"
+
+install -d "$datadir/bash-completion/completions" \
+  "$datadir/zsh/site-functions" \
+  "$datadir/fish/vendor_completions.d"
+"$pdfs" completions bash > "$datadir/bash-completion/completions/pdfs"
+"$pdfs" completions zsh > "$datadir/zsh/site-functions/_pdfs"
+"$pdfs" completions fish > "$datadir/fish/vendor_completions.d/pdfs.fish"
+chmod 644 "$datadir/bash-completion/completions/pdfs" \
+  "$datadir/zsh/site-functions/_pdfs" \
+  "$datadir/fish/vendor_completions.d/pdfs.fish"
@@ -40,6 +40,7 @@ rustPlatform.buildRustPackage {
      ../io.narl.proton-drive-linux.desktop
      ../io.narl.proton-drive-linux-tray.desktop
      ../io.narl.proton-drive-linux.svg
+      ../completions.sh
    ];
  };

@@ -107,6 +108,9 @@ rustPlatform.buildRustPackage {
    patchShebangs po/build.sh
    po/build.sh $out/share/locale

+    patchShebangs packaging/completions.sh
+    packaging/completions.sh $out/bin/pdfs $out/share
+
    # Nix brings new releases, so the app never checks for them itself.
    install -Dm644 /dev/null $out/share/proton-drive-linux/managed-updates
  '';
@@ -10,7 +10,7 @@
 # Match Arch PKGBUILD `!lto` — LTO has broken some GTK/Rust links in practice.
 %global _lto_cflags %{nil}

-%{!?version: %global version 3.7.0}
+%{!?version: %global version 3.8.0}
 %global forge https://github.com/narrrl/proton-drive-linux
 # Files come from the checkout, or from the unpacked tag archive.
 %global src %{?git_dir}%{!?git_dir:.}
@@ -114,6 +114,7 @@ install -D -m0644 %{src}/packaging/io.narl.proton-drive-linux.svg \
 install -D -m0644 %{src}/packaging/proton-drive.service \
  %{buildroot}/usr/lib/systemd/user/proton-drive.service
 %{src}/po/build.sh %{buildroot}%{_datadir}/locale
+%{src}/packaging/completions.sh "$rel/pdfs" %{buildroot}%{_datadir}
 %if 0%{!?git_dir:1}
 # dnf brings new releases from COPR, so the app does not offer its own check.
 install -D -m0644 /dev/null %{buildroot}%{_datadir}/proton-drive-linux/managed-updates
@@ -149,6 +150,9 @@ fi
 %{_datadir}/icons/hicolor/scalable/apps/io.narl.proton-drive-linux.svg
 /usr/lib/systemd/user/proton-drive.service
 %{_datadir}/locale/*/LC_MESSAGES/pdfs.mo
+%{_datadir}/bash-completion/completions/pdfs
+%{_datadir}/zsh/site-functions/_pdfs
+%{_datadir}/fish/vendor_completions.d/pdfs.fish
 %if 0%{!?git_dir:1}
 %{_datadir}/proton-drive-linux/managed-updates
 %endif
@@ -6,7 +6,7 @@
 #, fuzzy
 msgid ""
 msgstr ""
-"Project-Id-Version: proton-drive-linux 3.7.0\n"
+"Project-Id-Version: proton-drive-linux 3.8.0\n"
 "Report-Msgid-Bugs-To: https://github.com/narrrl/proton-drive-linux/issues\n"
 "POT-Creation-Date: 2026-11-01 17:51+0100\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
Author	SHA1	Message	Date
nvrl	ad648ab5cc	feat(cli,core): shell completions with live values from the service `pdfs completions <shell>` prints a completion script for bash, zsh, fish, elvish or PowerShell, built on clap_complete's dynamic engine: on Tab the shell calls `pdfs` back, which completes commands and options and also the values the running service knows, each with a description: paths in My files, synced-folder and queue ids, computers, trash, albums, items shared with me, invitations, bookmarks, conflict copies, and a file's versions or a share's members and public link once its path is typed. A completer that gets no answer from the service within two seconds offers nothing rather than hanging the prompt. Listings that ask Proton are kept for 30 s in $XDG_RUNTIME_DIR (0600), so repeated Tabs do not wait again. Completion is triggered by PDFS_COMPLETE rather than clap's generic COMPLETE, because the same binary runs the daemon. Share roles are now checked by the CLI before the request. The package recipes install the bash, zsh and fish scripts via packaging/completions.sh.	2026-11-12 11:47:29 +01:00
nvrl	2b95708260	chore(release): 3.8.0	2026-11-12 10:22:04 +01:00
nvrl	c78bb529bc	fix(fuse): bound memory held by thumbnail decodes Every image upload decodes the whole file to build its thumbnail, and nothing limited how many decodes ran at once. With a queue of large photos all 16 drain workers decoded together; 100-megapixel JPEGs held about 9 GiB, swapped the machine, and the watchdog killed the daemon on every restart. Each decode now takes a share of a process-wide 512 MiB budget, sized from the encoded length and the header's pixel count. Phone photos still decode side by side; a photo larger than the budget waits and runs alone. Records B280.	2026-11-12 00:55:19 +01:00
nvrl	8d824af656	fix(fuse,cli): recover the mount after a watchdog kill A daemon killed by the watchdog left its FUSE mounts dead. A dead mount answers ENOTCONN, which create_dir_all took for an absent directory, so every restart failed with EEXIST and retried forever without reaching the code that clears stale mounts. mount_once now goes through prepare_mountpoint, which clears a dead mount first. Startup on a large account (70 s hydrating 48k nodes) plus the supervisor's first ping one full period later outlasted WatchdogSec=120, so a restart that did mount was aborted again. The daemon now asks for a 10-minute watchdog before startup, the supervisor pings on its first tick, and the unit's own timeout is restored once the control socket answers. Records B279.	2026-11-12 00:38:50 +01:00