Forem: Kriasoft

Browser Auto-Open: Seamless OAuth UX for CLI Tools

Konstantin Tarkus — Wed, 20 Aug 2025 17:36:34 +0000

Picture this: you're setting up a new CLI tool, and it needs to authenticate with GitHub. Instead of hunting for API keys or copying tokens, the tool simply opens your browser, you click "Authorize," and you're done. That magic moment — when the browser opens automatically — transforms OAuth from a technical hurdle into a delightful experience.

But getting that browser launch right is harder than it looks. Different operating systems, edge cases with headless environments, custom browser preferences, and security considerations all conspire to turn a simple open() call into a complex engineering challenge.

The Art of Opening Browsers Cross-Platform

Opening a browser sounds trivial until you realize every operating system does it differently. macOS uses open, Windows wants start, and Linux fragments across xdg-open, gnome-open, and countless others. Then there's WSL, where you need to reach back to Windows. And don't forget about users with custom default browsers or those running in Docker containers.

The open package has become the de facto standard for handling this complexity, abstracting away platform differences with a simple API:

import open from "open";

// Opens in the user's default browser
await open("https://github.com/login/oauth/authorize?...");

// Force a specific browser
await open(url, { app: { name: "firefox" } });

// Non-blocking for better UX
open(url, { wait: false });

Under the hood, open handles an impressive array of edge cases. It detects WSL and uses powershell.exe to launch Windows browsers. It respects the BROWSER environment variable for Linux users who've customized their setup. It even handles spaces in URLs and special characters that would break naive implementations.

Smart Defaults with Escape Hatches

The key to great developer experience is making the common case trivial while keeping the complex cases possible. In oauth-callback, browser launching is enabled by default but fully configurable:

// Default behavior - just works
const result = await getAuthCode({
  authorizationUrl: "https://oauth.example.com/authorize?...",
});

// Disable for CI/headless environments
const result = await getAuthCode({
  authorizationUrl: url,
  openBrowser: false, // User must manually open the URL
});

// Custom browser handling
const result = await getAuthCode({
  authorizationUrl: url,
  openBrowser: false,
});
// Implement your own logic
await myCustomBrowserLauncher(url);

This flexibility becomes crucial in different environments. CI systems often run headless, so automatic browser launching would fail. Some users prefer copying URLs to browsers on different machines. Others might be running in containers or SSH sessions where browser access is impossible.

Handling Launch Failures Gracefully

Browser launching can fail for numerous reasons: the system might be headless, the user might have unusual configurations, or security policies might block the operation. Rather than crashing, provide a fallback:

async function launchBrowser(url: string, options: GetAuthCodeOptions) {
  if (!options.openBrowser) {
    console.log(`Please open this URL in your browser:\n${url}`);
    return;
  }

  try {
    await open(url);
    console.log("Opening browser...");
  } catch (error) {
    // Fallback to manual URL opening
    console.log("Could not open browser automatically.");
    console.log(`Please open this URL manually:\n${url}`);
  }
}

Some tools go further, displaying QR codes for mobile authentication or providing platform-specific instructions when automatic launching fails. The GitHub CLI, for example, offers to wait if you need to switch to a different device.

Non-Blocking for Better Performance

A subtle but important detail: browser launching should never block your OAuth flow. Users might take time to authenticate, the browser might be slow to start, or they might ignore the prompt entirely. Your server should be ready immediately:

export async function getAuthCode(options: GetAuthCodeOptions) {
  const server = createCallbackServer();

  try {
    // Start server first
    await server.start({
      port: options.port,
      hostname: options.hostname,
    });

    // Launch browser without waiting
    if (options.openBrowser) {
      // Don't await - let it run in parallel
      open(options.authorizationUrl).catch(() => {
        // Log but don't fail
        console.log("Note: Could not open browser automatically");
      });
    }

    // Server is ready regardless of browser status
    const result = await server.waitForCallback(
      options.callbackPath,
      options.timeout,
    );

    return result;
  } finally {
    await server.stop();
  }
}

This pattern ensures your callback server is always ready, even if the browser takes 10 seconds to launch or fails entirely. Users who manually copy the URL won't face race conditions, and automated testing remains reliable.

Testing Without Real Browsers

Automated testing shouldn't spawn actual browser windows. The openBrowser flag enables test-friendly behavior:

// In tests
const mockProvider = new MockOAuthProvider();

const result = await getAuthCode({
  authorizationUrl: mockProvider.authUrl,
  openBrowser: false, // Prevent browser launch
  port: 0, // Use random available port
});

// Simulate the OAuth callback programmatically
await mockProvider.completeAuth({
  code: "test-auth-code",
  state: "test-state",
});

expect(result.code).toBe("test-auth-code");

For integration with Model Context Protocol servers or other automation scenarios, you might want programmatic control:

