Reference

CLI reference

The pharen command-line tool is the thin, authenticated client behind distribution and symbol upload. The fastlane plugin and the Xcode run script wrap it — this page is the underlying surface. The CLI and the MCP connection are the supported interfaces to Pharen; the HTTP API behind them is not yet a public contract, so its paths and fields can change.

pharen setup ios

The whole on-ramp as one command: sign in, write the project files, mint your ingest keys, wire the project, verify. What's left afterwards is one line of your own Swift.

pharen setup ios      # sign in, configure, wire, verify
# ── call Pharen.start(), build and run the app ──
pharen verify --wait  # confirm your first event arrived

setup doesn't watch for your first event, because on a first run nothing can have arrived — you still have to build. The confirmation is its own command, whose name is what it does, and setup prints it at the moment it becomes useful, so there is nothing to remember. (setup --wait exists as sugar when you already have the app running and want one command end to end.)

In the ordinary case it takes no arguments at all. Your org is derived from your credential, and your app id is proposed from the project's own bundle identifier (case-folded, so com.Acme.MyApp and com.acme.myapp are the same app) and confirmed with you before it is used. So there is nothing to look up and nothing to get wrong. --app overrides the proposal; if you pass --org and it disagrees with your credential, that's a hard stop rather than a silent switch to the wrong organization.

It is stateless and idempotent: every step declines to redo work that is already done, so re-running always resumes and never repeats. That is why “run it again when you've wired it up” is safe, and why a re-run can't issue a second set of keys.

Wiring your project

Where your project is built from a project.yml (XcodeGen), setupalso points it at the generated config, adds the SDK package, and declares PharenIngestKey in your Info.plist. It prints every edit — file by file, line by line — and asks before writing any of them. You know whether your working tree is clean and whether now is the moment; the tool doesn't.

-y applies without asking (for CI and scripted runs) and --no-wire skips the step. With no terminal and no -y the answer is no, the plan is still printed, and the run continues — it never blocks waiting on input that can't arrive. Declining is a correct answer, not a failure: your keys are minted either way and verify reports what is still unwired.

Edits are additive only. Where anything is ambiguous — an existing configFiles: block pointing elsewhere, an inline include: [...], a hand-managed .xcodeproj — it declines and tells you what to do by hand rather than guessing at your project file. The SDK is linked to your app target only, never to App Clips or extensions.

What the CLI touches on your machine

setup and verify read your source and edit your project files, so here is the whole of it — the answer you would otherwise have to get by reading the code.

What it reads

To diagnose an integration, verify parses your project.yml, every Info.plist under your app directory, and every .swift file there (looking for a Pharen.start call). None of it is transmitted. Those reads feed a regular expression and a substring test inside the process and are then discarded. Across a whole run — --wait included — the CLI makes three requests, all GET, all to the API host you configured:

GET /v1/auth/session                    does this credential still authenticate
GET /v1/ingest-keys?app_id=…            are the keys in your build still active
GET /v1/events?app_id=&environment=…    has anything arrived yet   (--wait only)

No request body, no file contents, no file paths, no source. That isn't a promise in a document: the test suite runs the whole command over a tree whose files carry distinctive markers and fails if any marker turns up in an outgoing URL, header or body. The assertion exists to break if anyone ever adds telemetry to a check.

The directory walk is bounded to your app directory and never follows a symlink — not into a directory, not to a file whose name happens to match. It also stops at a depth and entry budget, and reports when it did, so a partial answer never reads as a clean bill of health.

What it writes

• .pharen.yml, release/ and Config/Pharen.xcconfig — files Pharen owns. It refuses to overwrite an existing one unless you pass --force.
• project.yml and your Info.plist — files you own. Only additions, only after it prints every line and you say yes, and never where the situation is ambiguous. This is the step -y and --no-wire control.
• ~/.config/pharen/credentials.json — your session from pharen auth login, written 0600 in a 0700 directory. Nothing else ever writes a credential to disk, and pharen auth logout deletes it.

Configuration

Three inputs configure every command. In precedence order, highest first:

1. Command-line flags — --org, --app, --api-url.
2. Environment — PHAREN_AUTH_TOKEN (the one secret) and PHAREN_API_URL (development only; see below).
3. .pharen.yml — your committed org and app.

org: your-org      # customer-facing alias of your organization
app: your-app-id   # the app_id

.pharen.yml is found by walking up from the working directory — the nearest one wins — so it works whether a command runs from the repo root or an app subdirectory. It holds no secrets. Your --org never grants access on its own: the auth token's organization is authoritative, and a token/config mismatch is a hard 403.

Every command that talks to the control plane needs a credential (init ios is purely local unless you pass --mint). On your machine, pharen auth login signs you in from a browser and stores the session. A CI job can sign in as itself, with no secret to store — see pharen workload. Elsewhere, set PHAREN_AUTH_TOKEN as a CI secret and never commit it. Output is JSON on stdout, so fastlane and CI can parse it.

