Environment Variables

The wh CLI reads a small set of environment variables for authentication, the default repo target, and the backend URL. This page is the canonical list of those client variables, with the precedence rules that decide which value wins when more than one source is set.

It also records the backend runtime variables that configure WarmHub’s hosted checkpoint store, under Repository checkpoint storage. Those are documented for reference only — they are read by the service, not by your shell, so setting them locally changes nothing about how wh behaves.

The variables use two prefixes: WH_* for authentication and client flags (WH_TOKEN, WH_PROFILE, WH_CLIENT_FLAGS) and WARMHUB_* for connection and repo context (WARMHUB_API_URL, WARMHUB_REPO, WARMHUB_ORG). The two prefixes are not interchangeable — use the exact names in the table below.

Variables

Variable	Purpose	Example
WH_TOKEN	WarmHub authentication. A bearer token (personal access token) the CLI sends on every request.	eyJhbGciOi...
WH_PROFILE	Named auth profile to use, equivalent to --profile / -P.	staging
WH_CLIENT_FLAGS	A comma-separated list of client-flag tokens to declare on every request in this session. Client flags are opt-in feature switches the backend applies when it recognizes and currently honors them — see Client flags below. Each token must match ^[a-z0-9-]+$. The CLI unions these with any flags stored in the active profile, so flags set here extend rather than replace profile-stored flags. Useful for automation and environments without a stored profile.	my-flag
WARMHUB_REPO	Default org/repo for commands that take a repo.	myorg/myrepo
WARMHUB_ORG	Default org for org-scoped commands and for resolving a bare repo name (myrepo → myorg/myrepo).	myorg
WARMHUB_API_URL	Backend API URL. Overrides the default https://api.warmhub.ai.	https://warmhub.example.com

Set them as you would any environment variable:

export WH_TOKEN=eyJhbGciOi...
export WARMHUB_REPO=myorg/myrepo
wh thing list            # targets myorg/myrepo, authenticated with WH_TOKEN

Precedence

Authentication

The CLI resolves the auth token in this order:

Priority	Source
1	WH_TOKEN environment variable
2	--profile flag
3	WH_PROFILE environment variable
4	Profile recorded in the .wh file for the current directory (written by wh use <org/repo> --profile <name>)
5	default profile

When WH_TOKEN is set it takes priority over any stored profile — wh auth login writes a profile but does not override an exported WH_TOKEN. The server validates the token, so an invalid or expired WH_TOKEN surfaces as an authentication error rather than silently falling back to a profile.

Note that the .wh file in the current directory (priority 4) is checked before falling back to default. If you ran wh use myorg/myrepo --profile work in a directory, the CLI will use the work profile there even without setting --profile or WH_PROFILE.

Client flags

Client flags are opt-in feature switches declared on requests to the backend. The backend applies only the flags it recognizes and currently honors — well-formed tokens that aren’t recognized are sent but have no effect. Specific flag names are internal and not documented here; consult internal documentation for the current set. To control debug output or the update check, use WARMHUB_DEBUG and WARMHUB_CLI_NO_UPDATE_CHECK instead (see Advanced CLI behavior).

The CLI resolves client flags by unioning two sources:

1. Flags stored in the active profile (set via wh auth login --flag)
2. WH_CLIENT_FLAGS environment variable

Flags from both sources are merged, with WH_CLIENT_FLAGS extending rather than replacing profile-stored flags. There is no per-command client-flags override at runtime; the only way to store flags for future runs is via wh auth login --flag.

To declare a flag for a single session, export WH_CLIENT_FLAGS before running wh:

export WH_CLIENT_FLAGS=my-flag
wh thing list

To declare multiple flags, separate them with commas:

export WH_CLIENT_FLAGS=flag-one,flag-two
wh thing list

Repo target

Commands resolve the target repo in this order:

1. --repo org/repo flag (per-command override)
2. WARMHUB_REPO environment variable
3. .wh file in the current directory (written by wh use)

WARMHUB_ORG does not select a repo on its own. It supplies the org for a bare repo name (wh thing list --repo myrepo) and for org-scoped commands that take an org but no repo, such as wh repo list.

Backend URL

The CLI resolves the backend URL in this order:

1. --api-url flag
2. The active profile’s stored URL (profiles are created by wh auth login)
3. WARMHUB_API_URL environment variable
4. The default, https://api.warmhub.ai

WARMHUB_API_URL is a fallback that applies only when no profile sets a URL — a loaded profile’s URL takes priority over it. To point a profile-bound CLI at a different backend, pass --api-url.

Using these with the SDK

The SDK does not read any environment variables directly. Pass the token to the client explicitly — typically by reading WH_TOKEN in your own code:

import { WarmHubClient } from "@warmhub/sdk-ts"

const client = new WarmHubClient({
  auth: { getToken: async () => process.env.WH_TOKEN },
})

See the SDK overview for the full client setup.

Using these with the MCP server

The MCP endpoint authenticates the bearer token sent in the Authorization header. WH_TOKEN is a convenient local source for that value — reference it as Bearer ${WH_TOKEN} in your MCP client config. See the MCP server guide.

Advanced CLI behavior

These variables tune CLI behavior and are optional:

Variable	Purpose	Example
WARMHUB_CLI_HTTP_TIMEOUT_MS	HTTP headers/body timeout in milliseconds for long-running requests (Node only; no-op under Bun). Default 5700000 (95 minutes); 0 disables the timeout.	3600000
WARMHUB_CLI_NO_UPDATE_CHECK	Disable the background CLI update check. Set to 1, true, or TRUE. Equivalent to --no-update-check.	1
WARMHUB_DEBUG	Set to 1 to enable debug output, equivalent to --debug.	1
WARMHUB_FUNCTION_LOGS	Replay backend function logs. Set to off or raw. Equivalent to --function-logs.	raw

Repository checkpoint storage

These backend runtime variables configure the private object store that holds repository checkpoints. They are not CLI client settings, and nothing in this section is something a CLI user sets — it documents how the hosted service is configured. Keep the R2 credentials in your deployment secret manager; callers receive short-lived signed download URLs instead of object-store credentials.

Variable	Purpose
WARMHUB_CHECKPOINT_R2_ACCOUNT_ID	Cloudflare account identifier for the private checkpoint R2 bucket.
WARMHUB_CHECKPOINT_R2_BUCKET	Private, environment-specific R2 bucket name.
WARMHUB_CHECKPOINT_R2_ACCESS_KEY_ID	Bucket-scoped R2 API access-key identifier.
WARMHUB_CHECKPOINT_R2_SECRET_ACCESS_KEY	Secret half of the bucket-scoped R2 API credential.
WARMHUB_CHECKPOINT_ACCESS_TTL_SECONDS	Signed checkpoint-download URL lifetime. Defaults to 3600; values must be integers from 1 through 604800.

Outside explicit local or test runtimes, all four WARMHUB_CHECKPOINT_R2_* settings are required. WARMHUB_CHECKPOINT_ACCESS_TTL_SECONDS is optional and applies environment-wide; clients cannot override it.

Component sources and GitHub

WarmHub does not read a GITHUB_TOKEN environment variable from your shell. Credentials for private GitHub-backed component sources are stored explicitly as a named credential — wh credential set <set-name> GITHUB_TOKEN --org myorg — and resolved by the backend at install time. See the component registry reference.