export const browserAuth = () => ({
  async authenticate(params: AuthenticateParams) {
    const options = {
      authorizationUrl: params.url,
      openBrowser: process.env.CI ? false : true,
      timeout: params.timeout,
    };

    if (!options.openBrowser) {
      // MCP client handles URL display
      await params.onAuthUrl(params.url);
    }

    return getAuthCode(options);
  },
});

Security Considerations

Browser launching introduces several security considerations worth addressing:

1. URL Validation: Always validate authorization URLs before opening them. Malicious URLs could lead to phishing or execute local protocols:

function validateAuthUrl(url: string): void {
  const parsed = new URL(url);

  // Only allow HTTPS (with localhost exception for testing)
  if (
    parsed.protocol !== "https:" &&
    !(parsed.protocol === "http:" && parsed.hostname === "localhost")
  ) {
    throw new Error("Authorization URL must use HTTPS");
  }

  // Prevent file:// and other dangerous protocols
  if (!["http:", "https:"].includes(parsed.protocol)) {
    throw new Error("Invalid protocol in authorization URL");
  }
}

2. Command Injection: When spawning browser processes, always use array arguments rather than string concatenation to prevent command injection:

// WRONG - vulnerable to injection
exec(`open ${url}`);

// RIGHT - safe from injection
spawn("open", [url]);

3. User Consent: Consider warning users before opening browsers, especially if the URL isn't from a trusted source:

if (options.requireConfirmation) {
  const answer = await prompt("Open browser for authentication? (y/n): ");
  if (answer.toLowerCase() !== "y") {
    console.log(`Please open this URL manually:\n${url}`);
    return;
  }
}

Platform-Specific Enhancements

Different platforms offer unique opportunities to enhance the browser-opening experience:

macOS: Use AppleScript for more control:

// Open in a specific browser window
await runAppleScript(`
  tell application "Google Chrome"
    open location "${url}"
    activate
  end tell
`);

Windows: Leverage PowerShell for WSL compatibility:

if (isWSL()) {
  // Use PowerShell to open in Windows from WSL
  await exec(`powershell.exe -Command "Start '${url}'"`);
}

Linux: Respect desktop environment preferences:

const openers = [
  process.env.BROWSER,
  "xdg-open",
  "gnome-open",
  "kde-open",
].filter(Boolean);

for (const opener of openers) {
  try {
    await spawn(opener, [url]);
    break;
  } catch {
    // Try next opener
  }
}

Real-World Patterns

Leading CLI tools have evolved consistent patterns for browser-based authentication:

GitHub CLI shows the authorization URL and offers to wait if you're authenticating on another device:

? Where do you want to authenticate?
> Login in browser
  Paste authentication token

Vercel CLI provides clear feedback about what's happening:

> Opening browser for authentication...
> If browser doesn't open, visit:
> https://vercel.com/cli/login/...

Google Cloud SDK handles headless environments elegantly:

Go to the following link in your browser:
    https://accounts.google.com/o/oauth2/auth?...

Enter authorization code:

These patterns share common principles: clear communication, graceful fallbacks, and respect for user preferences.

Conclusion

Browser auto-opening might seem like a minor feature, but it's the difference between a tool that feels modern and one that feels clunky. By handling platform differences, providing smart defaults, failing gracefully, and respecting security boundaries, you create an authentication experience that users barely notice — the highest compliment for developer tools.

The oauth-callback library encapsulates these best practices in a simple API. Whether you're building a CLI tool, desktop application, or automation script, proper browser handling transforms OAuth from a necessary evil into a smooth, professional experience.

Remember: the best authentication is the one users don't have to think about. Make it automatic when possible, manual when necessary, and always clear about what's happening. Your users will thank you with their continued engagement rather than authentication abandonment.

Ready to implement seamless OAuth in your CLI tool? Check out oauth-callback for production-ready browser handling, cross-platform support, and battle-tested edge case management.

Why Your CLI Tool Needs OAuth (Not API Keys)

Konstantin Tarkus — Mon, 18 Aug 2025 09:58:09 +0000

Remember the last time you installed a CLI tool and it asked for your API key? You probably hunted through documentation, navigated to some settings page, generated a key, then carefully copied it into a config file. Now multiply that friction by every user of your tool.

There's a better way, and it's been hiding in plain sight.

The API Key Problem Nobody Talks About

API keys seem simple on the surface. Generate once, use forever. But that simplicity masks serious problems that compound as your tool gains adoption.

First, there's the security nightmare. Users paste API keys into dotfiles, commit them to repositories, share them in documentation. Once leaked, an API key becomes a permanent liability — there's no way to know who has it or where it's been copied. Unlike passwords that users might change periodically, API keys tend to live forever in forgotten config files.

Then there's the user experience disaster. Finding where to generate an API key requires navigating documentation that varies wildly between services. GitHub hides them under Developer Settings. Notion requires creating an integration. Slack needs an entire app configuration. Each service has its own maze, and your users have to navigate them all.