pharen init ios

Sets up a repo: writes .pharen.yml at the root and copies the release lane into your app. Local only — no network, no prompts. Re-running won't overwrite existing files unless you pass --force.

pharen init ios --org your-org --app your-app-id

Add --mint and it also issues your ingest keys and writes them into your build settings — the whole on-ramp in one command:

pharen init ios --org your-org --app your-app-id --mint

This mints one key per environment and generates a committed Config/Pharen.xcconfig that assigns them per build configuration (Debug → development, Staging → staging, Release → live), with a development-key fallback for any configuration it doesn't name — never the live key. It ends with #include? "Pharen.local.xcconfig", so a gitignored per-machine override still wins if you keep one. Everything else about init ios stays local.

--mint needs a credential. Either sign in first with pharen auth login, or add --login to run that flow as part of this command. It's opt-in rather than automatic because the sign-in blocks waiting for you to approve in a browser, and this command also runs in lanes — without the flag, a missing credential fails in a second and names what to run.

pharen verify

Checks an integration end to end and tells you what is wrong. Every way an iOS integration can be misconfigured fails silently — the SDK is deliberately quiet when it isn't configured, so a broken setup looks exactly like a working one until you go looking for data that was never sent. This is where you find out instead.

pharen verify          # check the setup
pharen verify --wait   # check it, then watch for your first event

It asserts, in order:

• .pharen.yml resolves an org and app.
• Your control credential authenticates — not merely that a token is set.
• The generated build config exists, and each configuration has a well-formed key.
• Environment alignment — Release carries a phi_live_… key, the others phi_test_…, and the unnamed-configuration fallback is never live.
• No value was truncated by the xcconfig // comment rule.
• The project actually reads the xcconfig, and some Info.plist declares PharenIngestKey. These two are best-effort file checks, so they warn and name what they looked at rather than failing your build.
• The keys baked into your build are still active server-side, and none was revoked.
• With --wait: your first event arrives — reported with the version and build it came from, so you know it was this build talking.

Each check reports pass, fail, warn, or skipped; a check that couldn't run says so rather than silently counting as a pass. Exit is non-zero on any failure, and the JSON on stdout carries the same list — so it works as a CI gate.

pharen releases create

Registers or updates a release — the anchor incoming crashes resolve against. Idempotent: re-running for the same version and build is a safe no-op.

pharen releases create --platform ios --version 1.2.0 --build 42 --commit "$(git rev-parse HEAD)"

pharen builds upload

Uploads the installable and returns the OTA install link. On iOS, --bundle-id is required — the server generates the install manifest and the device refuses a mismatch.

pharen builds upload --platform ios --version 1.2.0 --build 42 \
  --bundle-id com.yourcompany.yourapp ./App.ipa

pharen symbols upload

Uploads debug symbols, kept private under your organization. Slim by design — a token and a path is a complete invocation. Platform is inferred from the artifact (a dSYM implies iOS), and the server deduplicates by debug id, so re-uploads are cheap no-ops that still exit 0.

pharen symbols upload ./App.dSYM
pharen symbols upload ./App.xcarchive/dSYMs     # every bundle in the folder: your app's, and any a framework brought

pharen ingest-keys create

Mints a single ingest key for one environment — the phi_live_… / phi_test_… value behind PharenIngestKey. The secret is shown once, and this command hands it to you, so you place it yourself. For setting up an app, prefer pharen setup ios (or pharen init ios --mint when scripting), which mints every environment's key and writes them into your build settings for you. Reach for this one to add an environment later, or to replace a key.

pharen ingest-keys create --environment live

pharen workload

Lets a CI job sign in as itself, with nothing to store or rotate. An organization owner binds one pipeline to a scope; each command in that job then signs in on its own, with a credential that lasts at most fifteen minutes and can write only builds, symbols and releases.

# GitHub: the numeric ids (gh api repos/OWNER/REPO --jq '.id, .owner.id')
pharen workload federations add --kind github --project 123456 --project-owner 9 --environment test

# GitLab.com: the exact group/project path
pharen workload federations add --kind gitlab --project acme/app --environment test

pharen workload federations list
pharen workload token          # in the job: its organization, scope and expiry, never the token

A GitHub job needs permissions: id-token: write, and can run any number of pharen commands. A GitLab job needs id_tokens: { PHAREN_ID_TOKEN: { aud: 'https://api.pharen.ai' } } and must run on a protected branch; its token signs in once, so each pharen command needs its own token (workload token counts as one): declare one id_tokens: entry per command and pass each in turn, as in PHAREN_ID_TOKEN="$PHAREN_ID_TOKEN_2" pharen …. The release lane takes five, PHAREN_ID_TOKEN_1 through PHAREN_ID_TOKEN_5, and hands each command the next.

Everything else

The commands above are the ones you meet while setting an app up and shipping it. The rest of the tool is listed here so you know it exists; each one documents itself in full with pharen help <command>.