How to Get Version History for an App Using IPATool

IPATool's list-versions command queries the App Store to retrieve every historical version ID available for a specific iOS application.

To get version history for an app using IPATool, you authenticate with your Apple ID and execute the command against either a numeric App ID or a bundle identifier. The tool implements a multi-step resolution flow that handles automatic re-authentication, App Store lookup, and XML parsing to return a complete list of external version identifiers.

Understanding the list-versions Architecture

The implementation spans two primary source files in the majd/ipatool repository. The command logic resides in cmd/list_versions.go, while the low-level App Store communication lives in pkg/appstore/appstore_list_versions.go.

Account Acquisition and Authentication

When you invoke ipatool list-versions, the ListVersionsCmd struct first validates your session by calling AppStore.AccountInfo. If your stored password token has expired, the system automatically re-authenticates via AppStore.Login before proceeding with the version query. This ensures the subsequent request to Apple's servers includes valid credentials without manual intervention.

App Resolution from Bundle Identifiers

You can specify the target app using either --app-id (the numerical App Store ID) or --bundle-identifier (the reverse-domain string). If you provide only a bundle identifier, the command executes AppStore.Lookup to resolve the corresponding numerical app-id before requesting version data.

The Private App Store Request

Once authentication and resolution are complete, appstore.ListVersions constructs a POST request mimicking the official iOS App Store client. The listVersionsRequest payload includes three critical components: the device’s MAC address (used as a GUID), your account’s DS-ID, and the target application’s ID. This request targets Apple’s internal endpoints to access historical version data not exposed through public APIs.

Parsing the XML Response

The App Store returns an XML document that pkg/appstore/appstore_list_versions.go parses into the ListVersionsOutput struct. The parser specifically extracts two fields:

• softwareVersionExternalIdentifiers – An array containing every historic version ID available for the application
• softwareVersionExternalIdentifier – The single newest version ID

The CLI then logs the array under the key externalVersionIdentifiers and renders the output in your selected format.

Retrieving Version History via CLI

Before running version queries, ensure you have an active authenticated session:

ipatool auth login

Query by App ID

Use the numerical App Store ID to retrieve version history directly:

ipatool list-versions --app-id 123456789

Query by Bundle Identifier

If you know the bundle identifier but not the App ID, IPATool resolves it automatically:

ipatool list-versions --bundle-identifier com.example.myapp

Machine-Readable JSON Output

For scripting and automation, specify the JSON format to receive structured data:

ipatool list-versions -b com.example.myapp --format json

The JSON response contains the full history array and the latest version identifier:

{
  "externalVersionIdentifiers": [
    "20000123",
    "20000234",
    "20000345"
  ],
  "latestExternalVersionID": "20000345"
}

Programmatic Access with Go

You can integrate version history retrieval directly into Go applications using the pkg/appstore package. The AppStore interface defined in pkg/appstore/appstore.go exposes the ListVersions method for programmatic use:

import (
    "github.com/majd/ipatool/v2/pkg/appstore"
)

func getHistory(appID int64, acc appstore.Account) ([]string, error) {
    out, err := appstoreClient.ListVersions(appstore.ListVersionsInput{
        Account: acc,
        App:     appstore.App{ID: appID},
    })
    if err != nil {
        return nil, err
    }
    return out.ExternalVersionIdentifiers, nil
}

This approach allows you to handle the ListVersionsInput struct directly, manage the Account object programmatically, and process the ExternalVersionIdentifiers slice without shelling out to the CLI.

Summary

• list-versions is the primary command for retrieving historical App Store versions according to the majd/ipatool source code.
• The command automatically handles expired authentication by calling AppStore.Login when AccountInfo detects invalid tokens.
• You can target apps by either --app-id or --bundle-identifier, with the latter automatically resolving to the former via AppStore.Lookup.
• pkg/appstore/appstore_list_versions.go sends a POST request containing your DS-ID and a device GUID, then parses the XML response to extract softwareVersionExternalIdentifiers.
• Output formats include human-readable text and machine-readable json, both exposing the externalVersionIdentifiers array.

Frequently Asked Questions

Can I retrieve version history without knowing the App ID?

Yes. If you only know the bundle identifier (e.g., com.company.appname), use the --bundle-identifier flag. The ListVersionsCmd implementation in cmd/list_versions.go automatically calls AppStore.Lookup to resolve the numerical App ID before fetching the version history.

What authentication is required to use list-versions?

You must have a valid Apple ID session established via ipatool auth login. The command checks AppStore.AccountInfo before executing, and if your password token has expired, it automatically triggers AppStore.Login to refresh credentials without requiring you to re-run the login command manually.

What information does the version history response contain?

The response contains the externalVersionIdentifiers array, which lists every historical version ID available for the app on the App Store, and latestExternalVersionID, which identifies the current release. These values map to the softwareVersionExternalIdentifiers and softwareVersionExternalIdentifier fields in Apple's internal XML response, as parsed in pkg/appstore/appstore_list_versions.go.

Can I use IPATool's version history feature in my own Go application?

Yes. Import github.com/majd/ipatool/v2/pkg/appstore and call the ListVersions method with a ListVersionsInput struct containing your Account and target App details. The method returns a ListVersionsOutput struct containing the ExternalVersionIdentifiers slice for programmatic processing.

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