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.

-v

Adds curated phase narration, progress updates throttled to roughly every 30s, and phase durations.

-vv

Adds per-item paths (each file transferred/affected) and sub-steps; progress throttled to roughly every 5s.

-vvv

Adds INFO-level diagnostics; progress throttled to roughly every 1s.

-vvvv

DEBUG from every protonfs module, the proton-drive subprocess’s argv and stderr, and third-party library logging; progress updates continuously (no throttle).

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_DEVICE_ID

Per-key override for device_id.

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-drive binary 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 doctor warns when the cache is on such a mount. proton-drive creates the directory itself, so a location under /tmp survives 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 --add records 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-drive version install-drive installs when --version is not passed.

Added in version 1.0.0.

PROTONFS_DRIVE_SHA512

Explicit SHA-512 to verify a proton-drive download 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 (default 900), used by restore, trash list, rm --force, ls --trash and the trash pass of du /. On expiry the command fails with an error saying the trash is too large to list; nothing is changed. du instead 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, see PROTONFS_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. 0 turns the scaling off.

Added in version 2.5.0.

PROTONFS_CLOCK_SKEW

Per-key override for defaults.clock_skew (off, auto or 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 the Date of 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. With defaults.clock_skew set, the corrected offset is what is checked. Sync the clock (NTP) or set clock_skew rather 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 below 1 counts as 1; 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.manifest says.

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) or pass (password-store). The default, auto, tries keychain first and falls back to a protonfs-managed pass store 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. Native PROTON_DRIVE_CREDENTIALS_STORE, if already set in the environment, is passed straight through to proton-drive and takes precedence over this variable’s resolution.

Added in version 1.9.0.

PROTONFS_DU_REFRESH

Override for du.refresh: the age past which protonfs du re-checks a cached figure (a duration such as 5d or 2h45m, 0 for fresh values only, or never for 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 du cache 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 SyncState conflict. Overridable via PROTONFS_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, inline or lines. Overridable via PROTONFS_PROGRESS_STYLE.

Added in version 1.3.0.

defaults.batch_size
Type:
int
Default:
200

Most files sent in one proton-drive filesystem upload or download call. 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 a config get/config set key: set it in a config.json layer’s defaults object, or override it via PROTONFS_BATCH_SIZE.

Added in version 1.6.0.

defaults.manifest
Type:
bool
Default:
true

Keep the remote manifest (see verify) current on push and rm. Only an existing manifest is updated; protonfs verify --repair creates one. Set it in the shared config.json so every host maintains it. Overridable via PROTONFS_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/rm until protonfs verify --repair has built one.

defaults.skip_thumbnails
Type:
bool
Default:
false

Upload every file without a thumbnail (proton-drive’s --skip-thumbnails). Off, push still 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 via PROTONFS_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 --preload script handed to proton-drive (a Bun build) through BUN_OPTIONS; it changes the time proton-drive signs with, not the system clock. Overridable via PROTONFS_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. keep leaves Drive’s copy (and the index entry) alone; trash moves it to the Drive trash (protonfs restore puts it back on Drive) and drops it from the index. Overridden per run by push --deletions and per scheduled job by schedule --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 du figure may be before it is re-checked: a duration (5d, 2h45m, 1w, 1mo, 1y), 0 for fresh values only, or never for cache only. Global config only (protonfs config set --global du.refresh 2d), overridden by PROTONFS_DU_REFRESH and per run by du --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 %Plan column, e.g. 3TB or 500GB (decimal) or 2TiB (binary). Proton’s CLI cannot report it, so it has to be set by hand. Global config only, overridden by PROTONFS_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-delete is 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 --cached for each file, then git 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, and git add stages the file (and .gitignore);

  • one line per file goes into a # protonfs export block 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 PATH trashes one later. A kept copy is out of the store’s scope like any excluded file: status and ls (--remote too) leave it out, and pull and refresh never 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 next push.

  • both — fetch the remote copy alongside the local one under a .remote suffix (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:

  1. Push first (unless --no-push), so new files are on Drive before anything is considered.

  2. Choose candidates. A tracked file is one the index records as held locally, that is not excluded by .protonfs/ignore/include, and that lies within PATH. Tracked files are grouped by their immediate parent directory. In each directory the --keep most recently modified files (by local modification time; ties broken by path) stay local, and any other file that has not been modified for --min-age becomes a candidate. A file must be released by both rules.

  3. 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 --repair from a full listing, so it starts complete. push and rm keep an existing manifest current when defaults.manifest is on. They never start one mid-history, because such a manifest would look complete while missing everything uploaded before it.

  • Nothing destructive trusts it. offload always 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. verify is 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 pull restores 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:

- the same command on the identical scope: refused;
- push alongside offload or prune: refused (offload/prune push first themselves);
- push alongside pull: refused on the identical scope, warned when the scopes only
overlap (use one sync job); likewise sync alongside push or pull;
- offload or prune alongside pull or sync: refused (one removes what the other
restores);
- offload alongside prune: refused (offload would remove what prune keeps);
- the same command on overlapping scopes: warned.

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

push with offload or prune

refused

offload and prune jobs already push their scope first; schedule them alone

push with pull (or sync with either)

refused if identical, warning if overlapping

opposite directions on the same files; one sync job does both, in order

offload/prune with pull/sync

refused

one removes local copies the other brings back

offload with prune

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 to proton-drive auth <action> with inherited stdio, so an interactive login URL/prompt reaches your terminal directly. Exit code is whatever proton-drive returns.

  • status — checks for a valid session directly (without invoking proton-drive), printing authenticated or a reminder to log in. Exit 0 if authenticated, 1 otherwise.

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 (or PROTONFS_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