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?

3 Answers 3


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 --wait --shorten
  • 1
    Slightly more robust and shorter: find . -name '.*icloud' | sed 's|\.\([^/]*\)\.icloud$|\1|g' | while read fn; do brctl download "$fn"; done Jun 9, 2020 at 23:01
  • 4
    Here's another: find . -type f -name "*.icloud" -exec brctl download {} \;
    – mrplants
    Sep 11, 2020 at 20:14
  • For brctl log --wait --shorten I get unrecognized option --wait, but -w worked for me.
    – mpoisot
    Dec 3, 2020 at 18:48
  • Interesting, @mpoisot. man brctl suggests both are possible, at least on Catalina.
    – ldeck
    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
    Feb 18, 2020 at 20:58
  • 1
    Awesome to learn about evict! It boggles my mind why they don't expose this in Finder.
    – mpoisot
    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
    Dec 3, 2020 at 19:12

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.

You must log in to answer this question.

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