feat: support custom redirect URI for production OAuth

Production Intuit apps don't allow localhost redirect URIs. Add
--redirect-uri flag, QBO_REDIRECT_URI env var, and config field to
specify a public redirect URI. Non-localhost URIs use a manual flow
where the user pastes the callback URL after authorizing.

Author: voska

README.md

@@ -58,6 +58,29 @@ curl -LO https://github.com/voska/qbo-cli/releases/latest/download/qbo_linux_amd
 sudo dpkg -i qbo_linux_amd64.deb
 ```
 
+## Agent Skill
+
+Install as a [Claude Code skill](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/skills) for AI-assisted QuickBooks workflows:
+
+```bash
+npx skills add -g voska/qbo-cli
+```
+
+The skill includes setup guidance, usage patterns, troubleshooting, and a full command reference.
+
+## Getting Credentials
+
+You need an Intuit Developer account to get OAuth credentials.
+
+1. Sign up at [developer.intuit.com](https://developer.intuit.com) and create an app.
+2. Select **QuickBooks Online and Payments** as the platform.
+3. Under **Keys & credentials**, grab your **Client ID** and **Client Secret**.
+4. Add a **Redirect URI** — `http://localhost:8844/callback` for sandbox, or a public URI for production.
+
+See [Intuit's OAuth 2.0 guide](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/oauth-2.0) for the full walkthrough.
+
+> **Sandbox vs Production:** Development keys only work with sandbox companies. For production, complete Intuit's app assessment and use `--redirect-uri` (or `QBO_REDIRECT_URI`) with a public URI. You can use a tunnel, or any registered domain — after authorizing, paste the callback URL back into the CLI.
+
 ## Quick Start
 
 ```bash
@@ -84,29 +107,6 @@ qbo list invoices --where "Balance > '0'" --sandbox --json
 qbo report profit-and-loss --start-date 2025-01-01 --end-date 2025-12-31 --sandbox
 ```
 
-## Getting Credentials
-
-You need an Intuit Developer account to get OAuth credentials.
-
-1. Sign up at [developer.intuit.com](https://developer.intuit.com) and create an app.
-2. Select **QuickBooks Online and Payments** as the platform.
-3. Under **Keys & credentials**, grab your **Client ID** and **Client Secret**.
-4. Add `http://localhost:8844/callback` as a **Redirect URI**.
-
-See [Intuit's OAuth 2.0 guide](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/oauth-2.0) for the full walkthrough.
-
-> **Sandbox vs Production:** Development keys only work with sandbox companies. For production, you must complete Intuit's app assessment and use a public redirect URI (not localhost).
-
-## Agent Skill
-
-Install as a [Claude Code skill](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/skills) for AI-assisted QuickBooks workflows:
-
-```bash
-npx skills add -g voska/qbo-cli
-```
-
-The skill includes setup guidance, usage patterns, troubleshooting, and a full command reference.
-
 ## Output Modes
 
 | Flag | Description |

internal/auth/oauth.go

@@ -1,15 +1,18 @@
 package auth
 
 import (
+	"bufio"
 	"context"
 	"crypto/rand"
 	"encoding/hex"
 	"fmt"
 	"net"
 	"net/http"
+	"net/url"
 	"os"
 	"os/exec"
 	"runtime"
+	"strings"
 
 	"github.com/voska/qbo-cli/internal/errfmt"
 	"golang.org/x/oauth2"
@@ -52,13 +55,36 @@ func RefreshAccessToken(ctx context.Context, clientID, clientSecret string, toke
 
 const DefaultCallbackPort = 8844
 
-func LoginInteractive(ctx context.Context, clientID, clientSecret string) (*AuthResult, error) {
+func DefaultRedirectURI() string {
+	return fmt.Sprintf("http://localhost:%d/callback", DefaultCallbackPort)
+}
+
+func isLocalRedirect(redirectURL string) bool {
+	u, err := url.Parse(redirectURL)
+	if err != nil {
+		return false
+	}
+	host := u.Hostname()
+	return host == "localhost" || host == "127.0.0.1" || host == "::1"
+}
+
+func LoginInteractive(ctx context.Context, clientID, clientSecret, redirectURL string) (*AuthResult, error) {
+	if redirectURL == "" {
+		redirectURL = DefaultRedirectURI()
+	}
+
+	if isLocalRedirect(redirectURL) {
+		return loginLocal(ctx, clientID, clientSecret, redirectURL)
+	}
+	return loginManual(ctx, clientID, clientSecret, redirectURL)
+}
+
+func loginLocal(ctx context.Context, clientID, clientSecret, redirectURL string) (*AuthResult, error) {
 	addr := fmt.Sprintf("127.0.0.1:%d", DefaultCallbackPort)
 	listener, err := net.Listen("tcp", addr)
 	if err != nil {
 		return nil, errfmt.Wrap(errfmt.ExitError, fmt.Sprintf("cannot listen on port %d — is another qbo login running?", DefaultCallbackPort), err)
 	}
-	redirectURL := fmt.Sprintf("http://localhost:%d/callback", DefaultCallbackPort)
 
 	cfg := OAuthConfig(clientID, clientSecret, redirectURL)
 	state := GenerateState()
@@ -112,6 +138,47 @@ func LoginInteractive(ctx context.Context, clientID, clientSecret string) (*Auth
 	}
 }
 
+func loginManual(ctx context.Context, clientID, clientSecret, redirectURL string) (*AuthResult, error) {
+	cfg := OAuthConfig(clientID, clientSecret, redirectURL)
+	state := GenerateState()
+
+	authURL := cfg.AuthCodeURL(state, oauth2.AccessTypeOffline)
+	fmt.Fprintf(os.Stderr, "Open this URL in your browser:\n\n  %s\n\n", authURL)
+	fmt.Fprintf(os.Stderr, "After authorizing, paste the full callback URL here:\n")
+
+	scanner := bufio.NewScanner(os.Stdin)
+	if !scanner.Scan() {
+		return nil, errfmt.New(errfmt.ExitAuth, "no input received")
+	}
+	callbackURL := strings.TrimSpace(scanner.Text())
+	if callbackURL == "" {
+		return nil, errfmt.New(errfmt.ExitAuth, "empty callback URL")
+	}
+
+	u, err := url.Parse(callbackURL)
+	if err != nil {
+		return nil, errfmt.Wrap(errfmt.ExitAuth, "invalid callback URL", err)
+	}
+
+	q := u.Query()
+	if q.Get("state") != state {
+		return nil, errfmt.New(errfmt.ExitAuth, "state mismatch — possible CSRF attack or stale URL")
+	}
+
+	code := q.Get("code")
+	realmID := q.Get("realmId")
+	if code == "" || realmID == "" {
+		return nil, errfmt.New(errfmt.ExitAuth, "callback URL missing code or realmId parameters")
+	}
+
+	token, err := cfg.Exchange(ctx, code)
+	if err != nil {
+		return nil, errfmt.Wrap(errfmt.ExitAuth, "token exchange failed", err)
+	}
+
+	return &AuthResult{Token: token, RealmID: realmID}, nil
+}
+
 func openBrowser(url string) {
 	var cmd *exec.Cmd
 	switch runtime.GOOS {

internal/cmd/auth.go

@@ -1,7 +1,6 @@
 package cmd
 
 import (
-	"fmt"
 	"time"
 
 	"github.com/voska/qbo-cli/internal/auth"
@@ -18,7 +17,8 @@ type AuthCmd struct {
 }
 
 type AuthLoginCmd struct {
-	Manual bool `help:"Print URL for manual copy instead of opening browser."`
+	Manual      bool   `help:"Print URL for manual copy instead of opening browser."`
+	RedirectURI string `name:"redirect-uri" help:"OAuth redirect URI. Required for production (non-localhost). Set via flag, QBO_REDIRECT_URI, or config." env:"QBO_REDIRECT_URI"`
 }
 
 func (c *AuthLoginCmd) Run(g *Globals) error {
@@ -28,14 +28,21 @@ func (c *AuthLoginCmd) Run(g *Globals) error {
 		return errfmt.Config("set QBO_CLIENT_ID and QBO_CLIENT_SECRET before logging in")
 	}
 
+	redirectURI := c.RedirectURI
+	if redirectURI == "" {
+		redirectURI = g.Config.ResolveRedirectURI()
+	}
+	if redirectURI == "" {
+		redirectURI = auth.DefaultRedirectURI()
+	}
+
 	if g.CLI.DryRun {
-		redirectURL := fmt.Sprintf("http://localhost:%d/callback", auth.DefaultCallbackPort)
-		url := auth.GetAuthURL(clientID, clientSecret, redirectURL, "STATE")
+		url := auth.GetAuthURL(clientID, clientSecret, redirectURI, "STATE")
 		output.Hint("[dry-run] would open: %s", url)
 		return nil
 	}
 
-	result, err := auth.LoginInteractive(g.Ctx, clientID, clientSecret)
+	result, err := auth.LoginInteractive(g.Ctx, clientID, clientSecret, redirectURI)
 	if err != nil {
 		return err
 	}

internal/config/config.go

@@ -24,6 +24,7 @@ type Config struct {
 	Companies      []Company `json:"companies,omitempty"`
 	ClientID       string    `json:"client_id,omitempty"`
 	ClientSecret   string    `json:"client_secret,omitempty"`
+	RedirectURI    string    `json:"redirect_uri,omitempty"`
 }
 
 func Dir() (string, error) {
@@ -114,3 +115,10 @@ func (c *Config) ResolveClientSecret() string {
 	}
 	return c.ClientSecret
 }
+
+func (c *Config) ResolveRedirectURI() string {
+	if v := os.Getenv("QBO_REDIRECT_URI"); v != "" {
+		return v
+	}
+	return c.RedirectURI
+}

skills/qbo/SKILL.md

@@ -28,29 +28,43 @@ Requires an Intuit Developer account and a QuickBooks app for OAuth credentials.
 1. Sign up at https://developer.intuit.com and create an app from the dashboard.
 2. Select **QuickBooks Online and Payments** as the platform.
 3. Under **Keys & credentials**, find your **Client ID** and **Client Secret**.
-4. Add `http://localhost:8844/callback` as a **Redirect URI**.
+4. Add a **Redirect URI** (see below).
 
 See [Intuit's OAuth 2.0 guide](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/oauth-2.0) for the full walkthrough.
 
-**Sandbox vs Production:** Development keys only work with sandbox companies. For production access, complete Intuit's app assessment and use a public redirect URI (not localhost). Use a domain routed through a tunnel, or a non-resolving domain — when the redirect errors in the browser, copy the full callback URL and paste it into the terminal.
+### Redirect URI Options
+
+**Sandbox** allows `http://localhost:8844/callback` — just register it in the Intuit portal and `qbo auth login` handles everything automatically.
+
+**Production** does not allow localhost. Three options:
+
+1. **Tunnel/funnel address** — Route a domain (e.g. `https://auth.yourdomain.com`) back to your machine. Register it as the redirect URI. Use `--redirect-uri` or set `QBO_REDIRECT_URI`.
+2. **Login on the same machine** — If the agent runs on a machine with a browser, use a tunnel so localhost callbacks work.
+3. **Non-resolving domain** — Register any domain you own (e.g. `https://yourdomain.com`) as the redirect URI. After authorizing, the browser redirects there with `?code=...&realmId=...&state=...` in the URL. Copy the full URL from the browser and paste it back into `qbo auth login` (or provide it to the agent to exchange manually).
 
 ## Setup
 
 ```bash
 export QBO_CLIENT_ID=your_client_id
 export QBO_CLIENT_SECRET=your_client_secret
 
-# Authenticate (opens browser, listens on localhost:8844)
-qbo auth login
-
-# Or for sandbox
+# Sandbox — uses localhost callback automatically
 qbo auth login --sandbox
 
-# Or print the URL without opening a browser (useful for agents/remote)
+# Production — specify your redirect URI
+qbo auth login --redirect-uri https://yourdomain.com
+
+# Or set it as env var / config so you don't need the flag every time
+export QBO_REDIRECT_URI=https://yourdomain.com
+qbo auth login
+
+# Print the URL without opening a browser (useful for agents/remote)
 qbo auth login --manual
 ```
 
-Tokens are stored at `~/.config/qbo/tokens/`.
+For non-localhost redirect URIs, `qbo auth login` prints the auth URL and prompts you to paste the callback URL after authorizing.
+
+Tokens are stored in the system keychain (macOS Keychain, Windows Credential Manager) with file-based fallback at `~/.config/qbo/tokens/`.
 
 ### Verify
 

skills/qbo/references/COMMANDS.md

@@ -41,13 +41,13 @@ All QBO responses are wrapped. Use `--json` for parsing.
 ### auth
 
 ```bash
-qbo auth login [--manual]     # OAuth flow on localhost:8844
+qbo auth login [--manual] [--redirect-uri URI]  # OAuth flow
 qbo auth logout               # Remove stored credentials
 qbo auth status               # Show token status and company
 qbo auth refresh              # Force token refresh
 ```
 
-OAuth callback listens on `http://localhost:8844/callback`. Register this as your redirect URI in the Intuit developer portal. Tokens stored at `~/.config/qbo/tokens/`.
+For sandbox, the default `http://localhost:8844/callback` redirect works automatically. For production, pass `--redirect-uri` (or set `QBO_REDIRECT_URI`) to a registered public URI. Non-localhost URIs use a manual flow: paste the callback URL after authorizing in the browser.
 
 ### list