Installation

Prerequisites

Choose one installation path:

• npm installation: Node.js 18 or newer;
• source build: Go 1.26 or newer;
• documentation development: Bun 1 or newer in addition to the source-build tools.

No credential is required to install the binary, inspect capabilities, or create an empty state. Account setup uses an app-specific password or an environment/file reference; it never requires the primary password for your Apple Account and does not contact iCloud yet.

Install through npm

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

The npm executable is named icloud. The package installer selects a release asset with this shape:

icloud_<operating-system>_<architecture>[.exe]

On macOS and Linux, the installed native binary lives beside the JavaScript shim as icloud-bin. On Windows it is icloud.exe.

If downloading the release asset fails, the installer checks for Go and the packaged cmd/icloud source, then performs a local fallback build. A failure in both paths stops installation rather than leaving a non-working command.

Build from source

From the repository root:

make check
make build
./dist/icloud version

Install that build into ~/.local/bin:

make install-local
icloud --help

The Makefile injects the package version into the same build-time version field used by release binaries.

Verify identity and capabilities

icloud version
icloud capabilities

Both commands use one compact line by default. capabilities includes the installed local-state schema version. Use --json only when a consumer needs structured fields.

Verify local state

Choose an isolated directory for a first read:

ICLOUD_HOME=./icloud-state icloud account list

A new installation prints accounts count=0 and creates the state root. Omitting both --home and ICLOUD_HOME uses the platform data directory described in Local state and account inspection.

Verify account setup

For a safe first profile, read Account setup and credentials, then choose native keyring, environment, or file-backed setup. A successful add returns pending_validation; it is not a live authentication test.

Repair an npm installation

When the JavaScript shim exists but its native binary does not:

npm rebuild --global @amxv/icloud-cli

If that still fails, check that the installed package version has a matching GitHub release asset or that Go is available for the fallback build.

Uninstall

For a global npm installation:

npm uninstall --global @amxv/icloud-cli

Package removal does not delete local application state, native keyring entries, environment variables, or external credential files. Remove accounts through icloud account remove <selector> --yes before uninstalling when you want keyring cleanup. Confirm the selected root and preserve anything needed before deleting it manually. version, capabilities, completion, man, and help do not create state.