[HDX-3976] CLI: migrate from apiUrl to appUrl with interactive login flow (#2101)

## Summary

Migrates the CLI from using API URLs (`-s, --server`) to app URLs (`-a, --app-url`), and adds interactive login prompts on expired/missing sessions.

Linear: https://linear.app/clickhouse/issue/HDX-3976

---

## Breaking Change

**The `-s` / `--server` flag has been removed.** All commands (except `upload-sourcemaps`) now use `-a` / `--app-url` instead.

The URL semantics have changed: users should now provide the **HyperDX app URL** (e.g. `http://localhost:8080`), not the API URL. The CLI derives the API URL internally by appending `/api`.

| Before | After |
|---|---|
| `hdx auth login -s http://localhost:8080/api` | `hdx auth login -a http://localhost:8080` |
| `hdx tui -s http://localhost:8080/api` | `hdx tui -a http://localhost:8080` |
| `hdx sources -s http://localhost:8080/api` | `hdx sources -a http://localhost:8080` |

> **Note:** `upload-sourcemaps` is unchanged — it still uses `--apiUrl` / `-u` as before.

**Existing saved sessions are auto-migrated** — old `session.json` files with `apiUrl` are converted to `appUrl` on first load.

---

## Changes

### `apiUrl` → `appUrl` migration
- `ApiClient` now accepts `appUrl` and derives `apiUrl` by appending `/api`
- `SessionConfig` stores `appUrl`; legacy sessions with `apiUrl` auto-migrate on load
- All commands use `-a, --app-url` instead of `-s, --server`

### Interactive login flow (HDX-3976)
- `hdx auth login` no longer requires `-a` — it prompts interactively for login method, app URL, then credentials
- Login method selector is extensible (currently Email/Password, designed for future OAuth support)
- **Expired sessions now prompt for re-login** instead of printing an error and exiting
- The app URL field is autofilled with the last used value so users can just hit Enter
- No longer requires manual deletion of `~/.config/hyperdx/cli/session.json` to recover from expired sessions
- Non-TUI commands (`sources`, `dashboards`, `query`) also launch interactive login on expired/missing sessions via `ensureSession()` helper

### TUI (`App.tsx`)
- Detects expired session on mount and shows "Session expired" message with editable URL field
- If the user changes the URL during re-login, the client is recreated
- 401/403 errors during data loading bounce back to the login screen instead of showing raw error messages

### Input validation & error handling
- App URL inputs are validated — rejects non-`http://` or `https://` URLs with a clear inline error
- `ApiClient.login()` catches network/URL errors and returns `false` instead of crashing
- `ApiClient.login()` verifies the session after a 302/200 response by calling `checkSession()` — prevents false "Logged in" messages from servers that return 302 without a valid session (e.g. SSO redirects)
- Login failure messages now mention both credentials and server URL

---

## Files changed

- `packages/cli/src/api/client.ts` — accepts `appUrl`, derives `apiUrl`, exposes `getAppUrl()`, login validation
- `packages/cli/src/utils/config.ts` — `SessionConfig.appUrl`, backward-compat migration
- `packages/cli/src/cli.tsx` — `-a` flag, `LoginPrompt`, `ReLoginPrompt`, `ensureSession()`, URL validation
- `packages/cli/src/App.tsx` — expired session detection, editable URL on re-login, 401/403 handling
- `packages/cli/src/components/LoginForm.tsx` — app URL prompt field, `message` prop, URL validation

Author: wrn14897

.changeset/cli-app-url-migration.md

@@ -0,0 +1,10 @@
+---
+"@hyperdx/cli": minor
+---
+
+**Breaking:** Replace `-s`/`--server` flag with `-a`/`--app-url` across all CLI commands (except `upload-sourcemaps`). Users should now provide the HyperDX app URL instead of the API URL — the CLI derives the API URL by appending `/api`.
+
+- `hdx auth login` now prompts interactively for login method, app URL, and credentials (no flags required)
+- Expired/missing sessions prompt for re-login with the last URL autofilled instead of printing an error
+- Add URL input validation and post-login session verification
+- Existing saved sessions are auto-migrated from `apiUrl` to `appUrl`

packages/cli/src/App.tsx

@@ -18,7 +18,7 @@ import EventViewer from '@/components/EventViewer';
 type Screen = 'loading' | 'login' | 'pick-source' | 'events' | 'alerts';
 
 interface AppProps {
-  apiUrl: string;
+  appUrl: string;
   /** Pre-set search query from CLI flags */
   query?: string;
   /** Pre-set source name from CLI flags */
@@ -27,9 +27,11 @@ interface AppProps {
   follow?: boolean;
 }
 
-export default function App({ apiUrl, query, sourceName, follow }: AppProps) {
+export default function App({ appUrl, query, sourceName, follow }: AppProps) {
   const [screen, setScreen] = useState<Screen>('loading');
-  const [client] = useState(() => new ApiClient({ apiUrl }));
+  const [client, setClient] = useState(() => new ApiClient({ appUrl }));
+  const [currentAppUrl, setCurrentAppUrl] = useState(appUrl);
+  const [sessionExpired, setSessionExpired] = useState(false);
   const [eventSources, setLogSources] = useState<SourceResponse[]>([]);
   const [savedSearches, setSavedSearches] = useState<SavedSearchResponse[]>([]);
   const [selectedSource, setSelectedSource] = useState<SourceResponse | null>(
@@ -43,18 +45,19 @@ export default function App({ apiUrl, query, sourceName, follow }: AppProps) {
     (async () => {
       const valid = await client.checkSession();
       if (valid) {
-        await loadData();
+        await loadData(client);
       } else {
+        setSessionExpired(true);
         setScreen('login');
       }
     })();
   }, []);
 
-  const loadData = async () => {
+  const loadData = async (apiClient: ApiClient) => {
     try {
       const [sources, searches] = await Promise.all([
-        client.getSources(),
-        client.getSavedSearches().catch(() => [] as SavedSearchResponse[]),
+        apiClient.getSources(),
+        apiClient.getSavedSearches().catch(() => [] as SavedSearchResponse[]),
       ]);
 
       const queryableSources = sources.filter(
@@ -92,14 +95,34 @@ export default function App({ apiUrl, query, sourceName, follow }: AppProps) {
 
       setScreen('pick-source');
     } catch (err: unknown) {
-      setError(err instanceof Error ? err.message : String(err));
+      const msg = err instanceof Error ? err.message : String(err);
+      // Treat auth errors as session issues — bounce back to login
+      if (msg.includes('401') || msg.includes('403')) {
+        setSessionExpired(true);
+        setScreen('login');
+        return;
+      }
+      setError(msg);
     }
   };
 
-  const handleLogin = async (email: string, password: string) => {
-    const ok = await client.login(email, password);
+  const handleLogin = async (
+    loginAppUrl: string,
+    email: string,
+    password: string,
+  ) => {
+    // Recreate client if the user changed the URL
+    let activeClient = client;
+    if (loginAppUrl !== currentAppUrl) {
+      activeClient = new ApiClient({ appUrl: loginAppUrl });
+      setClient(activeClient);
+      setCurrentAppUrl(loginAppUrl);
+    }
+
+    const ok = await activeClient.login(email, password);
     if (ok) {
-      await loadData();
+      setSessionExpired(false);
+      await loadData(activeClient);
     }
     return ok;
   };
@@ -148,13 +171,23 @@ export default function App({ apiUrl, query, sourceName, follow }: AppProps) {
       return (
         <Box paddingX={1}>
           <Text>
-            <Spinner type="dots" /> Connecting to {apiUrl}…
+            <Spinner type="dots" /> Connecting to {currentAppUrl}…
           </Text>
         </Box>
       );
 
     case 'login':
-      return <LoginForm apiUrl={apiUrl} onLogin={handleLogin} />;
+      return (
+        <LoginForm
+          defaultAppUrl={currentAppUrl}
+          onLogin={handleLogin}
+          message={
+            sessionExpired
+              ? 'Session expired — please log in again.'
+              : undefined
+          }
+        />
+      );
 
     case 'pick-source':
       return (

packages/cli/src/api/client.ts

@@ -31,22 +31,28 @@ import { loadSession, saveSession, clearSession } from '@/utils/config';
 // ------------------------------------------------------------------
 
 interface ApiClientOptions {
-  apiUrl: string;
+  appUrl: string;
 }
 
 export class ApiClient {
+  private appUrl: string;
   private apiUrl: string;
   private cookies: string[] = [];
 
   constructor(opts: ApiClientOptions) {
-    this.apiUrl = opts.apiUrl.replace(/\/+$/, '');
+    this.appUrl = opts.appUrl.replace(/\/+$/, '');
+    this.apiUrl = `${this.appUrl}/api`;
 
     const saved = loadSession();
-    if (saved && saved.apiUrl === this.apiUrl) {
+    if (saved && saved.appUrl === this.appUrl) {
       this.cookies = saved.cookies;
     }
   }
 
+  getAppUrl(): string {
+    return this.appUrl;
+  }
+
   getApiUrl(): string {
     return this.apiUrl;
   }
@@ -58,20 +64,31 @@ export class ApiClient {
   // ---- Auth --------------------------------------------------------
 
   async login(email: string, password: string): Promise<boolean> {
-    const res = await fetch(`${this.apiUrl}/login/password`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ email, password }),
-      redirect: 'manual',
-    });
+    try {
+      const res = await fetch(`${this.apiUrl}/login/password`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ email, password }),
+        redirect: 'manual',
+      });
 
-    if (res.status === 302 || res.status === 200) {
-      this.extractCookies(res);
-      saveSession({ apiUrl: this.apiUrl, cookies: this.cookies });
-      return true;
-    }
+      if (res.status === 302 || res.status === 200) {
+        this.extractCookies(res);
+
+        // Verify the session is actually valid — some servers return
+        // 302/200 without setting a real session (e.g. SSO redirects).
+        if (!(await this.checkSession())) {
+          return false;
+        }
 
-    return false;
+        saveSession({ appUrl: this.appUrl, cookies: this.cookies });
+        return true;
+      }
+
+      return false;
+    } catch {
+      return false;
+    }
   }
 
   async checkSession(): Promise<boolean> {