How to Login with IPATool Auth: Complete Command Guide

Run ipatool auth login --email you@example.com to authenticate with the Apple App Store using your Apple ID credentials, with optional support for two-factor authentication via the --auth-code flag.

The majd/ipatool repository provides a command-line interface for interacting with the Apple App Store. To download iOS apps or access purchase history, you must first complete an IPATool auth login to establish a secure session with Apple's servers.

Understanding the IPATool Auth Command Structure

The auth command group defined in cmd/auth.go registers three essential subcommands that manage authentication state. These commands handle the complete lifecycle of your Apple ID session, from initial authentication to credential revocation.

Available Auth Subcommands

• login – Initiates a new App Store session and stores credentials securely in the system keychain.
• info – Displays currently stored account details and authentication status without transmitting credentials.
• revoke – Removes stored credentials from the keychain via pkg/keychain/keychain_set.go, effectively logging you out.

How the IPATool Auth Login Flow Works

When you execute the login command, IPATool orchestrates a multi-step authentication process involving Apple's SAP (Secure Access Protocol) signing mechanism.

Core Authentication Implementation

In pkg/appstore/appstore_login.go, the AppStore.Login method constructs a SAP-signed authentication request (loginRequest) containing your Apple ID credentials. This request is transmitted via the HTTP client defined in pkg/http/client.go, which handles network retries for transient errors.

Two-Factor Authentication Handling

If your Apple ID has 2FA enabled, the server responds with a challenge after the initial credential verification. IPATool detects this requirement and either prompts interactively for the verification code or reads the --auth-code flag in non-interactive mode. Upon successful validation, the response is parsed into an Account struct and persisted to the system keychain via pkg/keychain/keychain_set.go.

Interactive vs Non-Interactive Login Modes

IPATool supports two distinct operational modes for authentication, controlled by the --non-interactive flag.

Interactive Mode (Default)

In the default interactive mode, IPATool reads sensitive input directly from the terminal. The command prompts for your password and, if required, requests the 2FA verification code dynamically. This mode is ideal for manual command-line usage where security and convenience are prioritized.

Non-Interactive Mode

For automation scripts and CI/CD pipelines, append the --non-interactive flag. This mode requires all inputs to be provided via command flags: --email, --password, and optionally --auth-code. Missing required flags in non-interactive mode results in immediate termination with an error code rather than a prompt.

Practical IPATool Auth Login Examples

The following commands demonstrate common authentication scenarios using the ipatool auth interface.

Basic Interactive Login

ipatool auth login --email you@example.com

The tool securely reads your password from the terminal. If 2FA is enabled on your Apple ID, IPATool prompts for the verification code after the initial authentication attempt.

Non-Interactive Login for Scripts

ipatool auth login \
    --email you@example.com \
    --password MySecretPass \
    --auth-code 123456 \
    --non-interactive

All credentials pass via flags, enabling unattended execution without terminal interaction.

Verify Active Session

ipatool auth info

This displays the stored account name and email address, confirming successful authentication.

Revoke Credentials

ipatool auth revoke

This removes the Apple ID credentials from your system keychain, effectively logging you out.

Key Source Files and Implementation Details

Understanding the codebase structure helps diagnose authentication issues and customize behavior.

cmd/auth.go

Defines the Cobra command structure for auth login, auth info, and auth revoke. Handles flag parsing for --email, --password, --auth-code, and --non-interactive.

pkg/appstore/appstore_login.go

Contains the core login logic including SAP request signing, XML payload construction, response parsing, and keychain integration.

pkg/http/request.go and pkg/http/client.go

Provide the HTTP abstraction layer handling request construction, SAP signature headers, retry logic for network failures, and response processing.

pkg/keychain/keychain_set.go

Implements secure credential storage using platform-specific keychain APIs across Windows, Linux, and macOS.

Summary

• Execute ipatool auth login to initiate Apple App Store authentication using your Apple ID.
• Provide credentials interactively (default) or via flags using --non-interactive for automation.
• The login flow uses SAP-signed requests in pkg/appstore/appstore_login.go and stores tokens securely in the system keychain.
• Use ipatool auth info to verify active sessions and ipatool auth revoke to clear stored credentials.
• All network operations include retry logic via pkg/http/client.go for resilient authentication.

Frequently Asked Questions

How do I log in to IPATool when I have two-factor authentication enabled?

When 2FA is active on your Apple ID, run ipatool auth login --email you@example.com and enter your password when prompted. IPATool automatically detects the 2FA requirement and asks for your verification code. For non-interactive scripts, include both --password and --auth-code flags along with --non-interactive.

Where does IPATool store my Apple ID password?

IPATool stores authentication tokens and account data in your operating system's secure keychain, implemented in pkg/keychain/keychain_set.go. The tool never saves raw passwords to disk; instead, it persists the password token received from Apple's servers after successful authentication.

Can I use IPATool auth login in a CI/CD pipeline?

Yes, use the --non-interactive flag to prevent terminal prompts. Supply all required credentials via flags: --email, --password, and --auth-code if 2FA is enabled. Ensure your pipeline securely injects these values as environment variables or secrets rather than hardcoding them in scripts.

What happens if the Apple App Store login fails temporarily?

The HTTP client in pkg/http/client.go implements automatic retry logic for transient network errors. If the initial SAP-signed authentication request fails due to connectivity issues, IPATool retries the operation before returning an error to the user.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}