# Environment variables Configure ipa-hub through the environment of the process doing the work: your CLI command, foreground server, or application using the library. Explicit command options take precedence over their environment defaults. ## Storage and server port | Variable | Purpose and default | | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `IPA_HUB_HOME` | Data directory for downloads, app records, credentials, and server state. Defaults to `~/.ipa-hub`. Override with `--data-dir` or the library’s `dataDir` option. | | `IPA_HUB_PORT` | TCP port for HTTP and UDP port for WebRTC Direct, used by `serve`, `service install`, and independent app installations. Overrides the saved port in `server/config.json`; otherwise the default is `19464`. Override with `--port`. Accepts integers from `1` to `65535`. | ```sh export IPA_HUB_HOME=~/Library/ipa-hub export IPA_HUB_PORT=19465 ipa-hub serve ``` Use the same data directory for commands that should share a server, app records, and credentials. Changing `IPA_HUB_HOME` selects a different directory; it does not move existing files. Independent installations discover and embed all usable machine destinations, even without a running server. They save the listener settings so a later server can use the same port. A running server embeds its active port. In library code, `startServer` and `installService` use the same precedence: explicit `port`, `IPA_HUB_PORT`, saved port, then `19464`. The hub’s `publicURL` adds a destination and sets the port used for the embedded update URLs. ## Source authentication These variables are optional; no tokens are configured by default. | Variable | Purpose | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `GITHUB_TOKEN` | Access token for `https://github.com` and `https://api.github.com`. It is not sent to custom GitHub instances. | | `GITLAB_TOKEN` | Access token for `https://gitlab.com`. It is not sent to custom GitLab instances. | | `IPA_HUB_TOKENS` | JSON object mapping exact HTTPS origins to access tokens; defaults to `{}`. Use it for custom GitHub/GitLab instances or other HTTPS download hosts. | ```sh export GITHUB_TOKEN='your-github-token' export GITLAB_TOKEN='your-gitlab-token' export IPA_HUB_TOKENS='{"https://github.company.example":"your-token","https://downloads.example.com":"another-token"}' ``` Origins include the scheme and host, plus a port when it is not the default. They do not include a repository or file path. An entry for `https://downloads.example.com` does not apply to its subdomains or to `https://downloads.example.com:8443`. Authentication is selected in this order: 1. The installation’s explicit `--access-token` or library `accessToken` option. 2. An exact-origin entry in `IPA_HUB_TOKENS`. 3. `GITHUB_TOKEN` or `GITLAB_TOKEN` for the public hosts listed above. An empty string in `IPA_HUB_TOKENS` disables environment authentication for that origin. `IPA_HUB_TOKENS` must be a valid JSON object even when an explicit token is supplied. Tokens require HTTPS and are sent as bearer credentials. Redirects do not carry authorization to a different origin. Only an explicitly supplied per-install token is saved for later updates and signature refreshes. Environment tokens remain process configuration: future operations need them in the process that performs the network request. When an installation is delegated to a running server, it uses the server’s environment; a token exported only in the client’s terminal is not forwarded. See [private downloads](https://ipa-hub.giladgd.com/docs/guide/sources.md#private-downloads) for per-install authentication. ## Background service `service install` saves the resolved data directory and port as launch arguments, and captures the current `PATH`. Changing `IPA_HUB_HOME`, `IPA_HUB_PORT`, or `PATH` afterward does not reconfigure an installed service; run `service install` again with the intended settings. The LaunchAgent does not copy source-authentication or terminal-color variables from your shell. Use `--access-token` when installing a private app to retain its token for server-side updates, or run `ipa-hub serve` in a process with the required environment. ## Terminal and executable settings | Variable | Behavior | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NO_COLOR` | Disables CLI colors when present, including when set to an empty string. | | `NODE_DISABLE_COLORS` | Disables CLI colors when present, including when set to an empty string. | | `FORCE_COLOR` | `0` disables colors. Other values do not force colors in ipa-hub; output must still be a terminal that reports color support. | | `TERM` | `dumb` disables colors and uses numbered selections instead of arrow-key menus. Other values participate in the runtime’s terminal capability detection. | | `PATH` | Search path for executables invoked by name, including `npm`. Service installation saves its current value, falling back to `/usr/bin:/bin:/usr/sbin:/sbin` if unset. | ```sh NO_COLOR=1 ipa-hub device ls ``` ipa-hub only uses colors for terminal output with color support. Piped output stays uncolored. It inherits the process environment for child commands but sets `LC_ALL=C` so their output can be parsed consistently. Provisioning builds use a private `TMPDIR` inside their temporary workspace; `TMPDIR` does not configure ipa-hub’s temporary-directory location. ## Building and testing the repository These variables are for contributors. They do not configure an installed ipa-hub server. | Variable | Purpose and default | | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `WEBSITE_BASE` | Base path for the website’s Vite build, generated documentation URLs, and website browser tests. Defaults to `/`. Use leading and trailing slashes. | | `WEBAPP_BASE` | Base path for the webapp’s Vite assets and service-worker cache URLs. Defaults to `/app/` and must stay within `/app/` to keep the website outside the worker's scope. This does not change the server’s hosted-manager URL or the Pages packaging destination. | | `DOCS_PACKAGE_VERSION` | Version displayed in generated documentation and the website toolbar. Defaults to the version in `package.json`. The release workflow sets it to the published version. | | `IPA_HUB_TEST_CHROMIUM` | Chromium executable for website screenshots, website browser tests, and offline-webapp tests. Defaults to `/usr/bin/chromium`. | | `IPA_HUB_DEV_ALLOW_NON_MACOS` | Development-only platform override. Set exactly `1` to enable CLI commands and the real library implementation on another OS. Unset by default. It does not emulate Xcode, signing, or device access. | | `CI` | `CI=true` skips Git-hook installation in the repository’s prepare script. Unset by default. | ```sh IPA_HUB_TEST_CHROMIUM='/Applications/Chromium.app/Contents/MacOS/Chromium' npm run test:website ``` Without the development override, every CLI command on a non-macOS system exits with code `1` and a macOS-only error. Programmatic `getIpaHub()` calls warn once per instance and return an inactive instance: device, team, app, and release lists are empty; other operations reject with the macOS-only error. These instances do not create a data directory or contact a server. The library’s `warn` callback can receive the warning instead of the console.