iCloud Drive Tips & Tricks

23 February 2024 • Last updated: 10 March 2024 • 8 min read • iCloud

What Is iCloud Drive?

iCloud Drive is Apple's cloud-based file storage and synchronization service. It allows you to store, organize, and collaborate on files and folders across all your Apple devices. Whether you're using a Mac, iPhone, iPad, or even accessing your files via iCloud.com, iCloud Drive ensures seamless synchronization.
iCloud Drive simplifies file management, collaboration, and access across your Apple ecosystem. Whether you're a student, professional, or creative, harness the power of iCloud Drive to keep your digital life organized and connected.

Must know commandline commands

Download ‘all’ files in the current & sub folders.
find . -type f -name "*.icloud" -exec brctl download “{}” \;

Download a specific file:
brctl download filename

Remove the local download of a file
brctl evict filename

View iCloud log:
brctl log -w --shorten

Diagnose errors:
brctl diagnose

Debugging & more

If you are having issues with iCloud Drive, you can use the following commands in terminal to help diagnose the problem.

Check iCloud Progress:
brctl monitor com.apple.CloudDocs|grep %

Check iCloud Download Progress:
brctl monitor com.apple.CloudDocs|grep ↓

Check iCloud Upload Progress:
brctl monitor com.apple.CloudDocs|grep ↑

Check iCloud Errors:
brctl log -w --shorten

Check iCloud Diagnose:
brctl diagnose

Check iCloud Status:
brctl status

Full list of commands

brctl is the command line tool for iCloud Drive. Here is a full list of commands:

╭── 👤 wesley 📂 ~/d/w/wesleydegroot.nl/blog/
╰─> brctl     
Usage: brctl <command> [command-options and arguments]

    -h,--help            show this help

COMMANDS

diagnose [options] [--doc|-d <document-path>] [<diagnosis-output-path>]
    diagnose and collect logs

    -M,--collect-mobile-documents[=<container>]  (default: all containers)
    -s,--sysdiagnose     Do not collect what's already part of sysdiagnose
    -t,--uitest          Collect logs for UI tests
    -n,--name=<name>     Change the device name
    -f,--full            Do a full diagnose, including server checks
    -d,--doc=<document-path>
                         Collect additional information about the document at that path.
                         Helps when investigating an issue impacting a specific document.
    -e,--no-reveal       Do not reveal diagnose in the Finder when done
    [<diagnosis-output-path>]
                         Specifies the output path of the diagnosis; -n becomes useless.

log [options] [<command>]

    -a,--all                         Show all system logs
    -p,--predicate                   Additional predicate (see `log help predicates`)
    -x,--process <name>              Filter events from the specified process
    -d,--path=<logs-dir>             Use <logs-dir> instead of default
    --last num [m|h|d]               Limits the captured events to the period starting at the given interval ago from the current time
    -S,--start="YYYY-MM-DD HH:MM:SS" Start log dump from a specified date
    -E,--end="YYYY-MM-DD HH:MM:SS"   Stop log dump after a specified date
    -b                               Show CloudDocs logs
    -f                               Show FileProvider related logs
    -F                               Show FruitBasket related logs
    -N                               Show network related logs (should be used in conjonction with another flag)
    -g                               Show Genstore related logs
    -i                               Show SQL and CloudDocs logs
    -o                               Show local storage logs
    -D                               Show logs from the Denator subsystem
    -z,--local-timezone              Display timestamps within local timezone
    --dark-mode                      Adapt color scheme to dark mode terminal
    -q,--quick                       Print logs without heavy pre-processing

dump [options] [<container>]
    dump the CloudDocs database

    -o,--output=<file-path>
                         redirect output to <file-path>
    -d,--database-path=<db-path>
                         Use the database at <db-path>
    -e,--enterprise
                         Use the Data Separated database
    -i,--itemless
                         Don't dump items from the db
    -u,--upgrade
                         Upgrade the db if necessary before dumping

    [<container>]        the container to be dumped

status [<containers>]
    Prints items which haven't been completely synced up / applied to disk

    [<container>]        the container to be dumped

accounts [options]
    Displays iCloudDrive eligible accounts and their logged in/out status and directory name
    -w,--wait            wait for logged in accounts to load

quota
    Displays the available quota in the account

monitor [options] [<container> ...]
    monitor activity
    -g                   dump global activity of the iCloud Drive
    -i                   dump changes incrementally
    -t                   amount of time in seconds to run the query, the query will stop after the specified time
    -S,--scope=<scope>
                         restrict the NSMetadataQuery scope to docs, data, external or a combination

    [<container> ...]    list of containers to monitor, ignored when -g is used

Help

Something isn't working!

Finder freezes

Sometimes this can happen, especially when you have a lot of files in your iCloud Drive. You can try to find the file causing Finder to freeze by using the following command brctl monitor com.apple.CloudDocs|grep % , this will show you the progress of the files being downloaded. If you see a file that is stuck for a long time, you can try to download it manually by using the following command brctl download filename. If that doesn't work, you can try to remove the local download of the file by using the following command brctl evict filename. This will remove the local download of the file and try to download it again. If that doesn't work, you can try to diagnose the issue by using the following command brctl diagnose. This will collect logs and diagnose the issue. If you still can't find the issue, you can try to contact Apple Support for further assistance.

I unzipped a masively big zip and now the contents of the folder are not shown anymore (e.g. on the Desktop)

Go to https://www.icloud.com/iclouddrive and delete the files.

Tips

Do not use a lot of non-standard characters in your file names. This can cause issues with iCloud Drive.
Do not end your file names with a space. This can cause issues with iCloud Drive.
Do not save development folders like node_modules or .git in your iCloud Drive. This can take up a lot of space and cause issues with iCloud Drive.
Do not use iCloud Drive as a backup solution. It's not designed for that and you can lose your files if you're not careful.

Conclusion

i love iCloud Drive and it's features. It's a great way to keep all your files in sync and available on all your devices.
Unfortunately, it's not always working as expected. But with the above commands you can diagnose and fix most of the issues.
I hope this article helps you with your iCloud Drive issues. If you have any questions, feel free to ask them in the comments below.

TipKit • 3 minutes reading time.
A Guide to UI Testing in Swift • 15 minutes reading time.
Inspect: A Powerful Tool for SwiftUI Developers • 3 minutes reading time.

Share Mastodon Twitter LinkedIn Facebook