browser-go

browser is a small Go library that starts a request to open an HTTP or HTTPS URL in a browser.

A nil return means the launch request was submitted successfully to the operating system or a browser or launcher process started. The package does not wait for or verify browser navigation, and it does not collect browser or launcher output.

package main

import (
    "fmt"

    "github.com/credbind/browser-go"
)

func launchLogin() error {
    if err := browser.Open("https://example.com/login"); err != nil {
        return fmt.Errorf("open login page: %w", err)
    }
    return nil
}

Install it with:

go get github.com/credbind/browser-go

Try it

Run the included example with an HTTP or HTTPS URL:

go run ./example/open https://example.com

By default, the package uses the operating system's configured URL handler:

• macOS: open
• Windows: the native ShellExecuteW API
• Linux, BSDs, AIX, and Solaris: xdg-open, with gio open as a fallback
• WSL: the Windows default browser through PowerShell, with Linux launchers as a fallback

Optional browser override

No configuration is required. By default, Open uses the browser configured as the operating system default.

To explicitly use a different browser, set BROWSER to its executable name or full executable path:

BROWSER=firefox my-program
BROWSER=/usr/bin/google-chrome my-program

macOS

Point BROWSER at the executable inside the application bundle:

BROWSER="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" my-program

WSL

Use the browser's Windows executable through its /mnt/c path:

BROWSER='/mnt/c/Program Files (x86)/Microsoft/Edge/Application/msedge.exe' \
  go run ./example/open https://github.com/credbind/browser-go

Windows PowerShell

Set BROWSER in the PowerShell environment before running the example:

$env:BROWSER = "C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe"
go run .\example\open https://github.com/credbind/browser-go

The value is treated as one executable path, not as a shell command. The URL is passed as exactly one argument. To add browser flags, point BROWSER at a wrapper script. BROWSER and PATH are trusted process configuration; the URL is never interpreted as a shell command.

Only absolute http and https URLs with a host are accepted. Open returns validation and process-start errors to the caller and does not log or exit the calling program.

Print-only operation

Applications that explicitly select a manual browser flow can validate and print the URL without consulting BROWSER or starting any process:

if err := browser.Print(os.Stdout, authorizationURL); err != nil {
    return err
}

Print writes the exact validated URL followed by one newline. It returns writer errors and never silently falls back to launching a browser.

Scope and provenance

This package remains limited to validated HTTP(S) URL opening and explicit printing. It contains no OIDC, OAuth, CredBind token, provider, or SSH protocol behavior. See PROVENANCE.md for the preserved implementation history and LICENSE for the original MIT notice.