From a6b95dbac5f97a870c7ef58701726ad9733ea75d Mon Sep 17 00:00:00 2001
From: kaitranntt <kaitran.ntt@gmail.com>
Date: Sun, 14 Dec 2025 01:07:20 -0500
Subject: [PATCH] fix(cliproxy): add SSH port forwarding instructions for
 headless OAuth

When running OAuth in headless mode (SSH/remote), users now see clear
instructions about port forwarding requirement before the OAuth URL.
Previously, CLIProxyAPI's instructions were captured but not displayed.

- Show [!] PORT FORWARDING REQUIRED warning
- Explain that localhost:8085 callback must be reachable
- Show ssh -L command with <USER>@<HOST> placeholders
- Emphasize running on LOCAL machine, not remote
---
 src/cliproxy/auth-handler.ts | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/src/cliproxy/auth-handler.ts b/src/cliproxy/auth-handler.ts
index d1d8840a..0faae062 100644
--- a/src/cliproxy/auth-handler.ts
+++ b/src/cliproxy/auth-handler.ts
@@ -16,7 +16,7 @@ import { execSync, spawn } from 'child_process';
 import * as fs from 'fs';
 import * as path from 'path';
 import { ProgressIndicator } from '../utils/progress-indicator';
-import { ok, fail, info, warn } from '../utils/ui';
+import { ok, fail, info, warn, color } from '../utils/ui';
 import { ensureCLIProxyBinary } from './binary-manager';
 import { generateConfig, getProviderAuthDir } from './config-generator';
 import { CLIProxyProvider } from './types';
@@ -537,8 +537,14 @@ export async function triggerOAuth(
   console.log('');
   if (headless) {
     console.log(info('Headless mode detected - manual authentication required'));
-    console.log(info(`${oauthConfig.displayName} will display an OAuth URL below`));
     console.log('');
+    console.log(warn('PORT FORWARDING REQUIRED'));
+    console.log('    OAuth callback uses localhost:8085 which must be reachable.');
+    console.log('    Run this on your LOCAL machine (replace <USER> and <HOST>):');
+    console.log('');
+    console.log(`    ${color('ssh -L 8085:localhost:8085 <USER>@<HOST>', 'command')}`);
+    console.log('');
+    console.log(info(`${oauthConfig.displayName} OAuth URL:`));
   } else {
     console.log(info(`Opening browser for ${oauthConfig.displayName} authentication...`));
     console.log(info('Complete the login in your browser.'));