How to Search for tvOS Apps Using IPATool

Pass the --platform appletv flag to the search command to query the App Store specifically for Apple TV applications, which internally maps to the tvSoftware entity.

IPATool is a command-line utility that enables you to search, download, and manage iOS apps from Apple's ecosystem. When you need to locate applications specifically for Apple TV, you can filter searches to target tvOS exclusively using platform-specific parameters. This guide explains how to search for tvOS apps using IPATool by leveraging the --platform flag implemented in the majd/ipatool repository.

Understanding the --platform Flag

The search sub-command accepts a --platform argument that determines which App Store entity to query. According to the source code in cmd/search.go (lines 49-51), the CLI parses this flag and passes the value to the underlying App Store client. For tvOS searches, you must specify appletv as the platform value to ensure the query targets the correct device category.

Supported Platform Identifiers

While appletv is the canonical identifier, the appstore.ParsePlatform function in pkg/appstore/platform.go (lines 25-27) recognizes multiple aliases for convenience:

• appletv
• apple-tv
• tvos

All three strings resolve to the PlatformAppleTV constant internally, ensuring consistent behavior regardless of which alias you provide.

Executing a tvOS Search from the Command Line

To perform a tvOS-specific search, append --platform appletv to your query. The tool defaults to returning 5 results, but you can specify a custom limit up to the API maximum for tvOS entities.

# Basic tvOS search

ipatool search "Netflix" --platform appletv

# Increase result count (up to 12 for tvOS)

ipatool search "Hulu" --platform appletv --limit 10

# JSON output suitable for scripts

ipatool search "Disney+" --platform appletv --non-interactive --format json

Programmatic tvOS Search in Go

If integrating IPATool into your own Go application, invoke the search logic directly using the appstore package. You must first resolve account authentication, parse the platform string, then execute the search with the appropriate SearchInput parameters:

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

func searchTVOS(term string) ([]appstore.App, error) {
    // Parse platform string to PlatformAppleTV constant
    platform, err := appstore.ParsePlatform("appletv")
    if err != nil {
        return nil, err
    }
    
    // Requires existing Apple ID authentication
    accountInfo, _ := dependencies.AppStore.AccountInfo()
    
    // Execute search with tvOS platform specified
    out, err := dependencies.AppStore.Search(appstore.SearchInput{
        Account:  accountInfo.Account,
        Term:     term,
        Limit:    5,
        Platform: platform,
    })
    if err != nil {
        return nil, err
    }
    return out.Results, nil
}

The SearchInput struct requires the Platform field to be populated with the value returned by appstore.ParsePlatform, which returns the PlatformAppleTV type for tvOS requests.

How the Search Query is Built

When you specify a tvOS platform, IPATool constructs the iTunes Search API URL using the entity type tvSoftware. In pkg/appstore/appstore_search.go (lines 35-41), the implementation accesses PlatformAppleTV.searchEntity to determine the correct entity parameter for the HTTP request.

This mapping ensures that query results include only applications compatible with Apple TV, automatically filtering out iPhone, iPad, and macOS software that would otherwise appear in a generic search.

Summary

• Use --platform appletv to restrict searches exclusively to tvOS apps via the CLI
• The platform string is normalized by appstore.ParsePlatform in pkg/appstore/platform.go
• Accepted values include appletv, apple-tv, and tvos, all resolving to the same internal constant
• The search utilizes the tvSoftware entity accessed through PlatformAppleTV.searchEntity
• Both the command-line interface and the Go API support programmatic tvOS filtering using the SearchInput struct

Frequently Asked Questions

What platform value should I use for Apple TV apps?

Use --platform appletv when searching from the command line. The parser in pkg/appstore/platform.go also accepts apple-tv or tvos as valid alternatives, and all three aliases map to the same internal PlatformAppleTV constant.

Why does my tvOS search return fewer results than iOS searches?

The App Store's iTunes Search API imposes different result limits for tvSoftware entities compared to iOS software. IPATool respects these API constraints, typically returning a maximum of 12 results for tvOS searches versus higher limits available for mobile platforms.

Can I search for tvOS apps without authenticating?

No, you must authenticate with a valid Apple ID before executing searches. The SearchInput struct requires an Account object obtained through AppStore.AccountInfo(), as the underlying iTunes Search API requires authentication headers even for read-only queries.

Does IPATool support downloading tvOS apps after searching?

Yes, once you identify a tvOS app through search, you can use the download command with the same --platform appletv flag to acquire the IPA file, provided the app is associated with your authenticated Apple ID and available in your purchase history.

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