Command Reference¶
Every protonfs command, with its synopsis, arguments/options, what it actually
does, and worked examples. This page describes behavior; for the frozen contract
(exact exit codes, option names, config keys, env vars that will not change without
a major version bump) see Stability Promise (M4.1).
Synopsis¶
protonfs¶
Sync a local directory tree with Proton Drive.
Usage
protonfs [OPTIONS] COMMAND [ARGS]...
Options
- --version¶
Show the version and exit.
- -v, --verbose¶
Increase console detail (-v..-vvvv).
- --progress-inline, --progress-lines¶
Update progress in place (inline) vs. print each poll on a new line. Default: config (defaults.progress_style), else inline on a TTY.
- --event-log, --no-event-log¶
Write a full debug event log to .protonfs/events.log. Default: config (defaults.event_log), else off.
protonfs is the command group; every operation is a subcommand documented under
Subcommands. The global options above (verbosity, progress
style, event log) may appear before or after the subcommand.
Examples:
protonfs setup && protonfs push # first-time setup, then upload
protonfs refresh && protonfs pull # first pull on a new machine
protonfs status; echo "exit=$?" # drift check for scripts
Global behavior¶
Every command that mutates a repo’s index (push, pull, rm, restore,
refresh, offload) takes an exclusive, non-blocking advisory lock on
.protonfs/lock for its duration, so two protonfs processes never interleave
writes to index.json. If another process already holds it, the command fails
fast with an instructive message rather than blocking or racing (see
Durability and Drift-Resolution Guarantees).
Runtime commands that shell out to proton-drive (everything except config
and shell-init) share an error boundary: a Drive/auth failure, a locked
keyring, or a held repo lock all surface as a clean one-line error instead of a
Python traceback. An auth failure additionally suggests protonfs auth login.
Diagnostics & verbosity¶
Added in version 1.3.0: Layered -v verbosity, the progress-style flag, and the rotating event log.
Changed in version 1.4.0: Global options became position-independent — they may appear before or after the
subcommand (see reorder_argv()).
Every protonfs command accepts three global options, which may appear before or
after the subcommand (e.g. protonfs -vv --event-log pull or protonfs pull -vv),
that control how much it narrates and where that narration goes. All narration goes to stderr; each command’s result
summary stays on stdout, so piping/scripting a command’s output is unaffected by
verbosity. A flag, when given, overrides its config key; when unset, the resolved
config value is used, falling back to the built-in default (see Stability Promise (M4.1)
for the frozen option/config contract).
Verbosity ladder (-v)¶
-v is repeatable, from -v up to -vvvv. Each level is a superset of the one
below it.
Level |
Console detail |
|---|---|
(none) |
Warnings/errors only, plus each command’s normal stdout result summary. |
|
Adds curated phase narration, progress updates throttled to roughly every 30s, and phase durations. |
|
Adds per-item paths (each file transferred/affected) and sub-steps; progress throttled to roughly every 5s. |
|
Adds |
|
|
Progress style (--progress-inline / --progress-lines)¶
Controls how progress updates are rendered on stderr:
--progress-inline— one live line, rewritten in place as progress advances. This is the default when stderr is a TTY. An open inline progress line is always closed (a newline written) before any other message, so nothing it printed is overwritten.--progress-lines— every poll gets its own line instead of rewriting in place. Used automatically when stderr is not a TTY (e.g. redirected to a file or a CI log), regardless of the configured/default style.
Default: the defaults.progress_style config key, else inline on a TTY.
Event log (--event-log / --no-event-log)¶
When enabled, protonfs writes a structured log to .protonfs/events.log, rotating
at roughly 5 MB with one backup file (events.log.1). Each line is aligned text:
TIMESTAMP LEVEL component message key=value. The event log always records full
DEBUG-level detail while enabled, independent of the console -v level chosen
for the same run; the proton-drive subprocess’s stderr is included in it only at
-vvvv.
.protonfs/events.log is gitignored automatically — new repos get this from the
setup template, and existing repos pick it up via a protonfs upgrade
migration. protonfs deinit removes it along with the rest of .protonfs/. It is
never treated as sync payload: protonfs excludes .protonfs/ from scans entirely.
Default: the defaults.event_log config key, else off.
Configuration¶
Environment variables¶
- PROTONFS_CONFIG¶
Overrides the global config file path outright.
Added in version 1.0.0.
- PROTONFS_REMOTE_ROOT¶
Per-key override for
remote_root.Added in version 1.0.0.
- PROTONFS_ON_CONFLICT¶
Per-key override for
defaults.on_conflict.Added in version 1.0.0.
- PROTONFS_LOW_IO¶
Per-key override for
defaults.low_io.Added in version 1.0.0.
- PROTONFS_EVENT_LOG¶
Per-key override for
defaults.event_log.Added in version 1.3.0.
- PROTONFS_PROGRESS_STYLE¶
Per-key override for
defaults.progress_style.Added in version 1.3.0.
Operational & tuning environment variables¶
These have no config-key equivalent; they tune how protonfs invokes and installs the
proton-drive binary and how it bootstraps the keyring. All are part of the frozen
contract (see Stability Promise (M4.1)).
- PROTONFS_DRIVE_BIN¶
Path/name of the
proton-drivebinary to invoke, in place of the default.Added in version 1.0.0.
- PROTONFS_DRIVE_CACHE_HOME¶
Directory to keep proton-drive’s cache under, passed to proton-drive as
XDG_CACHE_HOME: the cache lands in$PROTONFS_DRIVE_CACHE_HOME/proton-drive-cli. Set it to a local disk when your home directory is a network mount (GlusterFS, NFS, Lustre, GPFS, CIFS): proton-drive reads and writes its sqlite cache on every call, and on one GlusterFS home that made listings 75 times slower.protonfs doctorwarns when the cache is on such a mount. proton-drive creates the directory itself, so a location under/tmpsurvives being wiped (the cache is rebuilt). Only the cache moves; proton-drive’s client ID, event state and logs stay where they are.protonfs schedule --addrecords the value set when the job is added and exports it from the job’s wrapper, so re-add existing jobs after setting it. Linux only.Added in version 2.6.0.
- PROTONFS_DRIVE_VERSION¶
Overrides the
proton-driveversioninstall-driveinstalls when--versionis not passed.Added in version 1.0.0.
- PROTONFS_DRIVE_SHA512¶
Explicit SHA-512 to verify a
proton-drivedownload against, required for versions/platforms without a built-in checksum pin.Added in version 1.0.0.
- PROTONFS_LIST_TIMEOUT¶
Timeout in seconds for a Drive listing call (default
45).Added in version 1.0.0.
- PROTONFS_TRASH_LIST_TIMEOUT¶
Timeout in seconds for listing the whole
/trash(default900), used byrestore,trash list,rm --force,ls --trashand the trash pass ofdu /. On expiry the command fails with an error saying the trash is too large to list; nothing is changed.duinstead shows its trash total as partial, with that reason, and lists the trash again before that figure is stale only when this value has been raised since (or under--refresh 0).Added in version 3.4.0.
- PROTONFS_LIST_RETRIES¶
Max retries for a Drive listing call (default
4).Added in version 1.0.0.
- PROTONFS_LIST_BACKOFF¶
Base backoff in seconds between Drive listing retries (default
2).Added in version 1.0.0.
- PROTONFS_LIST_BACKOFF_CAP¶
Cap in seconds on the Drive listing retry backoff (default
60).Added in version 1.0.0.
- PROTONFS_TRANSFER_TIMEOUT¶
Minimum timeout in seconds for a Drive upload/download call (default
300). A call moving more data gets longer, seePROTONFS_TRANSFER_MIN_RATE, and a call that times out is retried with its timeout doubled.Added in version 1.0.0.
Changed in version 2.5.0: Now the minimum: the timeout grows with the call’s data, and doubles on each timed-out retry. A call that times out on every attempt is reported as a timeout rather than as throttling.
- PROTONFS_TRANSFER_MIN_RATE¶
Slowest transfer rate, in bytes per second, that still counts as progress (default
524288, 512 KiB/s). A Drive upload/download call gets at least its data size divided by this rate before it times out, so a batch of large files is not cut off by a timeout sized for small ones.0turns the scaling off.Added in version 2.5.0.
- PROTONFS_CLOCK_SKEW¶
Per-key override for
defaults.clock_skew(off,autoor seconds).Added in version 3.3.0.
- PROTONFS_CLOCK_AHEAD_LIMIT¶
Seconds this host’s clock may run ahead of Proton’s before uploads are refused (default
30). Proton rejects a file whose signatures are dated ahead of its own clock (60 s ahead was accepted and 90 s refused when measured), so a fast clock fails every upload. Before its first upload, protonfs compares the clock with theDateof a Proton API response and stops with the measured offset when it is over this limit; an offset it cannot measure does not stop the upload. Withdefaults.clock_skewset, the corrected offset is what is checked. Sync the clock (NTP) or setclock_skewrather than raising the limit past about 60.Added in version 3.3.0.
- PROTONFS_BATCH_SIZE¶
Per-key override for
defaults.batch_size. A value below1counts as1; a value that is not an integer is an error when the config loads.Added in version 1.6.0.
- PROTONFS_TRANSFER_RETRIES¶
Max retries for a Drive upload/download call (default
4), after throttling or a timeout.Added in version 1.0.0.
- PROTONFS_TRANSFER_BACKOFF¶
Base backoff in seconds between Drive upload/download retries (default
2).Added in version 1.0.0.
- PROTONFS_TRANSFER_BACKOFF_CAP¶
Cap in seconds on the Drive upload/download retry backoff (default
60).Added in version 1.0.0.
- PROTONFS_KEYRING_PASSWORD¶
Supplies the password for the protonfs-owned keyring bootstrap, instead of generating one.
Added in version 1.0.0.
- PROTONFS_MANIFEST¶
Per-key override for
defaults.manifest.Added in version 2.1.0.
- PROTONFS_SKIP_THUMBNAILS¶
Per-key override for
defaults.skip_thumbnails.Added in version 2.5.0.
- PROTONFS_NO_MANIFEST¶
Set (to any truthy value) to switch every remote-manifest read and write off on this host, whatever
defaults.manifestsays.Added in version 2.1.0.
- PROTONFS_NO_KEYRING_BOOTSTRAP¶
Set (to any truthy value) to disable protonfs’s Secret Service/keyring bootstrap entirely; the caller is responsible for providing one.
Added in version 1.0.0.
- PROTONFS_CREDENTIALS_STORE¶
Forces which proton-drive credentials store protonfs prepares and uses:
keychain(freedesktop Secret Service) orpass(password-store). The default,auto, trieskeychainfirst and falls back to a protonfs-managedpassstore only when the Secret Service cannot be made ready on this host (see Credentials store: automatic pass fallback). The resolved choice is written to a per-host sticky file so later commands never read a different (empty) store. NativePROTON_DRIVE_CREDENTIALS_STORE, if already set in the environment, is passed straight through toproton-driveand takes precedence over this variable’s resolution.Added in version 1.9.0.
- PROTONFS_DU_REFRESH¶
Override for
du.refresh: the age past whichprotonfs dure-checks a cached figure (a duration such as5dor2h45m,0for fresh values only, orneverfor cache only).Added in version 3.4.0.
- PROTONFS_PLAN_SIZE¶
Override for
du.plan_size.Added in version 3.4.0.
- PROTONFS_DU_CACHE¶
Path of the
protonfs ducache database. Default:$XDG_CACHE_HOME/protonfs/du.sqlite(~/.cache/protonfs/du.sqlite). It is separate from proton-drive’s own cache (PROTONFS_DRIVE_CACHE_HOME).Added in version 3.4.0.
Configuration file and keys¶
- remote_root¶
- Type:
- str
Proton Drive path that maps to this repo’s ProtonFS root. Overridable via
PROTONFS_REMOTE_ROOT.Added in version 1.0.0.
- device_id¶
- Type:
- str
Stable identifier for this client device in the index. Overridable via
PROTONFS_DEVICE_ID.Added in version 1.0.0.
- defaults.on_conflict¶
- Type:
- str
- Default:
- "skip"
Action when a file is in
SyncStateconflict. Overridable viaPROTONFS_ON_CONFLICT.Added in version 1.0.0.
- defaults.low_io¶
- Type:
- bool
- Default:
- false
Skip hashing unchanged files. Overridable via
PROTONFS_LOW_IO.Added in version 1.0.0.
- defaults.event_log¶
- Type:
- bool
- Default:
- false
Enable the structured rotating event log. Overridable via
PROTONFS_EVENT_LOG.Added in version 1.3.0.
- defaults.progress_style¶
- Type:
- str
- Default:
- "inline"
Progress display style,
inlineorlines. Overridable viaPROTONFS_PROGRESS_STYLE.Added in version 1.3.0.
- defaults.batch_size¶
- Type:
- int
- Default:
- 200
Most files sent in one proton-drive
filesystem uploadordownloadcall. Each call’s timeout grows with the data it carries (PROTONFS_TRANSFER_MIN_RATE); a smaller batch saves progress to the index more often and resends less after a failed call. Not aconfig get/config setkey: set it in aconfig.jsonlayer’sdefaultsobject, or override it viaPROTONFS_BATCH_SIZE.Added in version 1.6.0.
- defaults.manifest¶
- Type:
- bool
- Default:
- true
Keep the remote manifest (see verify) current on
pushandrm. Only an existing manifest is updated;protonfs verify --repaircreates one. Set it in the sharedconfig.jsonso every host maintains it. Overridable viaPROTONFS_MANIFEST.Added in version 2.1.0.
Changed in version 2.3.0: On by default. A repo with no manifest yet gets a warning from
push/rmuntilprotonfs verify --repairhas built one.
- defaults.skip_thumbnails¶
- Type:
- bool
- Default:
- false
Upload every file without a thumbnail (proton-drive’s
--skip-thumbnails). Off,pushstill sends a file without a thumbnail when proton-drive cannot build one on this host (HEIC, AVIF or TIFF with no OS codec), after a warning. Turn it on to skip that first failed attempt, or to save the time thumbnails take. Overridable viaPROTONFS_SKIP_THUMBNAILS.Added in version 2.5.0.
- defaults.clock_skew¶
- Type:
- str
- Default:
- off
How proton-drive’s clock is corrected before it signs uploads. Proton rejects a file whose signatures are dated ahead of its own clock, so a host whose clock runs fast fails every upload (see
PROTONFS_CLOCK_AHEAD_LIMIT).off: no correction; an upload from a clock too far ahead is refused.auto: measure the offset against Proton’s clock once per run and run proton-drive on a clock shifted back by it. Right on a shared home directory, where one config file reaches hosts whose clocks differ.a number: the seconds this host’s clock runs ahead of Proton’s (negative if it runs behind); proton-drive’s clock is shifted back by that much.
The shift is applied by a
--preloadscript handed to proton-drive (a Bun build) throughBUN_OPTIONS; it changes the time proton-drive signs with, not the system clock. Overridable viaPROTONFS_CLOCK_SKEW.Added in version 3.3.0.
- defaults.deletions¶
- Type:
- str
- Default:
- keep
What push does on Drive with a file this machine held that is now gone locally.
keepleaves Drive’s copy (and the index entry) alone;trashmoves it to the Drive trash (protonfs restoreputs it back on Drive) and drops it from the index. Overridden per run bypush --deletionsand per scheduled job byschedule --deletions. There is deliberately no environment override: trashing is destructive and is chosen per repo. See push –deletions for the guards.Added in version 3.0.0.
- du.refresh¶
- Type:
- str
- Default:
- 5d
How old a cached
protonfs dufigure may be before it is re-checked: a duration (5d,2h45m,1w,1mo,1y),0for fresh values only, orneverfor cache only. Global config only (protonfs config set --global du.refresh 2d), overridden byPROTONFS_DU_REFRESHand per run bydu --refresh.Added in version 3.4.0.
- du.plan_size¶
- Type:
- str
- Default:
- unset
Your Proton plan’s shared storage total (Mail, Drive and the rest draw on it), for
protonfs du’s%Plancolumn, e.g.3TBor500GB(decimal) or2TiB(binary). Proton’s CLI cannot report it, so it has to be set by hand. Global config only, overridden byPROTONFS_PLAN_SIZE.Added in version 3.4.0.
Subcommands¶
setup¶
protonfs setup¶
Install/verify the proton-drive CLI, init .protonfs/, migrate off git-lfs if present.
A new store asks for its Drive remote root, or takes it from –remote-root; without a terminal to ask on, –remote-root is required.
Changed in version 3.2.0: Added --remote-root.
Usage
protonfs setup [OPTIONS]
Options
- --dry-run¶
Preview the LFS migration without making changes.
- --migrate-lfs, --no-migrate-lfs¶
Force or skip the repo-wide git-LFS migration. Default: migrate only when this directory is the git toplevel, so setting up a subdirectory never migrates the enclosing repo off LFS.
- --remote-root <PATH>¶
The Drive folder a new store syncs to (e.g. /my-files/myproject), instead of being asked. For an existing store it must be the store’s own root: setup never repoints a store.
Installs/verifies the proton-drive CLI, initializes .protonfs/ in the
current directory (config.json, ignore, a .gitignore that excludes
index.json/refresh-state.json, and a .gitattributes that exempts those
control files from git-LFS), and migrates the repo off git-LFS if it is tracked.
It also creates the configured remote_root on Drive if it does not exist yet,
so the first push has somewhere to land without hand-creating folders.
Default: migrate only when the current directory is the git toplevel, so running
setup in a subdirectory of a larger repo never migrates the enclosing repo off
LFS by surprise.
A new store asks for its Drive remote root. Pass --remote-root to answer in
advance, which a script, a cron job, ssh host 'protonfs setup' or any other run
without a terminal must do: with neither, setup stops with exit 1 rather than wait
on a question nobody can answer. Setup never repoints a store: in an existing one
(including a fresh clone), --remote-root must name the store’s own root, and a
different one is refused, naming both, with nothing changed. A new store’s root must
live under /my-files and carry no surrounding whitespace; anything else is refused
before anything is written (a prompted answer is asked again).
Changed in version 3.2.0: Added --remote-root.
Examples:
protonfs setup # first-time setup in the current directory
protonfs setup --dry-run # see what setup would do first
protonfs setup --no-migrate-lfs # set up without touching git-LFS either way
protonfs setup --remote-root /my-files/my-project # no prompt (scripts, ssh)
deinit¶
protonfs deinit¶
Remove .protonfs/ from this directory: clean teardown of a protonfs root.
Only protonfs’s own bookkeeping under .protonfs/ (config, index, ignore/include, control .gitattributes/.gitignore) is removed – synced payload files, local or remote, are never touched.
Changed in version 3.4.0: Run from a subdirectory of a store, it refuses and names the store root to run it from (#232): a teardown acts only where it is run.
Usage
protonfs deinit [OPTIONS]
Options
- --dry-run¶
List what would be removed; delete nothing.
- --yes¶
Skip confirmation prompt.
The inverse of setup: removes every file setup writes under .protonfs/
— the shared config.json, the per-device config.local.json, the index,
the resumable-refresh state, ignore/include, and the control
.gitattributes/.gitignore — after printing a summary and asking for
confirmation. It only ever looks inside .protonfs/: synced payload files,
local or remote, are never touched, so deinit is a clean teardown of protonfs’s own
bookkeeping and nothing else.
Examples:
protonfs deinit --dry-run # see exactly which .protonfs/ files would go
protonfs deinit # remove them after confirming
status¶
protonfs status¶
Summarize sync state as a count per state (locally-indexed, local-only, …).
Without --remote nothing is checked on Drive: every count compares the working
tree against this machine’s index (what protonfs last recorded). locally-indexed
therefore means “matches the index”, not “verified on Drive”; --remote walks
Drive and classifies against it too.
Accepts any number of PATHs (e.g. from a shell glob); counts are combined. Exit code, so an unattended caller can branch without parsing the counts: 0 = clean (every file locally-indexed, metadata-only or an LFS pointer stub), 1 = drift present (something to push/pull/prune), 2 = conflict present (conflict: a local change with no remote view to attribute it; both-modified: changed on both sides). Conflict outranks drift when both are present.
Changed in version 3.4.0: Run from a subdirectory of a store it finds the store, PATH is read relative to the current directory, and with no PATH it acts on that subdirectory (#232).
Usage
protonfs status [OPTIONS] [PATH]...
Options
- --format <fmt>¶
Output format: the classic state-per-line counts, or one JSON object.
- Default:
'plain'- Options:
plain | json
- --remote¶
Walk Drive and classify against it as well as the local index (slower, but catches remote changes that refresh hasn’t seen yet). Without it nothing is checked on Drive: ‘locally-indexed’ means the file matches this machine’s index.
Arguments
- PATH¶
Optional argument(s)
Glob patterns in scan-scoped commands. status, ls, offload and prune
also expand a quoted PATH pattern ('mload005e_*') themselves, so a scheduled
prune re-matches new run directories on every run. A pattern matches the local
tree and the index together (so a directory that is already offloaded is found
too), with the same segment rules as push. An existing literal
path wins: when run[7] exists on disk or in the index it names that folder and is
not read as a pattern. A pattern that matches nothing prints
warning: no tracked path matches 'mload005e_*' on stderr and the command does
nothing; it never widens to the whole repo. rm, restore and refresh take
their PATH literally: rm and restore change Drive and act only on what is
named, and refresh exists to find paths the index does not yet hold, so there is
nothing for a pattern to match against.
Changed in version 3.3.1: status, ls, offload and prune expand quoted glob PATH patterns.
Before, they treated the pattern as a literal path, so a scheduled
prune "mload005e_*" considered nothing and reported success.
Changed in version 1.1.0: Added --format (plain/json) and multiple PATH pathspecs.
Changed in version 2.0.0: synced renamed to locally-indexed; added --remote; the JSON output
gained a remote field.
Scans the local tree (optionally scoped to PATH), compares it against the
local index, and prints a count per sync state (locally-indexed,
local-only, remote-only, metadata-only, conflict,
local-modified, remote-modified, both-modified, local-deleted,
remote-changed, remote-deleted, lfs-pointer).
By default it does not talk to Drive at all, so every count describes the local
files against the index: locally-indexed means “matches what this machine last
recorded”, not “verified on Drive”. --remote walks Drive and classifies against
it as well — slower, and a failed or throttled walk is an error rather than a
silent fall-back to the index-only answer. --format json includes
"remote": true|false so a consumer can tell which answer it got.
Exit code: 0 clean, 1 drift present, 2 conflict present (conflict
outranks drift) — identical in both formats. See Stability Promise (M4.1) for the
exact mapping and Durability and Drift-Resolution Guarantees for how states are classified.
Examples:
protonfs status
protonfs status subdir/
protonfs status; echo "exit=$?"
protonfs status --format json | jq .counts
protonfs status --remote # classify against a live Drive walk
ls¶
protonfs ls¶
List tracked files with their sync state (any number of PATHs).
–dirs summarizes each immediate subdirectory (counts by state, cumulative local/indexed sizes) instead of listing thousands of files; –state filters to the states you care about; –format plain|json makes the output scriptable; –visual treemap|waffle draws a storage-usage chart of those directories.
Changed in version 3.4.0: Run from a subdirectory of a store it finds the store, PATH is read relative to the current directory, and with no PATH it acts on that subdirectory (#232).
Usage
protonfs ls [OPTIONS] [PATH]...
Options
- --remote¶
Force a live Drive listing to compute state instead of relying on the local index alone (slower, but catches remote changes that refresh hasn’t seen yet).
- --trash¶
List /trash instead of the working tree (name and type only; no sync-state column, since trashed items aren’t tracked in the index).
- --dirs¶
Aggregate per immediate subdirectory: file counts by state plus cumulative local/indexed sizes, instead of listing every file.
- --state <states>¶
Only show files in this sync state (repeatable).
- Options:
locally-indexed | local-only | remote-only | metadata-only | conflict | local-modified | remote-modified | both-modified | local-deleted | remote-changed | remote-deleted | lfs-pointer
- --format <fmt>¶
Output format: rich table, tab-separated lines, or JSON.
- Default:
'table'- Options:
table | plain | json
- --visual <visual>¶
Draw a per-directory storage-usage chart (by each dir’s apparent footprint) instead of the listing. Implies directory aggregation; terminal-only (not for –format/–trash).
- Options:
treemap | waffle
Arguments
- PATH¶
Optional argument(s)
Lists tracked files with their sync state, as a table of path / state.
Added in version 1.1.0: --dirs per-directory aggregation with sizes, the --state filter, and
--format on ls/status.
Changed in version 1.2.0: --visual treemap/waffle storage charts.
--dirs aggregates per immediate subdirectory instead of listing every file:
one row per directory with its file count, cumulative local size (bytes on
disk; 0 for fully offloaded dirs), cumulative indexed size (what the index
records — the remote-side size), and a per-state count summary. This is the
storage-breakdown view: protonfs ls --dirs on a large tree answers “which
directories are taking space locally vs on Drive” without printing 10,000
metadata-only lines. --state STATE applies before --dirs aggregation, so
the two compose. --state synced is still accepted as a deprecated alias of
locally-indexed (with a warning on stderr) and will be removed in the next
major release. The --dirs JSON/columns also carry an apparent_bytes
field: each directory’s true footprint, taking per file whichever of the
local/indexed size is known (they agree when locally-indexed, local for a not-yet-pushed
file, indexed for an offloaded one). --visual {treemap,waffle} draws a
per-directory storage-usage chart instead of the listing, sized by that
apparent_bytes footprint so a fresh local-only tree and a fully-offloaded tree
both chart correctly. treemap gives nested rectangles whose areas are
proportional to size (squarified for readability); waffle gives a
proportional grid of cells. Both print a colour legend with each directory’s size
and percentage. This is a terminal-only view — it cannot be combined with
--format plain/json or --trash (both raise a usage error).
Examples:
protonfs ls
protonfs ls --remote subdir/
protonfs ls --trash
protonfs ls --dirs # per-directory storage breakdown
protonfs ls --remote --state remote-only --format plain | cut -f1
protonfs ls sim/ --dirs --format json # scriptable per-dir sizes/counts
protonfs ls --visual treemap # squarified storage treemap
protonfs ls sim/ --visual waffle # proportional waffle chart of sim/
du¶
protonfs du¶
Show how much Proton Drive space remote paths take, trash included.
PATH is a Drive path (/, /my-files/…, /devices/…) or a local path inside a store; with none, the current directory. A quoted glob PATH expands: a local one against the store’s files and index (so offloaded folders match), a remote one against a listing of its parent. Every figure shows its age; a trash figure that could not be fully measured is shown as a lower bound.
Exit codes: 0 complete, 1 the target could not be measured, 2 usage error, 3 partial results (some row failed, or the / In trash total is incomplete). With several PATHs, one whose own figure failed makes the run exit 1 while the others still print.
Added in version 3.4.0.
Usage
protonfs du [OPTIONS] [PATH]...
Options
- -x, --exclude-updates <PATTERN>¶
Freeze matching paths: make no Drive calls for them or below; show the cached figure (blank if none). Gitignore syntax; repeatable.
- -X, --exclude <PATTERN>¶
Hide matching paths: not walked and not shown. Repeatable.
- --mindepth <mindepth>¶
Hide rows shallower than this (the target is depth 0).
- --maxdepth <maxdepth>¶
Deepest level shown (default 1: the target and its children).
- -d, --depth <N|MIN-MAX>¶
Depth: N (max), MIN-MAX, MIN- or -MAX. Not with –mindepth/–maxdepth.
- -D, --dirs-only¶
Hide file rows.
- --refresh <DURATION|0|never>¶
Re-measure figures older than this (default: config du.refresh, else 5d). 0 fetches everything fresh (but only du / reruns the trash pass); never uses the cache only.
- --format <fmt>¶
Output format: rich table (default), tab-separated lines, or JSON.
- Options:
table | plain | json
- --json¶
Shorthand for –format json.
- -p, --show-progress¶
Report Drive calls on stderr as they happen (one line rewritten in place, or a line each with –progress-lines).
- --gui¶
Serve a local web UI (loopback, token in the printed URL) instead of printing a report.
- --listen <listen>¶
With –gui: address to listen on.
- --port <port>¶
With –gui: port number, or auto.
- --log <log>¶
With –gui: log directory, file or device.
Arguments
- PATH¶
Optional argument(s)
Shows how much Proton Drive space remote paths take, from the whole account (/)
down to one folder, including what is in the trash. Read-only: it issues only
filesystem list, filesystem size, filesystem list /trash and
filesystem info /my-files.
Added in version 3.4.0.
Unlike ls --dirs, which sums the index of one store, du measures Drive itself,
so it covers every store, device and anything uploaded outside protonfs. Figures come
from a per-machine cache (PROTONFS_DU_CACHE) and carry their age; a figure
older than --refresh (default du.refresh, 5d) is re-checked when it
is used. --refresh 0 fetches everything shown, --refresh never makes no Drive
calls. %Plan needs du.plan_size.
Exit code: 0 complete, 1 a target could not be measured, 2 usage error,
3 complete output with some figures missing or a partial trash total. See
Where has my storage gone? for what the columns and remainder rows mean, and
Stability Promise (M4.1) for the JSON contract.
Examples:
protonfs du / # each section, plus the trash total
protonfs du /my-files/sph-dev -d 2 # two levels, biggest first
protonfs du ~/sph-dev/sim/mload005 # a local path inside a store
protonfs du / -x devices --refresh never # cache only, devices frozen
protonfs du /my-files --json | jq '.rows[] | select(.depth == 1)'
push¶
protonfs push¶
Upload local-only/changed files to Drive (any number of PATHs).
Each PATH may be a directory, a single file, or a glob pattern. A quoted pattern
('mload*', 'mload*/*.ev') is expanded by protonfs itself against the local
tree at run time; an unquoted one is expanded by the shell first, as before. A PATH
that does not exist locally is a usage error (exit 2): push uploads local files, so a
missing path can only be a typo – this is distinct from the exit 1 used for transfer
failures.
A pattern matching nothing is reported and skipped (it never widens to the whole
repo); pass --strict to make that an error instead.
Changed in version 1.5.2: PATH may now name a single file (previously only directories were scanned, so a
file/glob pathspec silently uploaded nothing). A nonexistent PATH is now a usage
error instead of a silent no-op, and an empty push prints nothing to push.
Changed in version 1.11.0: A quoted PATH glob pattern is now expanded by protonfs against the local tree,
rather than depending on the shell to expand it first (#131) – so a scheduled job
can carry a pattern that keeps matching as new directories appear. Added
--strict.
Changed in version 2.4.0: Added --min-age: a file modified within the window is held back and counted as
unsettled= in the summary, then pushed by a later run once it has settled (#168).
File PATHs share one pass, so N files no longer cost N listings and index saves
(#171).
Changed in version 3.0.0: A file moved or renamed locally is moved or renamed on Drive instead of uploaded
again, and counted as moved= in the summary. Added --deletions and
--allow-mass-delete: with trash, files deleted locally are moved to the
Drive trash and counted as trashed= (a dry run lists them). Files deleted
locally that stay on Drive are counted as local-deleted= (#197).
Changed in version 3.4.0: Run from a subdirectory of a store it finds the store, PATH is read relative to the current directory, and with no PATH it acts on that subdirectory (#232).
Usage
protonfs push [OPTIONS] [PATH]...
Options
- --resolve <resolve>¶
How to reconcile a file that changed on BOTH sides since the last sync: remote=keep the remote copy (skip the upload), local=replace the remote with your local copy (the existing remote file is moved to the trash), both=upload your local copy alongside the remote. A file changed only locally needs none of these: it is uploaded as a new revision of the remote file. The proton-drive strategy names merge|keep-both|replace|skip are also accepted (replace=local, skip=remote, keep-both=both; merge adds a revision regardless of what the remote holds).
- Options:
remote | local | both | merge | keep-both | replace | skip
- --dry-run¶
Report what would be pushed without transferring anything.
- --strict¶
Fail (exit 1) if a PATH pattern matches nothing, instead of skipping it.
- --min-age <DURATION>¶
Settle window (e.g. 30m, 2h): hold back files modified more recently than this, so a file still being written is never uploaded part-way. 0 holds nothing back.
- Default:
'0'
- --deletions <deletions>¶
What to do on Drive with files this machine held that are gone locally: keep leaves Drive’s copy, trash moves it to the Drive trash. Default: the repo’s defaults.deletions (keep).
- Options:
keep | trash
- --allow-mass-delete¶
With –deletions trash, trash even when a top-level directory vanished or more files than the per-run cap would go.
Arguments
- PATH¶
Optional argument(s)
Changed in version 1.1.0: Interactive batch progress on stderr; accepts multiple PATH pathspecs.
Changed in version 1.11.0: A quoted PATH glob pattern is expanded by protonfs itself against the local
tree, instead of relying on the shell to expand it first. Added --strict.
Uploads local-only and locally-modified files under PATH (or the whole repo)
to Drive. When run interactively (stderr is a terminal), a running
push: N/M file(s) progress line is shown on stderr after each uploaded batch;
scripts and redirected output see only the frozen summary on stdout.
PATH may be a directory, a single file, or a glob pattern. An unquoted
pattern is expanded by your shell before protonfs sees it, as always; a quoted
one ('mload*', 'mload*/*.ev') reaches protonfs intact and is expanded by
protonfs against the local tree at run time. The two are equivalent
interactively, but only the quoted form survives into a scheduled job — see
schedule — where the pattern must be re-expanded on each run so it
keeps matching as new directories appear. A pattern segment never crosses /,
matching shell semantics.
A PATH holding *, ? or [ also matches a path of exactly that name, as
a git pathspec does: 'run [7]' names the folder run [7] (and, as a pattern,
run 7).
Changed in version 3.1.1: A pattern also matches a path named exactly like it.
A pattern that matches nothing is reported and skipped, and never widens to the whole repo:
pattern(s) matched nothing, skipped (nothing to push): 'mload*' -- pass --strict to make this an error
Pass --strict to make that an error (exit 1) instead. --strict fails
before anything is transferred, so a run is all-or-nothing rather than partial.
Without --resolve, a genuine remote conflict is reported as a named
per-file failure rather than silently resolved or skipped. A file that changed
only locally since this machine last pushed it is not a conflict: it is uploaded
as a new revision of the existing Drive file, so Drive’s version history keeps
the earlier copy. --resolve local (replace) instead moves the existing
remote file to the trash and uploads a new one in its place. Every batch is
re-verified against a live remote listing after upload (matching each file’s
plaintext claimedSize) before it is recorded in the index — proton-drive can
report a transfer as successful when it did not actually land; an unverified file
is left unindexed and retried on the next push instead of being recorded as delivered.
A file that is an un-smudged git-LFS pointer stub is never pushed, even if
misclassified upstream, because that would overwrite real Drive content with a
131-byte placeholder. See Durability and Drift-Resolution Guarantees for the full mechanism.
A directory whose every file is new and being pushed, with nothing ignored, held
back or already indexed inside it, is uploaded whole in one proton-drive call
(up to defaults.batch_size files, several such directories per call),
and proton-drive creates its subfolders. Every other file goes up with the other
files of its folder. Each remote folder is created at most once per push.
A file you moved or renamed locally is moved or renamed on Drive instead of
uploaded again. Push pairs each new file with a file this machine held that is now
gone locally and has the same content (sha256 and size). Pairing is one-to-one:
among several identical files, a pair with the same name wins, then one in the same
folder, and anything still ambiguous is uploaded as a new file. A pair in the same
folder is renamed; a pair with the same name is moved; otherwise the file is moved,
then renamed. Missing target folders are created first. The Drive node itself moves,
so its version history and share links survive, and its index entry follows it with
its checksums. Each move is checked against a listing of the target folder; one that
fails, or that the listing does not show, falls back to an upload, and the old path
stays indexed. Moved files are counted as moved=N in the summary. A file edited
and then moved has different content, so it is uploaded, and its old path stays on
Drive. Pairing needs both paths inside PATH, and a push of individual files pairs
nothing.
Changed in version 3.0.0: Local moves and renames are applied on Drive instead of uploaded again.
A file this machine held that is now gone locally and was not moved stays on
Drive by default (defaults.deletions keep). With --deletions trash
(or the config key set to trash) push moves its Drive copy to the trash after the
uploads, confirms with a listing that it is gone, and drops it from the index and the
remote manifest; trashed=N counts them, and --dry-run lists each one as
trash <path>. restore puts a trashed file back on Drive; run
refresh and pull to bring it down again. A path now
matched by .protonfs/ignore is never trashed: ignoring stops syncing, it does not
delete. The old path of a move push had to upload instead is trashed once the new path
is on Drive; one whose new path the settle window (--min-age) held back is not.
Because a mass deletion is usually an accident, the trash step is refused, with nothing
trashed and exit 1:
always, when every file this machine held in scope is gone (an unmounted disk or the wrong directory); remove files deliberately with rm instead;
unless
--allow-mass-deleteis given, when a whole top-level directory of the scope vanished, or when the run would trash more than 500 files, or more than 10 files and more than 5% of the tracked files.
Changed in version 3.0.0: Added --deletions and --allow-mass-delete.
Progress is saved after each upload call or folder group, so an interrupted push resumes rather than restarting. Progress lines count files and bytes across the whole push.
Examples:
protonfs push # everything in scope that is new/changed
protonfs push subdir/ --resolve replace
protonfs push --dry-run
import¶
protonfs import¶
Move files git tracks in this store out of git and into the store (from git).
Each PATH may be a file, a directory (its tracked files) or a glob pattern; a quoted
pattern ('**/*.mp4') matches only files git tracks, never untracked or gitignored
ones. The files are pushed, then each is verified from a fresh read: against Drive
and against the blob committed in HEAD. Only when every one verifies does git
stop tracking them: one literal line per file goes into a block in this store’s
.gitignore, git rm --cached untracks them, and .gitignore is staged.
Nothing is committed, git history is not touched, and no imported file is changed
or deleted: review with git status and commit. Git is changed for every PATH or for
none. The files stay in git history; git filter-repo purges them (protonfs does
not). Other clones lose them from their work tree when they pull the commit;
protonfs pull there restores them from Drive, and push --deletions trash
never trashes them.
Directories and patterns skip .protonfs/ and git’s own .gitignore and
.gitattributes files. Refused, with nothing done (exit 1): a path that is not
tracked, has uncommitted changes, is a symlink, is tracked by git-LFS or is an LFS
pointer stub, is excluded by .protonfs/ignore or .protonfs/include, is a
.gitignore/.gitattributes, or lies outside the store; a .gitignore with
uncommitted changes; a store outside a git work tree. Every refusal is listed at once.
Exit code: 0 imported (or a dry run with nothing refused); 1 a refusal, a file that failed verification, a git failure (rolled back), or a Drive/lock error; 2 usage error.
Added in version 3.1.0.
Changed in version 3.4.0: Run from a subdirectory of a store it finds the store, PATH is read relative to the current directory, and with no PATH it acts on that subdirectory (#232).
Usage
protonfs import [OPTIONS] PATH...
Options
- --dry-run¶
Show each path’s verdict, the push plan, the .gitignore lines and the git commands, and change nothing.
- --strict¶
Fail (exit 1) if a PATH pattern matches nothing, instead of skipping it.
Arguments
- PATH¶
Required argument(s)
Added in version 3.1.0.
Moves files that git tracks in this store out of git and into the store, for example
generated outputs that were committed and have outgrown the repository. Run it from
inside the store; PATH may be a file, a directory (its tracked files) or a quoted
glob, which matches tracked files only, so a pattern never picks up an untracked or
gitignored file next to the ones you mean. Directories and patterns skip .protonfs/
and git’s own .gitignore/.gitattributes files:
protonfs import --dry-run '**/*.reduced.fits' '**/*.mp4'
protonfs import '**/*.reduced.fits' '**/*.mp4'
git status
git commit -m "chore: move 130 file(s) from git into protonfs"
What it changes, and only after every file is verified (see Durability and Drift-Resolution Guarantees):
one line per file in a block at the end of the store’s own
.gitignore(<store>/.gitignore, created if absent), each anchored and escaped so it matches exactly that file;git rm --cachedfor each file, thengit add .gitignore. Nothing is committed.
The location and format of that block are current behaviour, not part of the
Stability Promise (M4.1) contract. .gitignore is itself an ordinary file in the store,
so protonfs syncs it like any other.
export¶
protonfs export¶
Move files this store holds back into git (to git).
Each PATH may be a file, a directory (the files the store holds under it) or a glob
pattern; a quoted pattern ('**/*.mp4') matches the files the store holds,
offloaded ones included. Offloaded files are downloaded first. Each file is then
verified from a fresh read against its index entry and a fresh Drive listing, so git
gets the version Drive holds. Only when every one verifies: their lines leave the
import block of this store’s .gitignore, git add stages them, and one literal
line per file goes into a block in .protonfs/ignore, so no machine syncs them any
more; .gitignore and .protonfs/ignore are staged too.
Nothing is committed and no file is changed or deleted: review with git status
and commit. Git is changed for every PATH or for none. Drive copies are kept unless
--trash-remote. When other clones pull the commit, git replaces their copy of
these files with the committed one; run protonfs push there first so no local
change is lost.
Directories and patterns skip .protonfs/ and git’s own .gitignore and
.gitattributes files. Refused, with nothing done (exit 1): a path the store does
not hold, one git already tracks, one a git rule other than its import line still
ignores (the rule is named), one a git-LFS filter would store in LFS, a
.gitignore/.gitattributes, a path outside the store; a .gitignore or
.protonfs/ignore with uncommitted changes; a store outside a git work tree. Every
refusal is listed at once.
Exit code: 0 exported (or a dry run with nothing refused); 1 a refusal, a file not
downloaded or not verified, a git failure (rolled back), a Drive copy
--trash-remote could not trash, or a Drive/lock error; 2 usage error.
Added in version 3.1.0.
Changed in version 3.4.0: Run from a subdirectory of a store it finds the store, PATH is read relative to the current directory, and with no PATH it acts on that subdirectory (#232).
Usage
protonfs export [OPTIONS] PATH...
Options
- --dry-run¶
Show each path’s verdict, what would be downloaded, the ignore lines and the git commands, and change nothing.
- --strict¶
Fail (exit 1) if a PATH pattern matches nothing, instead of skipping it.
- --trash-remote¶
Once git tracks the files, move their Drive copies to the Drive trash. By default they are kept on Drive, and protonfs no longer syncs them.
Arguments
- PATH¶
Required argument(s)
Added in version 3.1.0.
The reverse of import: moves files this store holds back into git,
for example a file that should be versioned after all. PATH may be a file, a
directory (the files the store holds under it that git does not track) or a quoted glob
matched against the files the store holds, offloaded ones included:
protonfs export --dry-run 'run01/*.reduced.fits'
protonfs export 'run01/*.reduced.fits'
git status
git commit -m "chore: move 32 file(s) from protonfs into git"
What it changes, and only after every file is on disk and verified against Drive (see Durability and Drift-Resolution Guarantees):
offloaded files are downloaded first;
each file’s line is removed from the import block of
<store>/.gitignore, if it has one, andgit addstages the file (and.gitignore);one line per file goes into a
# protonfs exportblock in.protonfs/ignore, which is staged too, so no machine syncs the files any more;the files’ index entries (and remote manifest entries) are dropped. Their Drive copies are kept unless
--trash-remote;protonfs rm PATHtrashes one later. A kept copy is out of the store’s scope like any excluded file:statusandls(--remotetoo) leave it out, andpullandrefreshnever bring it back, on any machine, even after git moved or deleted the file.
When other clones pull the commit, git replaces their copy of each file with the
committed one, even if theirs had changes git never saw (git treats ignored files as
expendable). Run protonfs push on those clones first. A file listed in the export
block is refused by import, with the line to remove named. The block’s location and
format are current behaviour, not part of the Stability Promise (M4.1) contract.
The summary is push’s line plus untracked=N. Afterwards the files are still in
git history; git filter-repo removes them from it (protonfs does not). On other
clones, pulling the commit removes the files from the work tree; protonfs pull
there restores them, and push --deletions trash never trashes them. See
Moving files from git into a store for a walkthrough.
pull¶
protonfs pull¶
Download remote-only/changed files from Drive (any number of PATHs).
Each PATH may be a directory, a single file, or a glob pattern. A quoted pattern
('mload*', 'mload*/*.ev') is expanded by protonfs itself, against the paths
the INDEX knows about – not the local filesystem, because pull’s whole purpose is
fetching files that are absent locally (an offloaded file has no local presence to
glob). Run refresh first on a repo whose index has not seen those files yet.
A pattern matching nothing is reported and skipped (it never widens to the whole
repo); pass --strict to make that an error instead.
Diverged files (edited locally AND changed on the remote since the last sync) are left untouched unless you pass –resolve; they are reported and pull exits non-zero.
A file this machine held that is now gone locally is restored, since its copy is on
Drive. With --no-restore it is left alone and counted as local-deleted=, so a
deletion or move made locally survives for push to act on; a PATH given literally
(not a pattern) that names such a file is still restored.
Changed in version 1.11.0: A quoted PATH glob pattern is now expanded by protonfs against the index, rather
than depending on the shell to expand it first (#131) – so a scheduled job can
carry a pattern that keeps matching as new runs appear, and so a pattern can name
offloaded files that no filesystem glob could find. Added --strict.
Changed in version 2.1.0: With an empty index, the index is seeded from the remote manifest when the root has one, instead of stopping with “run refresh first” (#146).
Changed in version 3.0.0: Added --no-restore (#197).
Changed in version 3.3.2: --resolve downloads files changed only on Drive again (3.0.0 to 3.3.1 left
them alone). Without it, --refresh reports how many such files it left alone.
Changed in version 3.4.0: Run from a subdirectory of a store it finds the store, PATH is read relative to the current directory, and with no PATH it acts on that subdirectory (#232).
Usage
protonfs pull [OPTIONS] [PATH]...
Options
- --resolve <resolve>¶
How to reconcile a file that changed on BOTH sides since the last sync: remote=overwrite local, local=keep local (stays queued for push), both=fetch the remote copy under a .remote suffix for a manual merge. replace is an alias for remote (replace the local copy). Without this, pull leaves diverged files untouched and reports them.
- Options:
remote | local | both | replace
- --dry-run¶
Preview transfers and unresolved conflicts without downloading anything.
- --refresh¶
Discover remote files (seed the index) before pulling.
- --strict¶
Fail (exit 1) if a PATH pattern matches nothing, instead of skipping it.
- --no-restore¶
Leave files this machine held that are now gone locally (deleted, or moved away) alone instead of restoring them, and count them as local-deleted=. A PATH naming one such file is still restored.
Arguments
- PATH¶
Optional argument(s)
Changed in version 1.1.0: Interactive batch progress on stderr; accepts multiple PATH pathspecs.
Changed in version 1.11.0: A quoted PATH glob pattern is expanded by protonfs itself against the
index, instead of relying on the shell to expand it first. Added --strict.
Downloads remote-only and (with --resolve) remote-modified files under
PATH (or the whole repo). When run interactively (stderr is a terminal), a
running pull: N/M file(s) progress line is shown on stderr after each
transferred batch; scripts and redirected output see only the frozen summary on
stdout.
PATH accepts a glob pattern on the same terms as push,
with one important difference: pull expands a pattern against the paths the
index knows about, not the local filesystem. That is deliberate — pull exists
to fetch files that are absent locally, and an offloaded file has no local
presence for a filesystem glob to find, so matching on disk would silently miss
exactly the files you asked for. The practical consequence is that a pattern only
matches what the index has already seen: run refresh first on a repo
whose index does not yet know about those files (pull --refresh 'mload*' on a
brand-new repo expands the pattern before the refresh seeds the index, so it
matches nothing on that first run).
A pattern that matches nothing is reported and skipped, never widening to the
whole repo; --strict makes it an error (exit 1) instead, failing before
anything is transferred.
This is what makes the small-files case schedulable: 'mload*/*.ev' pulls a
few megabytes of time-series data across every matching run, while leaving the
much larger dumps in those same directories offloaded.
A file edited locally and changed on the
remote since the last sync (a divergence) is left untouched by a bare
pull — it is reported and the command exits non-zero, so a local edit is
never silently overwritten. Choose a side with --resolve:
remote— overwrite the local copy with the remote one.local— keep the local copy; it stays queued for the nextpush.both— fetch the remote copy alongside the local one under a.remotesuffix (untracked) for a manual merge.
A file this machine held that is now gone locally is restored: without a
remote listing it is remote-only, its copy is on Drive, and bringing it back is
what pull is for. Where local changes should win instead — a tree another tool
reorganises, with pull and push both scheduled — pass --no-restore: such
files are left alone and counted as local-deleted=N, so the next push can apply
the move on Drive (or, with --deletions trash, the deletion). A PATH given
literally that names one such file is still restored; a pattern is not. A path the
scan skipped that still exists on disk (now ignored, say) is never downloaded over.
A file the store’s .protonfs/ignore/include rules exclude is never downloaded
at all, and pull reports how many it left on Drive. With --refresh and no
--resolve, pull reports how many files the refresh found changed on Drive while
the local copy is unchanged; it leaves them alone, and --resolve remote brings them
down.
Changed in version 3.0.0: Added --no-restore.
Changed in version 3.3.2: --resolve downloads remote-modified files again (3.0.0 to 3.3.1 left them
alone), and --refresh without --resolve reports how many it left alone.
--refresh seeds the index from a fresh remote listing before pulling (metadata
only, no download) — useful on a machine whose index doesn’t yet know everything
already on Drive. Without an index yet, plain pull refuses to run and tells
you to run refresh first (or pass --refresh).
Examples:
protonfs refresh && protonfs pull # typical first pull on a new machine
protonfs pull --refresh # equivalent, one command
protonfs pull path/to/file --resolve remote
protonfs pull --resolve both # fetch remote copies as *.remote for merging
offload¶
protonfs offload¶
Delete local bytes of protonfs-tracked files confirmed present on Drive.
Accepts any number of PATHs (e.g. from a shell glob). The inverse of pull: reclaims local disk space while leaving the Drive copy intact. Reversible – a later pull restores the file in full. By default every file is re-verified against a live remote listing (not just the index) before its local copy is deleted; pass –no-verify to skip that check.
A file modified within the last –min-age (default one day) is never offloaded: with nobody holding it open, it may still be being written.
Changed in version 2.4.0: File PATHs share one pass, so N files no longer cost N listings and index saves (#171).
Changed in version 3.4.0: Run from a subdirectory of a store it finds the store, PATH is read relative to the current directory, and with no PATH it acts on that subdirectory (#232).
Usage
protonfs offload [OPTIONS] [PATH]...
Options
- --no-verify¶
Skip re-verifying files against the remote before deleting local bytes (unsafe). A file pushed while it was still changing is re-verified regardless.
- --min-age <DURATION>¶
Settle window: leave alone any file modified more recently than this (e.g. 12h, 1d, 90m; 0 disables it). A file can still be being written with nobody holding it open.
- Default:
'1d'
- --dry-run¶
Preview what would be offloaded; delete nothing.
- --yes¶
Skip confirmation prompt.
Arguments
- PATH¶
Optional argument(s)
Deletes the local bytes of protonfs-tracked files already confirmed present on
Drive, reclaiming disk space while leaving the index entry as
local_state=metadata-only — a later pull restores the file in full. This
is the inverse of pull; it never touches the remote copy.
Before deleting anything, every candidate is (a) checked for unsynced local
edits — a file whose live content hash differs from what the index last recorded
is never offloaded, verify or not, since offloading it would destroy the only
copy of that edit — and (b) by default, re-verified against a live remote
listing (not just the index), requiring the remote’s plaintext claimedSize to
match the local file’s byte size. A file that fails either check is left alone
and reported (skipped_modified / skipped_unverified); this is not treated
as command failure. --no-verify skips the live remote re-verification (the
unsynced-edit guard in (a) always still applies) — unsafe if the remote could
have changed since the index was last updated.
Examples:
protonfs offload subdir/ # prompts for confirmation
protonfs offload --dry-run
protonfs offload --yes --no-verify # unsafe: trust the index alone
protonfs offload --min-age 12h sim/ # settle window of 12 hours
Settle window¶
Added in version 2.2.0.
A file can still be in use when no process holds it open. A simulation writes a
dump, closes it, and may keep appending to its time series for days. So offload
never removes a file modified more recently than --min-age (default 1d;
0 disables the window). Such files are reported as skipped_unsettled,
whatever the remote holds. The age is measured from the file’s local modification
time when offload runs.
A file that was pushed while it was still inside the window is re-verified against
the live listing before deletion, even under --no-verify. The index entry
written at push time described a file that was still changing, so the index alone
is not trusted for it. “Pushed inside the window” means the entry’s last_synced
time is less than --min-age after the file’s recorded mtime; an entry whose
timestamp cannot be read counts as inside the window.
prune¶
protonfs prune¶
Free local disk by a retention policy, through offload (any number of PATHs).
Pushes first (unless –no-push), so new files are on Drive before anything is considered. Then, in each directory, the –keep most recently modified tracked files stay local, and any other tracked file unmodified for –min-age is offloaded. A file is offloaded only when BOTH rules release it. Holds the repo lock for the whole run, so it cannot overlap a push.
Every deletion goes through offload, with its live re-verification against Drive: prune never removes a file offload would refuse (not confirmed on Drive, edited since its last push, or not yet settled).
Exit code: 0 success (files offload refused are reported, not failed); 1 when the push that ran first failed for some file, or a Drive/lock error; 2 usage error.
Changed in version 3.4.0: Run from a subdirectory of a store it finds the store, PATH is read relative to the current directory, and with no PATH it acts on that subdirectory (#232).
Usage
protonfs prune [OPTIONS] [PATH]...
Options
- --keep <keep>¶
Newest files (by modification time) to keep locally in each directory.
- Default:
10
- --min-age <DURATION>¶
Settle window: leave alone any file modified more recently than this (e.g. 12h, 1d, 90m; 0 disables it). A file can still be being written with nobody holding it open.
- Default:
'1d'
- --no-push¶
Do not push new files first.
- --dry-run¶
Preview what would be offloaded; push and delete nothing.
- --yes¶
Skip confirmation prompt.
Arguments
- PATH¶
Optional argument(s)
Added in version 2.2.0.
A retention policy for freeing local disk, built on offload:
Push first (unless
--no-push), so new files are on Drive before anything is considered.Choose candidates. A tracked file is one the index records as held locally, that is not excluded by
.protonfs/ignore/include, and that lies withinPATH. Tracked files are grouped by their immediate parent directory. In each directory the--keepmost recently modified files (by local modification time; ties broken by path) stay local, and any other file that has not been modified for--min-agebecomes a candidate. A file must be released by both rules.Offload the candidates, with offload’s live verification and all of its guards. prune can only narrow what offload considers, never widen it: a file that is not confirmed on Drive, has changed since its last push, or is not yet settled is refused and reported.
The repo lock is held for the whole run, so a prune can never overlap a push.
Examples:
protonfs prune sim/ --keep 10 --min-age 1d # the defaults, spelled out
protonfs prune --dry-run # what would be offloaded
protonfs prune 'mload*' --keep 3 --no-push
PATH patterns are expanded as described under status.
rm¶
protonfs rm¶
Remove files/directories from Drive (trash by default, -f for permanent).
Changed in version 3.4.0: Run from a subdirectory of a store it finds the store, PATH is read relative to
the current directory, and the store root itself (., .. up to it, its
absolute path or /) is refused with a usage error (#232).
Usage
protonfs rm [OPTIONS] PATH...
Options
- -r, --recursive¶
- -f, --force¶
Permanently delete (trash, then delete).
- --yes¶
Skip confirmation prompt.
Arguments
- PATH¶
Required argument(s)
Trashes PATH on Drive (reversible via restore). Requires -r/
--recursive for a directory. The command removes the matching index entries
locally regardless of whether the permanent-delete step below runs.
-f/--force additionally attempts to permanently delete the trashed
node after trashing it. proton-drive addresses a trashed node only by
/trash/<basename> (no working UID addressing), so when two or more trashed
items share a basename, protonfs cannot safely tell which is yours: it leaves
the item trashed (still reversible) and reports the ambiguity rather than
guessing. See Durability and Drift-Resolution Guarantees for the exact boundary.
Examples:
protonfs rm old-dump.ev
protonfs rm -r stale-dir/ --yes
protonfs rm -f duplicate.tmp # trash, then attempt permanent delete
restore¶
protonfs restore¶
Restore trashed files/directories on Drive.
Changed in version 3.4.0: Run from a subdirectory of a store it finds the store, PATH is read relative to
the current directory, and the store root itself (., .. up to it, its
absolute path or /) is refused with a usage error (#232).
Usage
protonfs restore [OPTIONS] PATH...
Arguments
- PATH¶
Required argument(s)
Restores a previously trashed file/directory on Drive by its original path.
On proton-drive versions that reject original-path restore (0.5.0+), protonfs
falls back to resolving the trashed entry by name — and refuses to act (raising
an error naming the ambiguity) rather than guess when more than one trashed item
shares that name under a different original parent. See the boundary spelled out
in Durability and Drift-Resolution Guarantees and in DriveClient.restore’s docstring
(src/protonfs/drive.py).
Examples:
protonfs restore old-dump.ev
protonfs restore stale-dir/
refresh¶
protonfs refresh¶
Discover remote files and seed the local index (any number of PATHs).
Changed in version 3.4.0: Run from a subdirectory of a store it finds the store, PATH is read relative to the current directory, and with no PATH it acts on that subdirectory (#232).
Usage
protonfs refresh [OPTIONS] [PATH]...
Options
- --prune¶
Drop index entries for files deleted on the remote.
Arguments
- PATH¶
Optional argument(s)
Walks Drive under the configured remote_root (or PATH within it) and seeds
the local index with metadata-only entries for anything found there that this
machine’s index doesn’t already know about. This is the cross-client primitive: a
fresh machine (or one that missed files another client pushed) becomes aware of
everything already on Drive without downloading any content, so it will not
re-upload what’s already there. It also reports files that changed or were
deleted on the remote since they were last seen.
The walk is resumable: progress (both the seeded entries and the walk’s own frontier) is saved incrementally, so a run interrupted by an API throttle picks up where it left off on the next invocation instead of restarting from the root. Change/deletion detection only runs after a complete pass, though — a resumed partial pass seeds but does not yet report changes/deletions.
Examples:
protonfs refresh # seed everything not yet known
protonfs refresh subdir/ --prune # scope to a subtree, drop remote-deleted entries
Changed in version 2.1.0: When the repo maintains a remote manifest (defaults.manifest), a
complete whole-root pass records the manifest generation it reconciled against.
Nothing under the remote .protonfs/ directory is ever seeded.
verify¶
protonfs verify¶
Check the remote manifest against a full listing of the remote.
The manifest (.protonfs/manifest.json under the remote root) records every file protonfs verified on Drive, so a host can read what is there without walking the tree. It is a cache: this command walks the whole remote and reports entries Drive contradicts (missing, or a different size/sha1) and files the manifest does not list. –repair rewrites the manifest from that listing, and is how one is first created.
With –index, it checks the local index instead. Each entry is compared with a listing of its remote directory (one listing per directory, no local files read), with entries whose only copy is on Drive first. –repair then applies what that proves: an entry whose file is still here and whose Drive copy is missing or differs is dropped, so the next push uploads it; one whose file is gone and whose Drive copy is larger is rewritten to describe that copy. A Drive-only copy that is shorter, different or gone is reported and left as it is. When every entry was checked, the index is recorded at the current check level, so upgrade does not check it again.
Exit code: 0 when every manifest entry matches Drive (or there is no manifest, or –repair rewrote it); 1 when entries are missing or differ, or on a Drive error. With –index: 0 when every entry matches (with –repair: when every entry was checked and none was left untouched); 1 otherwise, or on a Drive or lock error.
Changed in version 2.4.0: Added --index (#169).
Usage
protonfs verify [OPTIONS]
Options
- --repair¶
Rewrite the remote manifest to match a full listing of the remote (creating it if the root has none). With –index, apply to the index what its check proves.
- --index¶
Check the local index instead: compare every entry with a listing of its remote directory, without reading local files.
Added in version 2.1.0.
The remote manifest is one JSON object per synced root, at
<remote_root>/.protonfs/manifest.json. It records every file protonfs uploaded
(or adopted) and verified on Drive: plaintext size, sha256, sha1, and the uid of the
Drive revision that was verified. A generation counter goes up on every write,
and each write is uploaded as a new revision of the manifest itself, so Drive’s
version history keeps every earlier one.
It is a cache, not an authority:
Entries are written only after the upload they describe was verified, so the manifest can lag Drive but never runs ahead of it. A crash, or a host running an older protonfs, leaves it behind, never ahead.
It is only ever created by
verify --repairfrom a full listing, so it starts complete.pushandrmkeep an existing manifest current whendefaults.manifestis on. They never start one mid-history, because such a manifest would look complete while missing everything uploaded before it.Nothing destructive trusts it.
offloadalways verifies against a live listing and never reads the manifest.Changes made outside protonfs (the web UI, another client) are invisible to it until something walks the remote.
verifyis that walk.
verify reports:
entries the manifest lists that Drive lacks, or holds at a different size or sha1 (faults: exit
1);files on Drive the manifest does not list (tolerated, since the manifest may lag);
entries whose content matches but whose Drive revision has moved on;
files Drive listed without a plaintext size, which cannot be compared.
It also says which manifest generation this machine’s index was last reconciled
with. --repair rewrites the manifest to match the listing. It keeps a sha256
only where this machine’s index, or the manifest itself, recorded one for exactly
that content; otherwise the sha256 is left unknown rather than guessed. It leaves
out any file Drive lists without a plaintext size.
Readers: pull on an empty index (a fresh clone) seeds the index from the
manifest instead of stopping with “run refresh first”, and says that files the
manifest does not list are not included. When the repo maintains a manifest,
pull also notes when the manifest has changed since this index was
reconciled, so another host has pushed files this index may not list yet.
Changed in version 2.4.0: --index checks this machine’s index instead of the manifest (#169).
verify --index compares every index entry with a listing of its remote
directory: one listing per directory, plaintext size always, sha1 where both sides
have one. It reads no local file, so it is practical on a host whose filesystem is
too slow for status --remote. Directories holding offloaded (metadata-only)
entries are listed first, since Drive holds those files’ only copy. Each entry is
ok, missing, remote-larger, remote-smaller, digest-differs,
unsized (Drive listed no plaintext size) or unlisted (its directory’s listing
failed). Without --repair nothing changes.
verify --index --repair applies what the check proves, and only that:
a present entry whose file is still here, and whose Drive copy is missing or differs, is dropped from the index. The file is then local-only: never counted as synced or offloaded, and uploaded by the next
push;an entry whose file is gone (or is only a git-LFS pointer stub), and whose Drive copy is larger than recorded (a stub indexed as content, #32), is rewritten to describe Drive’s copy, metadata-only, so
pullrestores it;a metadata-only entry that matches and has no sha1 yet gains Drive’s;
a copy only Drive holds that is shorter, different or gone is reported and left exactly as it was: rewriting the entry would hide the loss.
When every entry was checked, the index is recorded at the current check level
(a top-level check_level key in index.json). upgrade runs the same
re-verification on an index below the current level: one an earlier release wrote,
or one recorded before a release made a check stricter.
Enabling it on an existing repo:
protonfs verify --repair # build it from a full listing
protonfs config set defaults.manifest true # keep it current on push/rm
git add .protonfs/config.json && git commit -m "maintain the protonfs manifest"
protonfs refresh # on each host: record its generation
Set PROTONFS_NO_MANIFEST on a host to switch every manifest read and write
off there, whatever the repo config says.
install-drive¶
protonfs install-drive¶
Download and verify the official proton-drive CLI binary.
Usage
protonfs install-drive [OPTIONS]
Options
- --version <version>¶
proton-drive version to install (default: pinned).
- --skip-keyring¶
Do not prepare the OS keyring after installing.
Downloads the official proton-drive CLI binary for the current platform
(linux-x64 requires AVX2, linux-arm64, macOS x64/arm64), verifies its SHA-512
against a pinned checksum before installing it (never installs an unverified
binary), and by default also prepares the OS keyring proton-drive will use to
store its session — done here, not at first login, so a keyring failure surfaces
before a browser sign-in is thrown away.
Examples:
protonfs install-drive
protonfs install-drive --version 0.5.0
protonfs install-drive --skip-keyring
upgrade¶
protonfs upgrade¶
Upgrade proton-drive to the highest supported version + migrate repo state.
A protonfs release only ever upgrades proton-drive to its own highest supported version; a newer upstream release requires a newer protonfs (reported, never installed). Inside a protonfs root, pending repo-state migrations run too.
Usage
protonfs upgrade [OPTIONS]
Options
- --check¶
Report what would happen; change nothing. Exit 0 if fully current, 1 if an upgrade or migration is available.
- --drive-only¶
Only the proton-drive binary; skip migrations.
- --repo-only¶
Only repo-state migrations; skip the binary.
Upgrades the installed proton-drive binary to the highest version this
protonfs release supports (SHA-512-verified before an atomic swap; a newer
upstream release is reported but never installed), verifies the session survived
the swap, and – inside a protonfs root – runs any pending repo-state
migrations. See Upgrading for the full upgrade story.
Changed in version 2.4.0: An index recorded under an older check level is re-verified against Drive, as
verify --index --repair does, once per level (#169). It lists every indexed
remote directory, so it can take minutes on a large repo. If Drive throttles or
the repo is locked, the failure is reported, the rest of the upgrade stands, and
the next upgrade tries again.
Examples:
protonfs upgrade --check # what would happen?
protonfs upgrade # binary + migrations
protonfs upgrade --repo-only # just bring .protonfs/ current
doctor¶
protonfs doctor¶
Check this host can run proton-drive (binary, session bus, OS keyring).
Usage
protonfs doctor [OPTIONS]
Options
- --fix¶
Repair what protonfs can (bootstrap the keyring).
Checks that this host can actually run proton-drive: the binary is present
and runnable, and on Linux, that a D-Bus session bus and a usable (unlocked)
Secret Service keyring are reachable. Written for headless hosts (SSH, no
desktop), where a graphical login’s sealed login.keyring is the most common
silent failure.
Examples:
protonfs doctor
protonfs doctor --fix
shell-init¶
protonfs shell-init¶
Print shell exports so proton-drive run by hand sees the same keyring.
Usage
protonfs shell-init [OPTIONS]
Prints export VAR=value lines so that running the proton-drive binary by
hand (outside of protonfs) sees the same session bus/keyring environment
protonfs sets up for itself. Every protonfs command does this internally;
this is only needed for manual proton-drive invocations.
Example:
eval "$(protonfs shell-init)"
proton-drive filesystem list /my-files
completions¶
protonfs completions¶
Print or install shell completion (bash|zsh|fish).
Command names, per-subcommand options, and the global flags (in any position) all complete.
Usage
protonfs completions [OPTIONS] {bash|zsh|fish}
Options
- --install¶
Install the completion script (idempotent).
- --uninstall¶
Remove the installed completion script.
Arguments
- SHELL¶
Required argument
Prints, installs, or removes shell completion for bash, zsh, or fish. With
--install it writes the generated script and wires it into your shell config
(idempotent, marker-delimited); --uninstall removes it. Installed completions are
refreshed automatically by protonfs upgrade. Global flags
complete after a subcommand too, matching the position-independent argv handling.
Added in version 1.5.0.
Examples:
protonfs completions bash # print the script to stdout
protonfs completions zsh --install # install + wire into ~/.zshrc
protonfs completions fish --uninstall
schedule¶
protonfs schedule¶
Manage scheduled cron jobs (push, pull, sync, offload, prune) for this repo.
Bare protonfs schedule lists the jobs (it never installs implicitly). --add
installs a job (needs a cadence: --every/--cron/--at) and prints its id;
--uninstall <id> (or -U, accepting the id or a --list index) removes one,
--uninstall --all removes them all. Each job runs under flock with an absolute
proton-drive path and tuned timeouts, logging to .protonfs/schedule/<id>.log.
--path takes a subtree or a glob pattern. A pattern is stored (and passed to
push/pull) unexpanded, so protonfs re-expands it on every run – one job can cover a
whole family of runs and keeps matching as new ones appear:
protonfs schedule --add --every daily --command pull --path 'mload*/*.ev'
Jobs on one repo never run at the same time: each waits (up to 30 minutes) for the others, then skips that run. A job that would fight one already scheduled on overlapping files is refused, or added with a warning:
Added in version 1.8.0.
Changed in version 1.11.0: --path accepts a glob pattern, re-expanded at run time (#131). Added
--strict.
Changed in version 2.2.0: offload and prune jobs, --min-age/--keep, conflict checks, and one
job at a time per repo (#158).
Changed in version 3.0.0: Added --deletions for push and sync jobs and --no-restore for pull and
sync jobs (#197).
Changed in version 3.4.0: Run from a subdirectory of a store it finds the store, PATH is read relative to the current directory, and with no PATH it acts on that subdirectory (#232).
Usage
protonfs schedule [OPTIONS]
Options
- --list¶
List this machine’s scheduled jobs.
- --add¶
Install a new job from the options below.
- -U, --uninstall <ID>¶
Remove the job with this id (or –list index). Use –all to remove every job.
- --all¶
Remove every scheduled job.
- --every <SPEC>¶
Cadence: hourly | daily | weekly | <N>h | <N>m.
- --cron <EXPR>¶
Raw 5-field cron expression.
- --at <HOURS>¶
Run daily at these hours (0-23, comma-separated).
- --command <command>¶
What the job runs: sync = pull then push; offload = push, then offload the same scope; prune = protonfs prune (which pushes first).
- Default:
'push'- Options:
push | pull | sync | offload | prune
- --path <PATHSPEC>¶
Scope the job to a subtree, or to a quoted glob pattern that protonfs re-expands on every run (see the examples below).
- --resolve <sched_resolve>¶
Conflict strategy passed to push/pull.
- --strict¶
Pass –strict to push/pull, so a run whose –path pattern matches nothing fails.
- --min-age <DURATION>¶
Settle window passed to push, offload and prune jobs (e.g. 30m, 1d); default: push holds nothing back, offload/prune use 1d.
- --keep <sched_keep>¶
Newest files per directory a prune job keeps; default: prune’s (10).
- --deletions <sched_deletions>¶
Deletion policy passed to a push or sync job’s push (see push –deletions); default: the repo’s defaults.deletions.
- Options:
keep | trash
- --no-restore¶
Pass –no-restore to a pull or sync job’s pull (see pull –no-restore), so a run leaves files deleted or moved locally for push instead of restoring them.
- --label <label>¶
Human label shown in –list.
- --json¶
With –list, emit JSON.
Installs, lists, and removes cron jobs that run push,
pull, both (sync), offload or
prune on a schedule. Bare protonfs schedule lists this machine’s
jobs (it never installs implicitly); --add with a cadence
(--every hourly|daily|weekly|<N>h|<N>m, or a raw --cron expression, or
--at hours) installs one and prints a short id; --uninstall <id> (-U, also
accepting a --list index) removes it, and --all removes them all.
Each job runs a generated wrapper under flock (no overlapping runs), with an
absolute proton-drive path (cron has no useful PATH) and tuned list/transfer
timeouts, logging to .protonfs/schedule/<id>.log. Jobs are recorded per-device in
.protonfs/schedule.local.json (gitignored). --command sync runs pull then push.
A sync job’s pull restores files deleted or moved away locally since the last
run, as a bare pull does, so its push never sees those changes. Add
--no-restore (pull and sync jobs; passed to the pull only) when local changes
should win: the pull leaves them alone (local-deleted= in the log) and the push
applies local moves on Drive and, with --deletions trash (push and sync jobs;
passed to the push only), trashes local deletions there (moved=, trashed= and
the deletions it kept, local-deleted=, on the push’s summary line). --add for a
sync job prints a note on what its options leave implicit: a pull that restores
local deletions (no --no-restore), deleted files kept on Drive (keep policy),
or no --resolve (a file changed on both sides is reported and left alone every
run).
Changed in version 3.0.0: --deletions, --no-restore, and the note when adding a sync job.
--command offload pushes the job’s scope, then offloads it. --command prune
runs protonfs prune, which pushes first itself. Both pass --min-age through,
and prune also --keep; without them the commands’ own defaults apply (1d,
10). An option the command would ignore (--keep on a non-prune job,
--min-age on pull/sync, --resolve/--strict on prune, --deletions on
pull/offload/prune, --no-restore on push/offload/prune) is refused.
Added in version 1.8.0.
Changed in version 1.11.0: --path accepts a glob pattern, re-expanded on every run. Added --strict.
Changed in version 2.2.0: offload and prune jobs, --min-age/--keep, conflict checks, and one
job at a time per repo.
One job at a time per repo¶
Every wrapper takes two locks. Its own lock (flock -n) means a job never
overlaps itself: a run that finds the previous one still going logs a skip. The
repo’s shared schedule lock, .protonfs/schedule/repo.lock (flock -w), means
different jobs on one repo take turns. A job waits up to 30 minutes for another to
finish, then logs a skip and exits 0; its next run tries again. So a nightly
prune can never overlap a scheduled push, and neither fails on protonfs’s own
repo lock.
Conflicting jobs¶
--add compares the new job with the jobs already scheduled for the repo. Only
jobs whose scopes overlap are compared. Two scopes overlap when one contains the
other (sim contains sim/run1/*.ev) or when their patterns could match the
same path; when unsure, protonfs assumes they overlap.
New job vs existing job, overlapping scopes |
Result |
Why |
|---|---|---|
Same command, identical scope |
refused |
a duplicate |
|
refused |
offload and prune jobs already push their scope first; schedule them alone |
|
refused if identical, warning if overlapping |
opposite directions on the same files; one |
|
refused |
one removes local copies the other brings back |
|
refused |
offload would remove the newest files prune keeps |
Same command, overlapping but not identical scopes |
warning |
the two repeat each other’s work on the shared files |
A refused job is a usage error (exit 2) and nothing is installed. A warning is
printed on stderr and the job is installed.
Scoping a job with a pattern¶
--path takes a subtree or a glob pattern. The pattern is stored unexpanded and
written into the wrapper quoted, so cron’s shell leaves it alone and protonfs expands
it fresh on every run. That is the difference that matters for scheduling: a shell
glob is expanded once, when you install the job, and is frozen from then on — a
pattern keeps matching as new runs appear, with no need to reinstall the job.
This makes two otherwise inexpressible setups routine — pulling one family of runs while leaving the rest deliberately offloaded, and pulling only the small time-series files out of directories whose dumps are far too large to want locally:
protonfs schedule --add --every daily --command pull --path 'mload*'
protonfs schedule --add --every daily --command pull --path 'mload*/*.ev'
Note the quotes: without them your shell expands the pattern before protonfs sees it, and you get a job frozen to whatever matched at install time (the older behaviour).
By default a run whose pattern matches nothing is reported in the job log and treated
as a no-op, which is usually what you want — a pattern for runs that do not exist
yet should not fail nightly. Pass --strict when a job’s pattern is expected to
always match something, and a run that matches nothing should fail loudly instead:
$ protonfs schedule --add --every daily --command pull --path 'mload*' --strict
Examples:
protonfs schedule --add --every daily --at 1,3,5 # nightly at 01/03/05h
protonfs schedule --add --cron "0 */6 * * *" --command sync
protonfs schedule --add --every daily --command pull --path 'mload*/*.ev'
protonfs schedule --add --every daily --command prune --path sim --keep 10 --min-age 1d
protonfs schedule --list
protonfs schedule --uninstall a1d3ae
protonfs schedule --all # remove every job
auth¶
protonfs auth¶
Authenticate the proton-drive CLI: login | logout | status.
Usage
protonfs auth [OPTIONS] {login|logout|status}
Arguments
- ACTION¶
Required argument
login/logout— passthrough toproton-drive auth <action>with inherited stdio, so an interactive login URL/prompt reaches your terminal directly. Exit code is whateverproton-drivereturns.status— checks for a valid session directly (without invokingproton-drive), printingauthenticatedor a reminder to log in. Exit0if authenticated,1otherwise.
Examples:
protonfs auth login
protonfs auth status
protonfs auth logout
trash¶
protonfs trash¶
Inspect and empty Proton Drive’s trash (#70).
Usage
protonfs trash [OPTIONS] COMMAND [ARGS]...
Commands
- empty
Permanently empty /trash for the whole…
- list
List /trash: name, original parent path,…
Groups the /trash inspection and account-wide emptying operations.
trash list¶
protonfs trash list¶
List /trash: name, original parent path, same-name duplicate count.
The parent is found by searching the repo’s remote root (bounded); it shows
(not under <root>) or (not found within search limit) when it can’t be resolved.
A nonzero duplicate count is the ambiguity restore refuses to resolve on its own (#56): proton-drive resolves /trash paths by name, first match wins.
Usage
protonfs trash list [OPTIONS]
Lists every item currently in /trash: its name, its original parent path, and
how many other trashed items share the same name. A nonzero duplicate count is
exactly the ambiguity restore can refuse to resolve on its own (#56): proton-
drive resolves /trash paths by name, first match wins, so same-named entries
can silently block a restore or shadow one another.
proton-drive cannot look a folder up by its UID alone, so the original parent is found
by searching the remote_root subtree (at most 200 folder listings or two
minutes). A parent that could not be placed is marked rather than guessed:
(not under <remote_root>) when the whole subtree was searched without finding it (it is elsewhere, or was
permanently deleted),
(not found within search limit) when the search was cut short,
(trashed folder <name>) when the parent is itself in the trash, and (unknown)
when the entry names no parent.
Changed in version 3.4.0: The original parent is shown as a path; it was ? for every item (#231).
Examples:
protonfs trash list
trash empty¶
protonfs trash empty¶
Permanently empty /trash for the whole account (irreversible, account-global).
Requires typing an exact confirmation phrase unless –yes is passed. This is NOT scoped to this repo’s remote_root – it empties every trashed item on the account.
Usage
protonfs trash empty [OPTIONS]
Options
- --yes¶
Skip the typed confirmation prompt.
Permanently empties /trash for the whole Proton Drive account by calling
proton-drive filesystem empty-trash. This is irreversible and not
scoped to this repo’s remote_root — it deletes every trashed item on the
account, including ones unrelated to this repo. Without --yes, the command
prints that warning and requires typing an exact confirmation phrase; anything
else aborts without emptying trash.
Deliberately out of scope: permanently deleting a single trashed item by UID.
proton-drive does not accept node UIDs for /trash paths (see rm’s
duplicate-basename limitation above and #56’s analysis), so there is no safe way
to target one item there — use trash list to find and resolve duplicates via
the Drive web UI, or trash empty to clear everything.
Examples:
protonfs trash list # see what's there and any duplicates
protonfs trash empty # prompts for typed confirmation
protonfs trash empty --yes # scripts / non-interactive use
config¶
protonfs config¶
Get/set protonfs config (#21): env > local > shared > global > built-in default.
Usage
protonfs config [OPTIONS] COMMAND [ARGS]...
Commands
- get
Print the RESOLVED value of KEY (e.g.
- set
Set KEY = VALUE.
Reads or writes protonfs’s layered configuration. Known keys:
remote_root, device_id, defaults.on_conflict,
defaults.low_io, defaults.event_log,
defaults.progress_style, defaults.manifest,
defaults.skip_thumbnails, defaults.deletions (each defined in the
Configuration section above).
config get¶
protonfs config get¶
Print the RESOLVED value of KEY (e.g. remote_root, defaults.low_io).
Usage
protonfs config get [OPTIONS] KEY
Arguments
- KEY¶
Required argument
Always prints the fully resolved value across every layer (env var > per-device local config > shared per-repo config > global user config > built-in default) — see Stability Promise (M4.1) for the complete precedence list and the environment variables that can override each key.
Examples:
protonfs config get remote_root
config set¶
protonfs config set¶
Set KEY = VALUE. Default scope is the shared per-repo config (committed).
Usage
protonfs config set [OPTIONS] KEY VALUE
Options
- --global¶
Write to the global user config.
- --local¶
Write to the per-device local config.
Arguments
- KEY¶
Required argument
- VALUE¶
Required argument
Writes to exactly one layer:
default (no flag) — the shared per-repo file,
.protonfs/config.json(the file you commit, so every clone syncs to the same place).--local— the per-device file,.protonfs/config.local.json(gitignored).--global— the user-wide file,~/.config/protonfs/config.json(orPROTONFS_CONFIG).
--global and --local are mutually exclusive.
Examples:
protonfs config set defaults.low_io true --local
protonfs config set remote_root /my-files/sim-data --global
See also¶
The Configuration section above for every config key (
remote_root…) and environment variable (PROTONFS_CONFIG…) as cross-referenceable definitions.Stability Promise (M4.1) for the frozen exit-code/option contract.
Durability and Drift-Resolution Guarantees for durability and drift-resolution guarantees.
Getting Started and Syncing across machines for workflow-oriented walkthroughs.