Documentation

iCloud from a terminal, script, or agent.

Start with the quickstart or jump directly to the thing you want to do. The guides focus on commands, examples, and user-visible behavior rather than the machinery underneath the CLI.

Mail is the comprehensive service today. The project is designed to grow into a broader iCloud CLI as additional services become implemented and reliable.

Start

Understand the project, install the CLI, connect an account, and get useful Mail workflows running quickly.

What is icloud?

Understand the project in two minutes: one CLI for iCloud, with a comprehensive Mail experience available today.

Installation

Install with npm, update later with the same command, or build from source.

Quickstart

The shortest useful path through account setup, sync, reading, search, and safe sending.

Accounts and credentials

Configure accounts safely with the system keyring, stdin, environment variables, or protected files.

The iCloud ecosystem

Mail is comprehensive today; the project is designed to grow into a broader iCloud CLI.

Mail

Small task guides for reading, searching, composing, organizing, importing, exporting, securing, and recovering mail.

Mail

Start here when you know you want to work with Mail but are not sure which command or guide covers the task.

Sync mail

Sync current mail, watch in the foreground, backfill history, inspect status, and repair sync state.

Read mail

List messages, inspect concise previews, read full text or HTML, and export exact message files.

Search mail

Search locally by default, add useful filters, and opt into remote search only when you need a fresh provider check.

Conversations and threads

Work with `thr_…` conversation IDs without needing to understand how the grouping is built.

Attachments

Inspect attachment metadata first, then export exact files by stable `att_…` ID.

Send, reply, and forward

Everyday outbound Mail: preview first, send deliberately, and avoid accidental duplicate sends.

Drafts

Compose incrementally with stable `drf_…` draft IDs instead of sending immediately.

Sender identities

Configure the addresses that `--from` can use and choose the default sender for an account.

Signatures

Configure signatures once, then let normal compose commands apply them automatically.

Folders

Manage the mailbox tree without needing to think about provider protocol details.

Organize mail

Familiar mailbox actions with dry-run previews for location-changing operations.

Reviewed bulk actions

Turn a search or list of IDs into a short-lived reviewed selection, then apply exactly that selection.

Empty Trash, Junk, or a folder

Preview a page, apply exactly that page, then repeat if more mail remains.

Import and export mail

Move mail in and out of the CLI using interoperable message and mailbox formats.

Mailing lists and sender preferences

Keep inbox triage useful without turning local preferences into hidden provider-side actions.

S/MIME

Optional end-to-end Mail protection for users who already work with S/MIME certificates and keys.

Outbox and send recovery

When a send goes wrong, inspect the recorded attempt before deciding whether another transmission is safe.

Agents & automation

Conventions and copyable patterns for using icloud predictably from an agent, script, or long-running process.

Agent guide

The conventions an agent should follow to use the CLI accurately, safely, and with minimal output.

Output and automation

Choose the smallest useful output, opt into structured contracts, and handle failures by stable class instead of parsing prose.

Automation recipes

Small end-to-end examples built from the CLI's normal commands and safety controls.

Reference

Current feature coverage, diagnostics, local data, troubleshooting, release notes, and exhaustive command syntax.

Supported features

Use this page for orientation and `icloud capabilities` for the exact installed-build contract.

Account checks and doctor

Use `account test` for a live Mail check and `doctor` for readable diagnostics.

Local data and backups

The few local-storage details users actually need for portability, privacy, backup, and recovery.

Troubleshooting

Start with the command that failed, then use these short checks instead of inspecting implementation details.

Command reference

Exhaustive syntax generated from the same Cobra tree as the installed icloud executable.

Changelog

What changed for people and agents using the CLI.