Accounts and credentials

Add your first account

Use an Apple app-specific password, not your normal Apple Account password.

The interactive command is:

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

When the system keyring is available, this is the simplest setup.

Headless and agent-friendly credential sources

For non-interactive use, choose one explicit source.

Read the password from stdin

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

Reference an environment variable

icloud account add \
  --name Personal \
  --email you@icloud.com \
  --credential-env ICLOUD_APP_PASSWORD

The CLI remembers the reference; the environment variable must exist when a network operation needs the credential.

Reference a protected file

icloud account add \
  --name Personal \
  --email you@icloud.com \
  --credential-file ~/.config/icloud-cli/personal-password

Use filesystem permissions appropriate for a secret.

There is intentionally no plaintext --password ... flag.

Validate the account

After setup:

icloud account test Personal

This checks Mail connectivity without sending a message.

Add multiple accounts

icloud account add --name Personal --email you@icloud.com
icloud account add --name Work --email you@company.example

List them:

icloud account list

Choose a default:

icloud account default Personal

Or select one for a single command:

icloud --account Work mail messages list

Selectors can use the account’s friendly name, email address, or stable acct_… ID.

Rename an account

icloud account rename Personal Home

The friendly name changes; your Mail data stays associated with the same account.

Inspect credential metadata

icloud account credential show Personal

This describes how the credential is sourced without printing the password itself.

Replace a credential

For example, to rotate into a new keyring value:

printf '%s\n' "$NEW_ICLOUD_APP_PASSWORD" | \
  icloud account credential replace Personal --password-stdin

Then re-check the account:

icloud account test Personal

Remove an account

Review your local data first if you may want to keep it. Then:

icloud account remove Personal --yes

Removing an account is different from uninstalling the CLI. See Local data and backups if you want to preserve or delete synchronized mail deliberately.

Troubleshooting

If a credential works in the Apple website but account test fails, make sure it is an app-specific password and not the primary Apple Account password. For connection diagnostics, continue with Account checks and doctor.