# How to Search for Apps in the App Store with IPATool: Command-Line Guide > Learn how to search for apps in the App Store using IPATool's command-line interface. Query the catalog directly from your terminal with easy-to-use flags for region and output format. - Repository: [Majd/ipatool](https://github.com/majd/ipatool) - Tags: how-to-guide - Published: 2026-09-04 --- **Run `ipatool search ""` to query Apple's App Store catalog directly from your terminal, with optional flags to specify the storefront region (`--country`) and output format (`--output`).** IPATool is an open-source command-line utility that enables you to search for apps in the App Store with IPATool without opening iTunes or the App Store GUI. Whether you need to find bundle identifiers for automation scripts or verify app versions across different regions, the `search` command provides direct access to Apple's catalog through the implementation in [`cmd/search.go`](https://github.com/majd/ipatool/blob/main/cmd/search.go) and [`pkg/appstore/appstore_search.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_search.go). ## How the IPATool Search Command Works The search functionality is split between the user-facing CLI layer and the core App Store integration. In [`cmd/search.go`](https://github.com/majd/ipatool/blob/main/cmd/search.go), the command definition uses the **Cobra** framework to parse arguments and flags, while [`pkg/appstore/appstore_search.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_search.go) contains the business logic that authenticates with Apple and parses the search response. This architecture allows other commands—such as `list-versions`—to reuse the same search primitives once an app is identified. ## The Search Execution Pipeline When you invoke `ipatool search`, the tool executes a four-stage pipeline that handles authentication, request construction, data parsing, and formatted output. ### Authentication Handling Before querying the App Store, IPATool validates the user's session state. The tool retrieves authentication tokens stored in your system keychain, managed by the logic in [`pkg/appstore/appstore_login.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_login.go). If no valid session exists, you must first execute `ipatool auth login` with your Apple ID credentials. This step is mandatory because Apple's search endpoints require authenticated access even for free apps. ### Request Construction The search query is dispatched through the internal HTTP client defined in [`pkg/http/client.go`](https://github.com/majd/ipatool/blob/main/pkg/http/client.go). According to the source code in [`pkg/appstore/appstore_search.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_search.go), the request targets Apple's public search API, passing the query string, storefront country code, and pagination parameters. The endpoint URLs and default storefront values are defined in [`pkg/appstore/constants.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/constants.go). ### Response Parsing and Output Apple returns a JSON payload that the tool unmarshals into Go structs including `AppSearchResult` and `AppInfo`. The **printer** package then formats these results based on the `--output` flag value. By default, IPATool renders a human-readable table displaying the app name, bundle identifier, version, price, and description. Alternative formats include `json` and `yaml` for programmatic consumption in shell scripts. ## Practical IPATool Search Examples Execute a basic search for photography applications: ```bash ipatool search "photo editor" ``` Limit results to the United Kingdom storefront using the country code flag: ```bash ipatool search "photo editor" --country=gb ``` Retrieve machine-readable JSON output suitable for scripting: ```bash ipatool search "photo editor" --output=json ``` ## Customizing Search Behavior The `search` command accepts several configuration flags defined in [`cmd/search.go`](https://github.com/majd/ipatool/blob/main/cmd/search.go): **`--country`**: Specifies the two-letter ISO country code for the App Store storefront (e.g., `us`, `gb`, `jp`). This parameter is passed directly to Apple's search endpoint in [`pkg/appstore/appstore_search.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_search.go) to filter results by regional availability. **`--output`**: Controls the presentation format. Valid options are `table` (default), `json`, and `yaml`. This flag determines which serializer the printer invokes when displaying `AppSearchResult` structs extracted from the API response. Because the search implementation is fully encapsulated inside the `appstore` package, the underlying logic can be reused by other commands such as `download` or `list-versions` once an application is identified. ## Summary - **Use `ipatool search ""`** to query the App Store from your terminal using the CLI implementation in [`cmd/search.go`](https://github.com/majd/ipatool/blob/main/cmd/search.go). - **Authentication is required** via `ipatool auth login` before searching, with tokens stored in the system keychain and managed by [`pkg/appstore/appstore_login.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_login.go). - **Filter by storefront** using the `--country` flag to specify regional App Store catalogs and currency. - **Choose output formats** with `--output` (table, json, or yaml) for human reading or automated parsing. - **Core logic resides** in [`pkg/appstore/appstore_search.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_search.go), which uses [`pkg/http/client.go`](https://github.com/majd/ipatool/blob/main/pkg/http/client.go) to communicate with Apple's search API endpoints defined in [`pkg/appstore/constants.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/constants.go). ## Frequently Asked Questions ### Do I need to log in before using the search command? Yes, IPATool requires a valid Apple ID session to search the App Store. Run `ipatool auth login` and enter your credentials when prompted. The authentication token is securely stored in your system keychain and automatically reused by the search logic in [`pkg/appstore/appstore_search.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_search.go) via the session management in [`pkg/appstore/appstore_login.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_login.go). Without authentication, the Apple API returns authorization errors. ### Can I search for apps in different countries with IPATool? Yes, use the `--country` flag followed by a two-letter ISO country code. For example, `ipatool search "maps" --country=jp` queries the Japanese App Store to show region-specific pricing and availability. This parameter is injected into the HTTP request constructed by [`pkg/appstore/appstore_search.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_search.go) and transmitted through the client in [`pkg/http/client.go`](https://github.com/majd/ipatool/blob/main/pkg/http/client.go). ### What information does the IPATool search output include? By default, the command displays a formatted table containing the app name, bundle identifier, current version number, price tier, and a brief description. When you specify `--output=json` or `--output=yaml`, the tool outputs the complete data structure including all fields from the internal `AppSearchResult` and `AppInfo` structs, enabling extraction of metadata like developer name and supported devices for automation workflows. ### How does IPATool handle the App Store search API internally? The search implementation in [`pkg/appstore/appstore_search.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/appstore_search.go) constructs authenticated HTTP GET requests using the client from [`pkg/http/client.go`](https://github.com/majd/ipatool/blob/main/pkg/http/client.go). It appends your query and storefront parameters to Apple's search endpoint URL (defined in [`pkg/appstore/constants.go`](https://github.com/majd/ipatool/blob/main/pkg/appstore/constants.go)), then unmarshals the JSON response into Go structs. Finally, [`cmd/search.go`](https://github.com/majd/ipatool/blob/main/cmd/search.go) invokes the printer package to render the results according to your selected output format.