Installing apps

Use a release, a direct IPA URL, or a file on your Mac. The source is saved with the installed app so ipa-hub knows where to check for updates.

The examples default to Global, using an installed copy of ipa-hub. Select npm or bun above a command to run it without a global installation.

GitHub and GitLab releases

ipa-hub install gh:owner/repo
ipa-hub install gh:owner/repo:prerelease
ipa-hub install github:owner/repo:v1.2.3
ipa-hub install gitlab:group/project --release pre-release
ipa-hub install https://github.com/owner/repo/releases/tag/v1.2.3

Without a release, ipa-hub uses the latest stable release. Repository shorthand accepts a :<release> suffix. --release accepts latest, prerelease (or pre-release), or a specific tag. GitLab repository and release URLs work too. For a private instance, use an explicit provider URL:

ipa-hub install github:https://github.company.example/owner/repo
ipa-hub install gitlab:https://git.company.example/group/project:v1.2.3

Pick an IPA

ipa-hub install gh:owner/repo --filter tv
ipa-hub install gh:owner/repo --filter 'advanced*tv'
ipa-hub install gh:utmapp/UTM --filter '^UTM$'
ipa-hub install gh:owner/repo --asset MyApp.ipa

--filter matches text anywhere in an IPA filename, ignoring case. tv and *tv* are equivalent. Use advanced*tv to match advanced followed by tv, with any sequence of characters (including none) between them; for example, App-Advanced-AppleTV-arm64.ipa.

A filter starting with ^ or ending with $ is a case-insensitive regular expression. ^UTM$ selects UTM.ipa; Remote$ selects UTM-Remote.ipa without selecting UTM-Remote-visionOS.ipa. Other filters treat regex punctuation literally, apart from the * wildcard. Quote filters in your shell.

Matching first excludes the .ipa suffix from every filename. Only if that produces no matches does ipa-hub try the full filenames. For example, ^UTM\.ipa$ also selects UTM.ipa. The website, CLI, and App Manager use the same rules. If several assets match, choose one at the prompt. --asset selects an exact filename or URL.

The one-off command builder starts with a repository input, then lets you type a release or browse its history. Choose an IPA to fill a short, unique filter automatically, or edit the filter yourself. Nonmatching files stay available to select. Leave the filter empty to choose an IPA in the CLI, or narrow it to a single match. A release containing only one IPA needs no file-selection flag.

Filter Healing

Projects sometimes rename their IPA files or add new variants. When an update's original filter matches several files, Filter Healing tries the installation's saved filter refinements first. If it still needs help, it compares the installed release's filenames and looks for a more precise filter that identifies the installed variant in that release and one candidate in the new release.

If filenames cannot resolve the ambiguity, ipa-hub downloads the remaining candidates and inspects their app identity, Apple platform, device family, simulator target, and minimum OS version. It selects an IPA only when exactly one candidate passes those checks. An unreadable candidate or uncertain compatibility leaves the choice to you. Signing and installation validation still run normally.

Successful refinements are saved in the app record's filterImprovements list and retained across updates and re-signing. They narrow the original filter's matches; they never select a file outside that set. Your original filter stays unchanged. Update checks may download candidates for this last-resort compatibility check even when prefetch is disabled.

For the UTM release containing UTM.ipa, UTM-HV.ipa, UTM-Remote.ipa, UTM-Remote-visionOS.ipa, UTM-SE.ipa, UTM-SE-visionOS.ipa, and UTM-visionOS.ipa, useful filters include:

IPAFilter
UTM.ipa^UTM$
UTM-HV.ipaHV
UTM-Remote.ipaRemote$
UTM-SE.ipaSE$
UTM-SE-visionOS.ipaSE-visionOS
UTM-visionOS.ipa^UTM-visionOS$

visionOS$ alone matches three variants in this release, so it cannot select the base visionOS app uniquely.

Direct URLs and local files

ipa-hub install https://example.org/releases/App.ipa
ipa-hub install ./App.ipa

Local files are used directly. Direct downloads keep ETag, Last-Modified, or content-length validators when available so update checks can detect changes without downloading the whole file. Without usable validators, a check explains why it cannot reliably compare versions.

Private downloads

ipa-hub install gh:owner/private-repo --access-token "$MY_GITHUB_TOKEN"

The token is retained privately for that installation’s update checks and downloads. It is not returned through the server API. Tokens require HTTPS, are scoped to the source origin, and are removed on cross-origin redirects. GitLab and ordinary HTTPS sources also support --access-token.

Cache and installation

Downloads live under ~/.ipa-hub/downloads. Recently downloaded files are protected for an hour; older files use a ten-file LRU cache. Signed temporary IPAs are removed after installation.

Set the data directory with ipa-hub --data-dir PATH install … or the IPA_HUB_HOME environment variable. It defaults to ~/.ipa-hub. See environment variables for defaults, authentication, and background-service configuration. If a compatible local server is running, the CLI delegates the installation to it. Use --bypass-server for an independent installation.

See device selection and signing for destination, team, and profile flags.

Edit this page