# How to Search for tvOS Apps Using IPATool

> Easily search for tvOS apps using IPATool. Learn to use the --platform appletv flag with the search command to find Apple TV applications quickly and efficiently.

- Repository: [Majd/ipatool](https://github.com/majd/ipatool)
- Tags: how-to-guide
- Published: 2026-09-01

---

**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`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/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.

```bash

# 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:

```go
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`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/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`](https://github.com/majd/ipatool/blob/main/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.