Download iCloud Drive Files Locally with brctl
Trigger the hidden iCloud sync daemon to fetch file contents on demand.
Run `brctl download /path/inside/iCloud/Drive` to make the file download fully to disk.
01Command
Command
$ brctl download "$HOME/Library/Mobile Documents/com~apple~CloudDocs/报告.pdf"02What it does
iCloud Drive shows placeholder files that only download when opened, which breaks scripts that read paths directly. `brctl` talks to `bird`, the iCloud Drive daemon, and `download` forces the real contents onto disk without opening the app. Check progress with `brctl monitor` or the status column of `brctl dump`.
03Risk
!Warning: Only paths under `~/Library/Mobile Documents` belong to iCloud Drive. Downloading many files consumes data and disk space; there is no undo needed — the command simply fetches data.
04Undo
✓No undo needed — this command does not change persistent state.
05Sources
- brctl(8) – bird control utilityEvidence: Manual page documenting brctl download/monitor/dump for the iCloud document store
Last verified: 2026-09-18 · Category: Files & Folders
06Related solutions
Find files larger than 500 MB on Mac
List the biggest files in your home folder that are eating disk space.
Show file extensions for all files on Mac
Make Finder display .pdf, .docx, .png and every other extension at all times.
List Local Time Machine Snapshots with tmutil
See every local APFS Time Machine snapshot on your startup disk and delete ones you no longer need.