ihme-cli AGENTS.md

AGENTS.md

Coding agent instructions for ihme-cli — iCloud Hide My Email from the terminal.

What this tool does

ihme manages iCloud Hide My Email addresses: create, list, search, edit, deactivate, reactivate, delete, export. It authenticates via Apple's SRP-6a protocol with 2FA support and persists session tokens locally.

Prerequisites

Binary must be installed and authenticated before use:

# Install (macOS ARM)
curl -sL https://github.com/lroolle/ihme-cli/releases/latest/download/ihme_macOS_arm64.tar.gz | tar xz && sudo mv ihme /usr/local/bin/

# Install (macOS Intel)
curl -sL https://github.com/lroolle/ihme-cli/releases/latest/download/ihme_macOS_x86_64.tar.gz | tar xz && sudo mv ihme /usr/local/bin/

# Install (Linux x86_64)
curl -sL https://github.com/lroolle/ihme-cli/releases/latest/download/ihme_linux_x86_64.tar.gz | tar xz && sudo mv ihme /usr/local/bin/

# Install (Go)
go install github.com/lroolle/ihme-cli/cmd/ihme@latest

Authentication is interactive (requires human input for Apple ID + 2FA):

ihme auth login

Check session before running commands:

ihme auth status --json
# {"loggedIn":true,"appleId":"...","expired":false,...}

If exit code is 2, the user must run ihme auth login interactively.

Commands

All commands support --json for structured output and --jq <expr> for filtering.

List and search

ihme list --json                          # all addresses
ihme list --search netflix --json         # search label, address, or note
ihme list --active --json                 # only active
ihme list --inactive --json               # only inactive
ihme list --tag dev --json                # filter by tag
ihme list --sort label --json             # sort by: label, date, label:desc, date:asc
ihme list --json --jq '.addresses[0:5]'   # first 5
ihme list --json --jq '.count'            # total count

Create (two-step flow)

# Step 1: generate candidates (does NOT reserve)
ihme new github.com --json
# {"candidates":["[email protected]","[email protected]","[email protected]"],"hint":"ihme new github.com --address <address> --json","label":"github.com"}

# Step 2: reserve a specific candidate
ihme new github.com --address [email protected] --json
# {anonymousId, label, hme, isActive, ...}

# One-shot (take first candidate, no choice)
ihme new github.com --yes --json

# With tags and note
ihme new github.com --tag dev --note "main account" --json