Yesterday, I tried to explain some of the oddities you will encounter if you enable iCloud’s Desktop & Documents Folders option in High Sierra, and those which developers and scripters need to be aware of.

Today, I will walk you through some of these with the aid of screenshots from a new version of my free tool Cirrus, which I have improved so that it gives full coverage of this situation. If you want to see inside iCloud Drive, you’ll find it a powerful and flexible tool at last.

Using iCloud Drive without enabling the Desktop & Documents Folders option is confusing and frustrating in parts, but to experience the real thing, you should try enabling that option. Here are the results in macOS High Sierra 10.13.4. These are shown in the GUI, for which I am using an Open File dialog with hidden items displayed, and in Cirrus’s iCloud Browser, which sees what FileManager makes of it all. The latter is very similar to what you will encounter in shell scripts and commands, in Terminal.

Select iCloud Drive in the iCloud section of the sidebar, and this an example of what you’ll see. This is a mixture of:

• user-created folders, such as backup1,
• public containers created by apps, such as Keynote,
• Desktop, and the two Documents items, one of which is a symbolic link (symlink) to the ~/Documents folder which is now in iCloud.

The folder ~/Library/Mobile Documents/com~apple~CloudDocs is the closest thing to iCloud Drive, but only lists three folders which were user-created, and the symlink to Documents. Note that there is no matching symlink to Desktop. Cirrus can now follow such symlinks, to make access to a shared Documents folder easier.

The public containers are among those other folders in ~/Library/Mobile Documents, which is shown here. There are no simple rules which determine which of these other folders are shown in the GUI: com~apple~CloudDocs is shown as iCloud Drive, and com~apple~Keynote appears inside iCloud Drive. However, com~apple~ScriptEditor2 isn’t shown inside iCloud Drive, but some of the folders with names starting with letters and digits do appear inside iCloud Drive.

Cirrus displays the Container associated with a folder, which helps you work out which item in the GUI corresponds to which folder here. The GUI displays them by Container name, not that of the folder as seen by the file system.

Adding a file to your shared Documents folder, here by taking a screenshot, results in that file being created in your real ~/Documents folder, then uploaded to iCloud. This is marked by the appearance of a plain iCloud item, without an arrow, and the circular progress icon in the sidebar. The latter is actually incorrectly placed here, and should be shown next to the open Documents item in the iCloud list.

I’m running this Mac with Optimize Mac Storage turned on, so all new files in ~/Documents are stored locally and in iCloud until local storage runs short. However, the files and folder with iCloud+arrow icons have been evicted from local storage, so don’t take up much of my SSD. I haven’t been able to discover a built-in method of doing this, but Cirrus makes such evictions easy. Unless you try to access those evicted items, they will not be downloaded, unless you turn Optimize Mac Storage off.

This is reflected in the file system, but note the different names here. For example, the file shown in the GUI as Untitled.rtf (evicted) is actually .Untitled.rtf.icloud, a stub file of only 160 bytes. The moment that it is downloaded, its name returns to Untitled.rtf, and attempts to access it under its stub file name are doomed to fail.

I then used Cirrus’s menu command to evict all documents from my ~/Documents folder, and their status icon changed almost immediately to reflect that.

Here’s the same Documents folder viewed on a Mac running Sierra, connected to the same iCloud Drive. On this Mac, Optimize Mac Storage is turned on and there is no pressure on local storage, so all additions to the other Mac’s ~/Documents folder are quickly downloaded to this Mac. All these files and folders are held locally, and should automatically be kept in synchrony with the other Mac. This includes files added to this iCloud folder by any Mac (or iOS device) which has access to the same iCloud account.

Cirrus version 1.0b5 gives full access to iCloud folders including ~/Documents and ~/Desktop, now saves text listings of iCloud folders with full details of each item’s iCloud status, and has several other important changes. It is available from here: cirrus10b5
and from Downloads above.