What do I want to do?¶
A task-first index into protonfs: find what you are trying to do, run the command, and follow the worked walkthrough if you want the full picture. For the exact behaviour of any command see Command Reference; for the frozen 1.0 contract (exit codes, option names) see Stability Promise (M4.1).
Quick task index¶
I want to… |
Run (each links to its command reference) |
|---|---|
Set up syncing in a directory for the first time |
|
Check my keyring/CLI works on a headless server before logging in |
protonfs doctor (then |
Log in to Proton |
|
Upload my local files to Drive |
|
Download files that are on Drive but not here |
|
See what would sync without doing it |
|
See the sync state of every tracked file |
|
See which directories use the most storage |
protonfs ls –dirs (add –visual treemap|waffle for a chart) |
Get machine-readable output for a script |
protonfs status –format json / protonfs ls –format json|plain |
Learn about files on Drive I have never pulled |
|
Free local disk space but keep the files on Drive |
|
Remove a file from Drive (recoverably) |
|
Get back something I removed |
|
See or empty Drive’s trash |
|
Exclude or force-include files from syncing |
edit |
Update the proton-drive binary (safely) |
|
Bring an old repo’s |
protonfs upgrade (migrations run automatically) |
Change a config value |
|
See what protonfs is doing, or capture a debug log |
|
Tear protonfs out of a directory |
Walkthrough: your first sync¶
Set up a directory, log in, and push its contents to Drive.
cd ~/my-project
# 1. Install/verify the proton-drive CLI, prepare the keyring, and create
# .protonfs/. You are prompted for the Drive path to sync into.
protonfs setup
# Remote Drive root path for this repo: /my-files/my-project
# 2. Authenticate (opens a URL; on a server, see the headless walkthrough below).
protonfs auth login
# 3. See what a push would upload — always safe, changes nothing.
protonfs push --dry-run
# 4. Upload.
protonfs push
# 5. Confirm everything is in sync (exit code 0 == clean).
protonfs status
On another machine, run protonfs setup pointed at the same Drive path, then protonfs pull to bring the files down.
If that machine got the directory by cloning a repo that is already set up, setup
has nothing to ask you: remote_root and the ignore/include contract arrive with the
clone. All it does there is generate a device_id for this machine, because that value
lives in .protonfs/config.local.json, which is gitignored and so never travels with a
clone. Run protonfs setup once per machine and then carry on with refresh/pull.
Changed in version 1.12.1: Before this, setup in a fresh clone failed on the missing device_id – as did
every other command – and its own advice pointed back at setup.
See also
Syncing across machines for the push/pull/status model in depth.
Walkthrough: a headless server (SSH, no desktop)¶
proton-drive stores its session in the OS keyring, which over SSH usually has no session bus and no unlocked Secret Service. Diagnose and repair that before logging in, so a successful browser login is not thrown away.
# 1. Diagnose the environment (binary, session bus, keyring). Read-only.
protonfs doctor
# 2. Repair what protonfs can — bootstraps a protonfs-owned session bus + keyring.
protonfs doctor --fix
# 3. Now the session has somewhere to live; log in.
protonfs auth login
# To run the raw `proton-drive` binary by hand in the same shell:
eval "$(protonfs shell-init)"
Note
Every protonfs command sets up this keyring environment for itself;
shell-init is only needed for manual proton-drive invocations.
Credentials store: automatic pass fallback¶
On some headless hosts the freedesktop Secret Service still cannot be made ready even
after protonfs doctor --fix (no D-Bus, no keyring daemon available at all). In that
case protonfs auth login no longer fails to persist the session: it falls back
automatically to a protonfs-managed pass
credentials store, generating a passphrase-less GPG key and initializing the store —
the same security posture as the generated keyring password used for the keychain
path. A one-line notice is printed when this happens, and the choice is then sticky
for this host, so later commands reuse the same store instead of reading an empty one.
protonfs auth login
# falling back to a protonfs-managed pass credentials store (no Secret Service
# available on this host)...
protonfs doctor
# credentials store: pass (sticky)
Force a store instead of relying on auto-detection with PROTONFS_CREDENTIALS_STORE
(keychain/pass). If the native PROTON_DRIVE_CREDENTIALS_STORE is already set in
the environment, it passes straight through to proton-drive and wins over
PROTONFS_CREDENTIALS_STORE’s resolution.
Note
The pass fallback needs pass and gnupg2 on the host. With root, install
them from your package manager (on CentOS 7, enable EPEL first:
yum install epel-release && yum install pass gnupg2). gnupg2 is already present
on most systems.
Without root (a common headless case), pass installs into your home directory —
it is a self-contained shell script:
git clone https://git.zx2c4.com/password-store
make -C password-store PREFIX="$HOME/.local" install # installs ~/.local/bin/pass
Ensure ~/.local/bin is on PATH. pass’s only hard runtime dependencies are
gpg and getopt (tree is optional, used for listing only).
Requires proton-drive v0.6.0 or newer.
Walkthrough: free up local disk, keep the data on Drive¶
offload deletes the local bytes of files it can prove are already on Drive,
leaving the index entry so the file still shows up and can be pulled back.
# 1. Make sure everything is uploaded first.
protonfs push
# 2. Preview what would be freed (verifies each file against the remote first).
protonfs offload --dry-run
# 3. Free the local copies. Files that cannot be verified present on Drive, or
# have unsynced local edits, are reported and left untouched.
protonfs offload
# Later, bring one (or everything) back:
protonfs pull
Warning
offload only deletes a local file after confirming a byte-for-byte match on
Drive (via Proton’s plaintext claimedSize/digest, not the encrypted size).
Pass --no-verify at your own risk.
Walkthrough: remove and restore¶
# Move a file to Drive's trash (recoverable).
protonfs rm reports/old.csv
# Changed your mind:
protonfs restore reports/old.csv
# If restore complains it cannot disambiguate a same-named trash entry (#56),
# inspect the trash to see the duplicates:
protonfs trash list
# Permanently empty the trash (irreversible, account-global — typed confirmation):
protonfs trash empty
See also
Command Reference for rm’s -r/-f flags and the exact
trash-resolution behaviour.
Walkthrough: keeping proton-drive and an old repo current¶
# Upgrade protonfs itself first (PyPI):
pip install --upgrade protonfs
# Preview: installed vs highest-supported proton-drive, plus any pending
# repo-state migrations. Exits 1 if anything is out of date, 0 if current.
protonfs upgrade --check
# Apply: SHA-512-verified atomic binary swap + repo-state migrations.
protonfs upgrade
See also
Upgrading for the full upgrade story and the support-matrix
policy (why upgrade never installs a proton-drive newer than this release
supports).
Controlling what syncs¶
Two committed files under .protonfs/ decide which files are in scope:
.protonfs/ignore— gitignore-syntax exclusions (always wins)..protonfs/include— a gitignore-syntax allowlist: when present and non-empty, only matching files sync (and still never those matched byignore).
# Sync only the phantom dump files under an otherwise-excluded tree:
printf '%s\n' '*.ev' '*.sink' '*_[0-9][0-9][0-9][0-9][0-9]' > .protonfs/include
See also
Syncing across machines and the ignore/include notes in
Command Reference.