macOS utility

iCloud Drive sync commands

A quick reference for checking, forcing, and debugging iCloud Drive sync from the Terminal on macOS.

Before you start

These commands are safe for everyday troubleshooting, but they do interact with a live system process. Close important work first, and always keep a local backup of files you cannot afford to recreate.

Check current sync status

Shows a live snapshot of iCloud Drive sync - which files are queued, uploading, downloading, or stuck.

brctl status

~ brctl status
    0 pending downloads
    2 pending uploads
    0.02 MB uploaded

When to use it: Use this first when a file has not appeared or synced. It is the quickest way to see if anything is actually happening.

Run a deeper diagnostic

Collects a detailed report about iCloud Drive state, including logs, account info, and file-system health.

brctl diagnose

~ brctl diagnose
    Report written to: /tmp/CloudDocs...diagnose.zip

When to use it: Use this when status looks normal but files are still not syncing, or Apple Support asks for logs.

Watch sync in real time

Streams iCloud Drive events as they happen - uploads, downloads, conflicts, and errors.

brctl monitor

~ brctl monitor
    [upload] Document.pages
    [download] Notes.pdf

When to use it: Use this when you want to observe sync behavior while moving, saving, or editing files.

Force the sync daemon to restart

Terminates the bird process. macOS automatically relaunches it, which often clears a stuck sync session.

killall bird

~ killall bird
    (no output if successful; bird relaunches automatically)

When to use it: Use this as a safe first reset when iCloud Drive seems frozen. It does not delete any data.

Note: You may see a brief 'iCloud Drive disconnected' moment while bird restarts.

Inspect live bird logs

Streams low-level log messages from the bird process so you can spot errors, retries, or account issues.

log stream --predicate 'processImagePath contains "bird"'

~ log stream --predicate 'processImagePath contains "bird"'
    2026-06-26 10:00:12.123 ... [bird] sync start

When to use it: Use this when you need more detail than brctl provides, especially for debugging repeated failures.

Interpreting the results

Terminal output can look cryptic at first. Here is how to read the common signals each command produces.

brctl statusLook for the Local Item and Server Item counts. If they do not match, sync is still in progress. A non-zero number of pending items means files are waiting to upload or download.
Diagnosing sync statesA stuck sync often shows the same file name repeating in logs, or a progress value that has not moved for a long time. If a file keeps appearing with no bytes transferred, the process is likely blocked on that item.
Active uploads and downloadsIn brctl monitor, active transfers are marked with UP or DOWN next to a file path. If you see these moving, iCloud Drive is actively working. No new entries means nothing is happening right now.
Log streambird logs with error codes like 403 or messages such as quota exceeded usually point to permission or storage issues, not a local sync bug. Check your iCloud storage and account status before restarting the daemon.

What is bird?

bird is the background process macOS uses to keep iCloud Drive in sync. It watches your local iCloud Drive folder, uploads changes to Apples servers, and downloads updates from other devices. When bird gets stuck, files stop moving. Restarting it with killall bird gives it a fresh start without touching your files.