CLI: support cloud → local direction in `bm cloud sync`

[phernandez]

Summary

bm cloud sync --name X is currently hardcoded as a one-way local → cloud mirror (makes the cloud bucket identical to local). Underlying rclone sync supports a remote as either the source or the destination, so we can expose the reverse direction (one-way cloud → local) without changing transport.

Motivation

Today the only way to pull cloud state down to local is bm cloud bisync (two-way) or a snapshot restore. There's no one-way pull equivalent of the upload sync. Useful cases:

• Hydrating a fresh machine from cloud without establishing a bisync baseline
• Forcing local to match cloud after manual cloud edits (e.g., web UI, API)
• Recovery / re-mirror when local bisync state is corrupt and --resync is too risky
• Symmetry with bm cloud sync (upload) — a bm cloud pull (download) reads naturally

Current state

project_sync() in src/basic_memory/cli/commands/cloud/rclone_commands.py:187 builds:

rclone sync <local_path> <remote_path> ...

…with source/dest hardcoded.

Proposed change

Add a direction option. Two reasonable shapes — pick one:

Option A — flag on existing command:

bm cloud sync --name research                       # default: local → cloud (unchanged)
bm cloud sync --name research --direction pull      # cloud → local

Option B — separate command (clearer intent, harder to misuse):

bm cloud sync  --name research   # local → cloud (unchanged)
bm cloud pull  --name research   # cloud → local

Either way, the implementation in project_sync() swaps the source/dest args to rclone sync. Because rclone sync is destructive on the destination, the cloud → local direction will delete local files not present in the cloud — --dry-run must be the default suggestion in the docs and surfaced prominently in the command help.

Open questions

• Should --direction pull be gated behind a confirmation prompt (or require --force) given it can delete local files?
• Does the existing bisync filter (get_bmignore_filter_path()) compose correctly when the cloud side is source? (Likely yes, since filters apply to both sides — worth verifying.)
• Interaction with per-project cloud routing and bisync state: pulling should probably not touch bisync metadata, but we should think through whether a subsequent bisync needs --resync after a pull.

Test plan

• One-way cloud → local with a clean local dir matches cloud contents
• One-way cloud → local with extra local files deletes them (and --dry-run reports it without doing so)
• .bmignore filters apply correctly with cloud as source
• Subsequent bm cloud bisync behavior after a pull is documented and sane

[claude]

Claude finished @phernandez's task in 1m 29s —— View job

---

Triage Analysis

• Read issue and gather context
• Read relevant source files
• Check for duplicate issues (none found)
• Classify and label issue
• Provide triage summary

---

Classification

Field	Value
Type	Enhancement / Feature Request
Priority	Medium
Component	CLI, Cloud
Complexity	Medium

Labels applied: enhancement, cloud

---

Analysis

No duplicate issues found. This is a well-scoped feature request with clear motivation.

Current state (confirmed from source):

project_sync() in rclone_commands.py:222 hardcodes:

cmd = ["rclone", "sync", str(local_path), remote_path, ...]

The CLI wrapper in project_sync.py:92 exposes this as bm cloud sync with no direction option.

Recommended approach: Option B (separate bm cloud pull command)

A separate command is preferable over a --direction flag because:

• The destructive difference between push and pull is immediately visible from the command name
• bm cloud sync (upload) vs bm cloud pull (download) maps cleanly to mental model
• No risk of accidentally passing wrong direction via flag — especially in scripts

Implementation notes:

1. rclone_commands.py — project_sync(): Add a direction: Literal["push", "pull"] = "push" parameter. When direction == "pull", swap source/dest:

   if direction == "pull":
       src, dst = remote_path, str(local_path)
   else:
       src, dst = str(local_path), remote_path

   Also note: --local-no-preallocate is a local-filesystem flag — it should only be added when local is the destination (pull direction). Currently it's always added as source; confirm whether it's safe on source too or should be conditional.

2. project_sync.py — new pull command: Mirror sync_project_command with:

   • Direction set to "pull" when calling project_sync()
   • A prominent --dry-run suggestion in the help text
   • A confirmation prompt (or --force requirement) before proceeding, since pull deletes local files not present in cloud

3. .bmignore filters: Filters apply symmetrically in rclone — no changes needed. The get_bmignore_filter_path() call can be reused as-is.