But the real killer? API keys can't adapt. They're static credentials with fixed permissions. Need to request additional scopes? Your users must generate a new key. Want to implement granular permissions? Too bad — it's all or nothing. And forget about temporary access or delegation; API keys weren't designed for modern authorization patterns.

OAuth: The Solution That's Already Everywhere

OAuth isn't new technology — it's the authentication standard that already powers most of the web. When you click "Sign in with Google" or authorize a GitHub integration, you're using OAuth. The difference is that most CLI developers haven't realized how perfectly it fits their needs.

Here's what happens when your CLI uses OAuth: A user runs your command, their browser opens, they click "Authorize," and they're done. No hunting for settings pages. No copying cryptic strings. No permanent credentials stored on disk.

The security benefits are immediate. OAuth tokens expire automatically, reducing the blast radius of any leak. Refresh tokens allow seamless re-authentication without user intervention. And when a user revokes access through the service's UI, it takes effect immediately — no orphaned API keys floating around.

But the real magic is in the flexibility. Need read-only access initially but write access for certain operations? OAuth handles incremental authorization naturally. Want to access multiple services? OAuth makes it seamless. Building a tool for teams? OAuth tokens can carry user identity, enabling proper audit trails and access control.

Making It Work in Practice

The technical implementation is surprisingly straightforward. Your CLI spins up a temporary local server, opens the user's browser to the OAuth authorization URL, and waits for the callback. When the user authorizes, the service redirects back to localhost with an authorization code. Your CLI exchanges that code for tokens and shuts down the server.

import { getAuthCode } from "oauth-callback";

const result = await getAuthCode(
  "https://github.com/login/oauth/authorize?" +
    new URLSearchParams({
      client_id: process.env.CLIENT_ID,
      redirect_uri: "http://localhost:3000/callback",
      scope: "repo user",
    }),
);

// Exchange code for tokens
const tokens = await exchangeCodeForTokens(result.code);

Modern libraries handle the complexity. Automatic browser launching, secure token storage, refresh token rotation — it's all solved problems. Tools like oauth-callback provide production-ready implementations that work across Node.js, Deno, and Bun.

For services supporting Dynamic Client Registration, you don't even need pre-registered credentials. Your CLI can register itself on the fly, eliminating the chicken-and-egg problem of distributing client secrets.

The Future Is Already Here

Major CLI tools are already making this shift. The GitHub CLI uses OAuth for authentication. Vercel's CLI leverages browser-based auth flows. Model Context Protocol servers are standardizing on OAuth for secure access to AI tools.

The ecosystem is ready. Every major platform supports OAuth. Libraries exist for every language. Browser automation is a solved problem. The only thing holding us back is inertia — the assumption that CLI tools must use API keys because that's how it's always been done.

Your users deserve better than managing a keychain of API credentials. They deserve authentication that's secure by default, that respects principle of least privilege, and that just works. OAuth delivers all of that, today.

Stop asking your users for API keys. Start using OAuth. Your users — and your security team — will thank you.

Ready to implement OAuth in your CLI tool? Check out oauth-callback, a lightweight library that handles the entire flow with just a few lines of code.

Major Update to React Starter Kit: Welcome Joy UI and Jotai!

Konstantin Tarkus — Sun, 03 Dec 2023 23:48:57 +0000

Hello, React developers!

I'm excited to share some big news about the React Starter Kit, the go-to template project for many of you in the React.js community. We're rolling out a major update that's set to enhance your development experience significantly.

What's New?

Switching from Material UI to Joy UI: We've made a strategic decision to replace Material UI with Joy UI. This change brings a fresh and modern UI toolkit that aligns better with the evolving design trends and offers more flexibility and customization options. Joy UI is designed to provide a seamless and enjoyable developer experience, ensuring that your projects look more appealing and user-friendly.

Transitioning from Recoil to Jotai for state management: To streamline state management, we're moving from Recoil to Jotai. Jotai offers a simpler and more intuitive API, with minimalistic and atomic state management. This shift aims to improve performance and make state management in your React applications more straightforward and maintainable.

Why These Changes?

We believe these updates will make the React Starter Kit more robust, versatile, and future-proof. Joy UI's modern approach to UI components, combined with Jotai's efficient state management, aligns with our mission to provide a high-quality, easy-to-use starter kit for your React projects.

Getting Started with the New Update

Just clone the repo, install project dependencies and launch:

$ git clone --depth=1 https://github.com/kriasoft/react-starter-kit example
$ cd ./example
$ corepack enable
$ yarn install
$ yarn workspace app start

Your Feedback Matters

Your feedback is crucial for the continuous improvement of the React Starter Kit. Please try out the new version and share your thoughts and experiences. If you encounter any issues or have suggestions, feel free to open an issue on GitHub or join our community chat on Discord.

We're excited to see the amazing applications you'll build with these new features!

Happy coding!
https://github.com/kriasoft/react-starter-kit