Logging Into Higgsfield CLI on a Headless Server: The localhost Trap
Why OAuth PKCE CLI logins fail on headless servers: localhost is per-machine, redirect URIs are allowlisted, and how replaying the callback URL manually solves it.
Installing the Higgsfield CLI on a headless server surfaces a familiar OAuth 2.0 PKCE snag: the CLI opens a loopback listener and waits for a browser redirect to localhost, but on a headless box the browser lives on a laptop while the listener runs on the server — so the redirect dies with 'Unable to connect.' The failure isn't the tool's fault; it's the loopback flow's silent assumption that browser and listener share a machine.
The instinctive fix, an SSH tunnel, works but collides with another constraint: trying to pin a specific port via --port triggers Clerk's 'redirect_uri does not match' error, because PKCE removes the client secret but keeps the provider's pre-registered redirect-URI allowlist intact. You can only use ports the app already registered, not ones you choose.
The cleaner fix comes from recognizing the callback as nothing more than a GET request carrying a code and a state parameter. After letting the browser redirect fail, you copy that dead URL from the address bar and replay it with curl directly against the server's own listener — which validates the state, exchanges the code for a token, and completes login. Because state is the flow's built-in anti-forgery check, this hand-delivery isn't bypassing security; it's satisfying the exact mechanism the flow relies on.
The piece frames this as a general technique for any CLI using loopback OAuth redirects on headless machines — skip the tunnel, treat the callback as portable data, and hand-carry it yourself.