4. Bisync interaction: Pull should NOT touch bisync state. If bisync has been initialized, a subsequent bm cloud bisync should still work without --resync (since bisync detects actual file deltas), but this is worth verifying in tests.

Open questions to resolve before implementation:

• Should bm cloud pull require --force or show an interactive y/N prompt given it deletes local files? Recommend: interactive prompt by default, --force to skip it in scripts.
• Is --local-no-preallocate safe when local is the sync source (current push behavior) or only needed as destination? Worth checking rclone docs — it may be a no-op on source.

Test plan from issue looks solid. Add a case for the confirmation prompt bypass (--force) if that's implemented.

[phernandez]

Update: split into push / pull with Teams-safe semantics

In light of Teams support (see #849, #851), the original "add --direction pull" shape isn't quite right — rclone sync is destructive on the destination, which is the whole problem we're trying to avoid for shared workspaces. Revised proposal:

Verb	rclone command	Destructive on…	Personal	Teams
bm cloud pull --name X	rclone sync remote: local/	your own local	✅	✅
bm cloud push --name X	rclone copy local/ remote:	nothing (additive)	✅	✅
bm cloud sync --name X	rclone sync local/ remote:	shared bucket	✅	❌ (block per #849)
bm cloud bisync --name X	rclone bisync …	both sides	✅	❌ (block per #849)

Why push uses rclone copy, not rclone sync

If a teammate added or edited a note since your last pull, a local → cloud mirror (rclone sync) would delete their additions and overwrite their edits to make the cloud identical to your local. Last-writer-wins with collateral damage.

rclone copy is additive — it uploads new/changed files but never deletes on the destination. Same-file edit conflicts still resolve as last-writer-wins (which is acceptable for a file-level CLI primitive); for conflict-aware edits, writes should go through the MCP/API path.

Why keep sync and bisync at all

For Personal workspaces, the mirror semantics are useful and correct (one user, one source of truth). They just get gated to Personal-only per #849.

Implementation sketch

project_sync() in rclone_commands.py:187 becomes parameterized on:

• direction (local→cloud | cloud→local)
• mode (sync | copy)

Then the four verbs (sync, bisync, push, pull) are thin command wrappers that pick the right combination and apply the Teams gate.

Open questions

• Should pull also have a --copy variant (additive download, doesn't delete local files missing from cloud)? Useful for hydrating without risk.
• Workspace-type detection for gating: presumably reuse whatever Block rclone sync/bisync commands for Team workspaces with clear errors #849 lands on.

[groksrc]

I think the push/pull split is the right short-term shape, and I would keep that separate from the longer-term "Team mirror sync" story.

For Teams, the thing we need to avoid is not rclone itself. It is letting one client's stale local tree become authoritative for shared cloud state. pull is safe because the destructive side is only the caller's local directory; push is Team-safe if it uses additive copy semantics. sync/bisync should remain Personal-only because they can delete or overwrite shared remote state.

Even if files do not change fast enough for locking to matter, a sync baseline still matters because it distinguishes intentional deletes from stale clients that simply have not pulled a teammate's newer file yet.

For a real Team mirror workflow, I think we eventually need an app-owned reconciler instead of raw mirror semantics:

1. Store a per-client sync baseline/manifest: path, content hash/mtime/size, last seen cloud revision/version, and tombstones/deletes.
2. On each run, compare three states: baseline, current local tree, current cloud manifest.
3. Apply changes only when intent is unambiguous:
   • local changed, cloud unchanged since baseline: upload
   • cloud changed, local unchanged since baseline: download
   • local deleted, cloud unchanged since baseline: delete/tombstone cloud
   • cloud deleted, local unchanged since baseline: delete local
4. If both local and cloud changed since baseline, create a conflict copy or punt to API/MCP conflict-aware handling rather than overwriting.
5. Keep rclone as the byte-transfer engine if useful, but let Basic Memory decide operations from revision-aware metadata.

That gives us a path to Teams-safe mirror behavior without treating a local folder snapshot as the source of truth. It also keeps the current guard wording clean: Teams block mirror-style sync/bisync, but can still support Team-safe pull/push.

[phernandez]

claude confused what I was saying.

[groksrc]

Follow-up after tightening the #849/#855 wording: I would make the short-term guard bisync-only, not sync/bisync.

That means:

• bm cloud sync --name X can remain available for Team workspaces as the one-way/manual operation.
• bm cloud bisync --name X and bm cloud bisync-reset X stay Personal-only.
• The CLI guidance for Team workspaces can be direct: "The bisync operation is only supported on Personal workspaces. Use bm cloud sync --name X instead."

The longer-term three-way reconciler idea still applies, but specifically for a Team-safe bidirectional/mirror workflow. We would still want a per-client baseline/manifest and revision-aware comparison of baseline, local, and cloud state before letting a Team workspace do anything that behaves like continuous two-way sync.

[groksrc]

Opened #862 to track the longer-term Team-safe bidirectional sync design using Tigris snapshots as the remote baseline.

I still think the short-term push / pull split in this issue is the right primitive layer, while #862 covers the app-owned reconciler needed before Team workspaces get anything that behaves like true bidirectional local mirror sync.

[phernandez]

Decision: ship push / pull as git-style, fail-safe primitives

After working through the Teams semantics, here's the finalized design we're implementing. Guiding principle: be clear, let the user decide, no surprises — nothing destructive happens without the user spelling out who wins.

Command surface

Command	rclone (clean path)	Default on conflict	Destructive on
bm cloud pull --name X	copy (cloud → local), new files only	abort + list conflicting paths	never deletes local
bm cloud push --name X	copy (local → cloud), new files only	abort + list conflicting paths	never deletes cloud
bm cloud sync --name X	sync (local → cloud mirror)	n/a	shared bucket → now Personal-only
bm cloud bisync --name X	bisync (two-way)	n/a	both sides → Personal-only (already gated, #849)

push/pull are Team-safe and ungated: pull's only destructive side is your own local, push is additive on cloud. sync becomes Personal-only (it's a destructive local→cloud mirror that can delete a teammate's files); its guard message points Teams at push/pull.

Conflict handling: like git pull/git push

A conflict is any file that exists on both sides and differs. By default the command aborts before transferring anything, lists the exact paths, and tells you the flag to resolve — exactly like git pull refusing to clobber local changes, or git push being rejected when the remote is ahead. One explicit knob:

• --on-conflict fail (default) — list conflicts, exit non-zero, transfer nothing.
• --on-conflict keep-local — local wins (pull: skip those files; push: overwrite cloud).
• --on-conflict keep-cloud — cloud wins (pull: overwrite local; push: skip those files).
• --on-conflict keep-both — keep yours, write the other side beside it as name.conflict-<date>.md so nothing is lost.
• --dry-run / --verbose throughout.

No vague --force, no interactive prompt to fat-finger. The flag value names what survives, so it reads the same in both directions.

Honest limitations (surfaced in --help + command output, not buried)

Because there is no sync baseline (the thing #862 adds):

1. Deletions don't propagate. Delete a note on one side and the other side keeps it — we can't distinguish "deleted" from "never synced." Stated plainly in output so a reappearing note is never a mystery.
2. Every divergence is treated as a conflict. Without a baseline we can't tell a teammate's edit from your stale copy, so any differing file prompts a decision rather than auto-resolving. This is intentionally conservative — it never silently loses data.

Comparison is content-based (rclone check); a large multipart-uploaded binary whose ETag isn't a plain MD5 may show as differing — acceptable for a notes vault.

Scope boundary vs #862

This is the dumb-but-safe byte-transfer primitive. Real three-way merge — auto-resolving unambiguous cases, propagating deletes, distinguishing both-edited from stale — requires the per-client manifest + Tigris-snapshot baseline tracked in #862. Conflict-aware editing continues to flow through MCP/API. We're deliberately not building a partial manifest here; #862 owns the baseline.

Implementation shape

• rclone_commands.py: extract a shared transfer builder; refactor project_sync onto it (no behavior change); add project_diff (conflict detection via rclone check --combined), project_push, project_pull.
• project_sync.py: new push/pull commands with --on-conflict/--dry-run; add the Personal-only gate to sync and reword the guard to name push/pull.
• Tests at both the rclone-argv level and the CLI command level (abort message, each strategy, Team-allowed for push/pull, Team-blocked for sync).
• --help text covers the Document cloud sync/bisync commands as Personal-workspace-only local mirror workflows #851 documentation ask in passing.