# Getting started

ipa-hub downloads, signs, and installs IPA apps on your paired Apple devices. Run a single command on your Mac, or keep a server running and manage your apps from the manager.

## Prepare your Mac

Install [Xcode](https://apps.apple.com/app/xcode/id497799835) and sign in to your Apple account in **Xcode → Settings → Accounts**. ipa-hub reuses the signing certificate already in your Mac. It never asks for your Apple password.

Open **Device Hub** (installed with Xcode), choose **File → Pair Nearby Device...** from the macOS menu bar at the top of the screen, and follow the prompts to pair your device. Enable Developer Mode when your device asks for it.

- [Node.js **24 or later**](https://nodejs.org/en/download), or [Bun **1.4.2 or later**](https://bun.com/).
- A signing team configured in Xcode. ipa-hub reuses its local signing identity and asks Xcode to refresh provisioning when needed.

## Install your first app

No global installation is required:

```sh
npx -y ipa-hub install gh:utmapp/UTM
```

ipa-hub finds the latest release, lets you choose an `ipa` file and device when needed, signs the app, and installs it.

## Start a background server

```sh
npm i -g ipa-hub && ipa-hub service install --setup-manager
```

This starts the server immediately and installs a LaunchAgent that starts when you log in.
It also installs the App Manager on your selected device so that you can install and update apps from the device itself.
Use ↑/↓ and Enter to choose a paired iPhone or iPad for **App Manager**, or choose **Skip App Manager installation**. Add the personal link to your Home Screen when prompted; the icon is named **ipa-hub**. Keep the Mac awake for network installations.

You can also set up App Manager while installing an app with the global CLI:

```sh
ipa-hub install gh:utmapp/UTM --setup-manager
```

Choose the target device first. ipa-hub ensures the service is installed and started, installs the app through the server, then sets up App Manager on that device and opens its personal link. Add `--open` to open the installed app instead. With npx/bunx, `--setup-manager` requires an existing server or installed service; it never installs a service from a temporary CLI.

## Add App Manager to another device

```sh
ipa-hub service manager install
```

Choose your paired iPhone or iPad. Safari opens its personal setup page: choose **Share → Add to Home Screen**, keep **Open as Web App** enabled if shown, then tap **Add**. Open the **ipa-hub** Home Screen icon to use App Manager. See [App Manager setup](https://ipa-hub.giladgd.com/docs/guide/getting-started/server.md#set-up-app-manager) for details and device support.

Add `--make-admin` to let this manager manage every paired device. Each enrollment link contains private credentials; share it only with its intended device.

## Verify your setup

```sh
ipa-hub device ls
ipa-hub teams
```

If you've installed the background service, check it with `ipa-hub service status`.

Use `--help` on any command to see its flags and examples. Use `--json` for complete structured results. See [install sources](https://ipa-hub.giladgd.com/docs/guide/sources.md), [devices and signing](https://ipa-hub.giladgd.com/docs/guide/devices.md), or [server setup](https://ipa-hub.giladgd.com/docs/guide/server.md) next.

For storage paths, server ports, authentication tokens, and terminal settings, see [environment variables](https://ipa-hub.giladgd.com/docs/guide/environment-variables.md).