Environment variables

Exactly which environment variables each Referalli package reads, which pre-rename names still work and until when, and which names are only conventions in our examples.

Embed

<a href="https://referalli.com/docs/environment-variables"><img src="https://referalli.com/docs/_api/public/orgs/07f432f4-34b9-46a7-aaad-c0e395d2e4f9/spaces/2bf4f614-3630-4fbf-85f9-5ecafa6b7d97/pages/4f49151a-22fa-40e9-b98a-c6710df6a527/social-card.svg?v=3e7ae33eec8b" alt="Environment variables" width="600" height="315"></a>

Referalli's packages read only the environment variables below. Every other name you see in our examples (REFERALLI_WEBHOOK_SECRET, REFERALLI_BILLING_SECRET, REFERALLI_PROGRAM_ID in your app, …) is a convention: your code reads it and passes the value in, so you can call it anything.

What each package reads

Package	Reads	Meaning
CLI (`@referalli/cli`)	`REFERALLI_API_KEY`	Use this key instead of the saved login.
	`REFERALLI_API_URL`	API base URL (default `https://referalli.com`).
	`REFERALLI_CONFIG_DIR`	Where the login is saved (default `$XDG_CONFIG_HOME/referalli`, else `~/.config/referalli`).
	`XDG_CONFIG_HOME`	Only to find the default config directory.
	`REFERALLI_PROGRAM_ID`	The default for `--program` (`doctor`, `partners list`).
	`REFERALLI_TRACKING_TOKEN`, `NEXT_PUBLIC_REFERALLI_TRACKING_TOKEN`	`doctor` checks the token your app is configured with; `doctor --e2e` uses it with a program-scoped key.
Server SDK (`referalli`)	`REFERALLI_API_KEY`	The default `apiKey` of `new Referalli()`.
	`REFERALLI_BASE_URL`	The default `baseUrl` (default `https://referalli.com`). Note: not `REFERALLI_API_URL`, which is the CLI's and the MCP server's.
Next.js (`@referalli/next`)	none directly	Its server helpers (`ReferralPanel` and the others in `@referalli/next/server`) default to `new Referalli()`, so they read the server SDK's two names. `verifyWebhook` and `createWebhookHandler` take the secret as an argument.
React (`@referalli/react`)	none	Everything is a prop: the tracking token, the widget token, consent. A `NEXT_PUBLIC_…` value works because Next.js inlines it at build time, not because the package reads it.
Express (`@referalli/express`)	none	`referalliWebhook({ secret })` takes the secret as an argument.
MCP server (`@referalli/mcp`)	`REFERALLI_API_KEY`, `REFERALLI_API_URL`	The key (or partner token) and the API base URL.

The other server SDKs (Python, Ruby, Go, PHP, Swift, Kotlin) read nothing from the environment: pass the key to the client.

Names from before the rename

Only the CLI ever read REFERALLY_* names. It still reads these when the new name isn't set, with a notice on stderr, until 2027-03-31:

Old name	New name
`REFERALLY_API_KEY`	`REFERALLI_API_KEY`
`REFERALLY_API_URL`	`REFERALLI_API_URL`
`REFERALLY_CONFIG_DIR`	`REFERALLI_CONFIG_DIR`
`REFERALLY_TRACKING_TOKEN`	`REFERALLI_TRACKING_TOKEN`
`NEXT_PUBLIC_REFERALLY_TRACKING_TOKEN`	`NEXT_PUBLIC_REFERALLI_TRACKING_TOKEN`

Any other REFERALLY_* name in your project (REFERALLY_BILLING_SECRET, REFERALLY_PROGRAM_ID, REFERALLY_WEBHOOK_SECRET, …) is your own: nothing of ours reads it, so nothing breaks on any date. Rename it when convenient. referalli doctor --scan warns only on the five names above and lists the rest as ℹ info, so --strict passes once those five are renamed. All other old names and their dates are under Renamed from Referally.

Updated Nov 11, 2026

Was this page helpful?