Under iCloud in the Settings app, I have "Optimize Mac Storage" checked and "Desktop & Documents Folders" checked under "Apps that store documents and data in iCloud will appear here:"

enter image description here

This will cause some files in my "Documents" folder to be offloaded and replaced with a small file ending in ".icloud". I can download them by clicking on the cloud icon in the detail view in the Finder. I can also use "find" from the command line to show which files have been offloaded, eg "find . -name *.icloud | more".

Is there a command line way to cause these files to be downloaded, either by file or directory?

4 Answers 4


Scott Garret and Allan’s answer above is very close.

In the terminal, however, each *.icloud file is prefixed with a . when NOT downloaded.

For example, a directory called foo with optimised (i.e., offloaded to icloud) files a.txt and b.txt will look like this

$ cd foo
$ find . -name '.*icloud’

To resolve (i.e., download) the files from icloud, you need to pass the path to the resulting path to /usr/bin/brctl.

Thus, the following works.

find . -name '.*icloud' | perl -pe 's|(.*)/.(.*).icloud|$1/$2|s' | while read file; do brctl download "$file"; done

You can monitor the download activity as per this answer as follows :

brctl log -w --shorten

(There appears to be a bug where the full documented --wait flag isn't recognized.)

  • 1
    Slightly more robust and shorter: find . -name '.*icloud' | sed 's|\.\([^/]*\)\.icloud$|\1|g' | while read fn; do brctl download "$fn"; done Commented Jun 9, 2020 at 23:01
  • 6
    Here's another: find . -type f -name "*.icloud" -exec brctl download {} \;
    – mrplants
    Commented Sep 11, 2020 at 20:14
  • For brctl log --wait --shorten I get unrecognized option --wait, but -w worked for me.
    – mpoisot
    Commented Dec 3, 2020 at 18:48
  • Interesting, @mpoisot. man brctl suggests both are possible, at least on Catalina.
    – ldeck
    Commented Dec 23, 2020 at 10:13

The command you are looking for is brctl (located in /usr/bin). man brctl will tell you all you need, but basically just brctl download /path/to/filename (without the .icloud extension) and evict will purge the locally cached copy.

  • Really nice! I much prefer using built in utilities! Oh...and Welcome to Ask Different!
    – Allan
    Commented Feb 18, 2020 at 20:58
  • 2
    Awesome to learn about evict! It boggles my mind why they don't expose this in Finder.
    – mpoisot
    Commented Dec 3, 2020 at 18:50
  • Nevermind. I see that MacOS Catalina added this to Finder. Also it looks like evict no longer works on the command line (?). I get an Operation not supported error.
    – mpoisot
    Commented Dec 3, 2020 at 19:12
  • In case anyone's wondering, brctl download is asynchronous (just like when executed using the GUI). Commented Aug 22, 2023 at 4:44

To my knowledge, there is no command included that allows you to directly download an iCloud file or folder.

But since I had exactly the same problem as you, I found that it was possible to do it in Swift with the startDownloadingUbiquitousItem function.

So I wrote a really simple Swift script for downloading both folder and file. You can download it on Github: iCloud Downloader

I hope I have answered your issue.


I found the iCloud files were in a Mobile Documents directory. So to cut short time there, I focused the script just to that. Also fixed the issues based on comments from members above.

This is my icloudforcesync.sh file content (make sure you apply chmod +x icloudforcesync.sh to make it exeutable):


icloudDir="~/Library/Mobile Documents/"
find "${icloudDir}" -name '.*icloud' | perl -pe 's|(.*)/.(.*).icloud|$1/$2|s' | while read file; do brctl download "$file"; done

brctl log -w -t

Do comment if there's more improvements that can be introduced to this or if there are other better ways.


You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .