Quickstart

This guide covers the everyday path. Advanced features such as historical backfill, imports, S/MIME, bulk changes, and recovery each have their own guide.

1. Install the CLI

npm install --global @amxv/icloud-cli@latest
icloud version

2. Create an Apple app-specific password

Use an app-specific password for your Apple Account. Do not give the CLI your normal Apple Account password.

When you have one, add the account interactively:

icloud account add --name Personal --email you@icloud.com

The interactive path stores the password in your system keyring when available.

For a script or agent, pass it through stdin instead of placing it in the command line:

printf '%s\n' "$ICLOUD_APP_PASSWORD" | \
  icloud account add \
    --name Personal \
    --email you@icloud.com \
    --password-stdin

See Accounts and credentials for environment variables, credential files, multiple accounts, and rotation.

3. Check the account

icloud account test Personal

This validates that the account can connect to iCloud Mail. It does not send a message.

If it fails, use Account checks and doctor.

4. Discover your folders

icloud mail folders refresh

Then inspect the saved list:

icloud mail folders list

Inbox and Sent are the normal starting folders. You can opt custom folders into routine synchronization later.

5. Sync recent mail

icloud mail sync

To pull additional recent pages until you are current:

icloud mail sync --folder inbox --until-current

Normal sync is designed for current mail. If you later want older history, use Sync mail and its backfill workflow.

6. Read your inbox

icloud mail messages list

Open a message using the returned msg_… ID:

icloud mail message show msg_…
icloud mail message show msg_… --full

The first command gives you a concise view. --full asks for the complete readable body.

For HTML or exact message data:

icloud mail message show msg_… --format html
icloud mail message raw msg_… > message.eml

See Read mail for the rest of the content options.

7. Search

Search your synchronized mail locally:

icloud mail search invoice
icloud mail search --from billing@example.com --unread

If you need to check iCloud directly for something that is not in your local copy yet:

icloud mail search invoice --remote

See Search mail for filters, thread results, and caching selected remote hits.

8. Read conversations

icloud mail threads list
icloud mail threads show thr_…

A message ID works too:

icloud mail threads show msg_…

See Conversations and threads.

9. Save an attachment

icloud mail attachments list msg_…
icloud mail attachments save att_… --output invoice.pdf

Or save all attachments from a message:

icloud mail attachments save-all msg_… --dir ./attachments

See Attachments.

10. Reply safely

Preview a reply first:

icloud mail reply msg_… --body-file reply.txt --dry-run

Then send it:

icloud mail reply msg_… \
  --body-file reply.txt \
  --idempotency-key reply-2026-08-11-01 \
  --yes

--idempotency-key is especially useful in automation because repeating the same request with the same key will not create an accidental duplicate send.

11. Send a new message

icloud mail send \
  --to teammate@example.com \
  --subject 'Project update' \
  --body-file update.txt \
  --attach report.pdf \
  --dry-run

After review:

icloud mail send \
  --to teammate@example.com \
  --subject 'Project update' \
  --body-file update.txt \
  --attach report.pdf \
  --idempotency-key project-update-01 \
  --yes

See Send, reply, and forward.

12. Keep mail fresh while you work

For a foreground watcher:

icloud mail watch

Press Ctrl-C to stop it. For an agent or another program that wants events:

icloud mail watch --jsonl

Multiple accounts

Use --account when you have more than one:

icloud --account Work mail sync
icloud --account Work mail messages list

You can also set a default:

icloud account default Work

A useful mental model

For everyday use:

folders refresh → sync → list/search → inspect → act

You do not need to understand how the CLI talks to iCloud to use it. The task guides explain the user-facing behavior and safety rules; the command reference contains every flag when you need something exact.