From 80da706f91d57396a4c01ac5dc53db0c8535a202 Mon Sep 17 00:00:00 2001
From: fayzan <fayzan@requesty.ai>
Date: Tue, 15 Sep 2026 13:17:52 +0100
Subject: [PATCH 1/9] Add OAuth to CLI

---
 cmd/login.go                    |  58 +++++++
 cmd/login_test.go               |  95 ++++++++++++
 cmd/requesty.go                 |   7 +
 internal/client/client.go       |   6 +-
 internal/config/config.go       |  15 ++
 internal/config/config_test.go  |  26 ++++
 internal/oauth/browser.go       |  31 ++++
 internal/oauth/callback.go      | 165 ++++++++++++++++++++
 internal/oauth/callback_test.go | 165 ++++++++++++++++++++
 internal/oauth/flow.go          | 207 +++++++++++++++++++++++++
 internal/oauth/flow_test.go     | 261 ++++++++++++++++++++++++++++++++
 internal/oauth/page.go          | 161 ++++++++++++++++++++
 internal/oauth/pkce.go          |  37 +++++
 internal/oauth/pkce_test.go     |  44 ++++++
 14 files changed, 1273 insertions(+), 5 deletions(-)
 create mode 100644 cmd/login.go
 create mode 100644 cmd/login_test.go
 create mode 100644 internal/config/config_test.go
 create mode 100644 internal/oauth/browser.go
 create mode 100644 internal/oauth/callback.go
 create mode 100644 internal/oauth/callback_test.go
 create mode 100644 internal/oauth/flow.go
 create mode 100644 internal/oauth/flow_test.go
 create mode 100644 internal/oauth/page.go
 create mode 100644 internal/oauth/pkce.go
 create mode 100644 internal/oauth/pkce_test.go

diff --git a/cmd/login.go b/cmd/login.go
new file mode 100644
index 0000000..d35bd70
--- /dev/null
+++ b/cmd/login.go
@@ -0,0 +1,58 @@
+package cmd
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/requestyai/cli/internal/oauth"
+	"github.com/spf13/cobra"
+)
+
+const (
+	loginPrintTokenFlag = "print-token"
+)
+
+func newLoginCommand(env environment) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "login",
+		Short: "Sign in to Requesty in your browser",
+		Long: "Sign in to Requesty in your browser.\n\n" +
+			"The CLI opens the Requesty consent page and, once you approve, receives a\n" +
+			"short-lived token on this machine. Nothing is written to disk.",
+		Args: cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			login := env.login
+			if login == nil {
+				login = oauth.Login
+			}
+
+			token, err := login(cmd.Context(), oauth.Options{
+				APIBaseURL: env.config.ResolveAPIBaseURL(),
+				Status:     cmd.ErrOrStderr(),
+			})
+			if err != nil {
+				return err
+			}
+
+			out := cmd.OutOrStdout()
+			if _, err := fmt.Fprintln(out, "Signed in to Requesty."); err != nil {
+				return err
+			}
+
+			fields := [][2]string{
+				{"Scopes", strings.Join(token.Scopes(), " ")},
+				{"Expires in", token.ExpiresIn.String()},
+			}
+			if printToken, _ := cmd.Flags().GetBool(loginPrintTokenFlag); printToken {
+				fields = append(fields, [2]string{"Access token", token.AccessToken})
+			}
+
+			return writeFields(out, fields)
+		},
+	}
+
+	cmd.Flags().Bool(loginPrintTokenFlag, false, "print the access token for manual testing")
+	_ = cmd.Flags().MarkHidden(loginPrintTokenFlag)
+
+	return cmd
+}
diff --git a/cmd/login_test.go b/cmd/login_test.go
new file mode 100644
index 0000000..09aaed4
--- /dev/null
+++ b/cmd/login_test.go
@@ -0,0 +1,95 @@
+package cmd
+
+import (
+	"bytes"
+	"context"
+	"errors"
+	"testing"
+	"time"
+
+	"github.com/requestyai/cli/internal/config"
+	"github.com/requestyai/cli/internal/oauth"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestLoginPrintsScopesAndExpiry(t *testing.T) {
+	var gotOptions oauth.Options
+	var output bytes.Buffer
+	command := newRootCommand(environment{
+		config: config.Config{APIBaseURL: "http://localhost:40003"},
+		login: func(_ context.Context, opts oauth.Options) (*oauth.Token, error) {
+			gotOptions = opts
+			return &oauth.Token{
+				AccessToken: "secret-token",
+				TokenType:   "Bearer",
+				Scope:       "manage:group:r manage:apikey:w",
+				ExpiresIn:   5 * time.Minute,
+			}, nil
+		},
+	})
+	command.SetOut(&output)
+	command.SetArgs([]string{"login"})
+
+	require.NoError(t, command.Execute())
+
+	assert.Equal(t, "http://localhost:40003", gotOptions.APIBaseURL)
+	assert.NotNil(t, gotOptions.Status)
+	assert.Equal(t,
+		"Signed in to Requesty.\n"+
+			"Scopes      manage:group:r manage:apikey:w\n"+
+			"Expires in  5m0s\n",
+		output.String())
+	assert.NotContains(t, output.String(), "secret-token")
+}
+
+func TestLoginDefaultsToProductionAPI(t *testing.T) {
+	var gotOptions oauth.Options
+	command := newRootCommand(environment{
+		login: func(_ context.Context, opts oauth.Options) (*oauth.Token, error) {
+			gotOptions = opts
+			return &oauth.Token{AccessToken: "t", ExpiresIn: time.Minute}, nil
+		},
+	})
+	command.SetOut(&bytes.Buffer{})
+	command.SetArgs([]string{"login"})
+
+	require.NoError(t, command.Execute())
+	assert.Equal(t, config.DefaultAPIBaseURL, gotOptions.APIBaseURL)
+}
+
+func TestLoginPrintTokenFlagRevealsToken(t *testing.T) {
+	var output bytes.Buffer
+	command := newRootCommand(environment{
+		login: func(context.Context, oauth.Options) (*oauth.Token, error) {
+			return &oauth.Token{AccessToken: "secret-token", Scope: "manage:group:r", ExpiresIn: time.Minute}, nil
+		},
+	})
+	command.SetOut(&output)
+	command.SetArgs([]string{"login", "--print-token"})
+
+	require.NoError(t, command.Execute())
+	assert.Contains(t, output.String(), "Access token  secret-token\n")
+}
+
+func TestLoginPrintTokenFlagIsHidden(t *testing.T) {
+	command := newRootCommand(environment{})
+
+	login, _, err := command.Find([]string{"login"})
+	require.NoError(t, err)
+
+	flag := login.Flags().Lookup(loginPrintTokenFlag)
+	require.NotNil(t, flag)
+	assert.True(t, flag.Hidden)
+}
+
+func TestLoginReportsFailure(t *testing.T) {
+	command := newRootCommand(environment{
+		login: func(context.Context, oauth.Options) (*oauth.Token, error) {
+			return nil, errors.New("sign-in was not completed: access_denied")
+		},
+	})
+	command.SetArgs([]string{"login"})
+
+	require.EqualError(t, command.Execute(), "sign-in was not completed: access_denied")
+}
diff --git a/cmd/requesty.go b/cmd/requesty.go
index 997dbb4..df8d524 100644
--- a/cmd/requesty.go
+++ b/cmd/requesty.go
@@ -1,11 +1,13 @@
 package cmd
 
 import (
+	"context"
 	"fmt"
 
 	tea "charm.land/bubbletea/v2"
 	"github.com/requestyai/cli/internal/client"
 	"github.com/requestyai/cli/internal/config"
+	"github.com/requestyai/cli/internal/oauth"
 	"github.com/requestyai/cli/internal/tui"
 	"github.com/spf13/cobra"
 )
@@ -25,6 +27,9 @@ func Run() error {
 type environment struct {
 	config      config.Config
 	apiv2Client *client.Client
+
+	// login runs the browser sign-in. nil means the real OAuth flow.
+	login func(context.Context, oauth.Options) (*oauth.Token, error)
 }
 
 func newEnvironment() (environment, error) {
@@ -36,6 +41,7 @@ func newEnvironment() (environment, error) {
 	return environment{
 		config:      cfg,
 		apiv2Client: client.New(cfg),
+		login:       oauth.Login,
 	}, nil
 }
 
@@ -59,6 +65,7 @@ func newRootCommand(env environment) *cobra.Command {
 	}
 
 	root.AddCommand(
+		newLoginCommand(env),
 		newAuthCommand(env),
 		newAPIKeysCommand(env),
 		newGroupsCommand(env),
diff --git a/internal/client/client.go b/internal/client/client.go
index 6bb8edb..ed35c38 100644
--- a/internal/client/client.go
+++ b/internal/client/client.go
@@ -31,11 +31,7 @@ func New(cfg config.Config) *Client {
 }
 
 func (c *Client) apiBaseURL() (string, error) {
-	if c.config.APIBaseURL != "" {
-		return c.config.APIBaseURL, nil
-	}
-
-	return strings.Replace(c.config.RouterBaseURL, "router", "api-v2", 1), nil
+	return c.config.ResolveAPIBaseURL(), nil
 }
 
 func (c *Client) authorize(req *http.Request) {
diff --git a/internal/config/config.go b/internal/config/config.go
index bf4c04d..d186ce1 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -7,6 +7,7 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"strings"
 )
 
 const (
@@ -24,6 +25,20 @@ type Config struct {
 	APIBaseURL    string `json:"api_base_url,omitempty"`
 }
 
+// ResolveAPIBaseURL returns the management API address: the configured one,
+// else the one implied by the router address, else the production default.
+// The fallback matters before onboarding, when the config file does not exist.
+func (c Config) ResolveAPIBaseURL() string {
+	if c.APIBaseURL != "" {
+		return c.APIBaseURL
+	}
+	if c.RouterBaseURL != "" {
+		return strings.Replace(c.RouterBaseURL, "router", "api-v2", 1)
+	}
+
+	return DefaultAPIBaseURL
+}
+
 // Load reads the settings. A missing file is not an error: it means the user
 // has not onboarded yet, so the zero Config comes back.
 func Load() (Config, error) {
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
new file mode 100644
index 0000000..0f8505d
--- /dev/null
+++ b/internal/config/config_test.go
@@ -0,0 +1,26 @@
+package config
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+)
+
+func TestResolveAPIBaseURL(t *testing.T) {
+	tests := []struct {
+		name   string
+		config Config
+		want   string
+	}{
+		{name: "explicit api base url wins", config: Config{APIBaseURL: "http://localhost:40003", RouterBaseURL: "https://router.requesty.ai"}, want: "http://localhost:40003"},
+		{name: "derived from router", config: Config{RouterBaseURL: "https://router.requesty.ai"}, want: "https://api-v2.requesty.ai"},
+		{name: "derived from staging router", config: Config{RouterBaseURL: "https://router.staging.requesty.ai"}, want: "https://api-v2.staging.requesty.ai"},
+		{name: "zero config uses production default", config: Config{}, want: DefaultAPIBaseURL},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			assert.Equal(t, tc.want, tc.config.ResolveAPIBaseURL())
+		})
+	}
+}
diff --git a/internal/oauth/browser.go b/internal/oauth/browser.go
new file mode 100644
index 0000000..7e5e9a6
--- /dev/null
+++ b/internal/oauth/browser.go
@@ -0,0 +1,31 @@
+package oauth
+
+import (
+	"fmt"
+	"os/exec"
+	"runtime"
+)
+
+// openBrowser asks the desktop to open url in the default browser. It returns
+// once the request has been handed off, without waiting for the browser to
+// exit, because some launchers block until the browser window closes.
+func openBrowser(url string) error {
+	var cmd *exec.Cmd
+	switch runtime.GOOS {
+	case "darwin":
+		cmd = exec.Command("open", url)
+	case "windows":
+		cmd = exec.Command("rundll32", "url.dll,FileProtocolHandler", url)
+	default:
+		cmd = exec.Command("xdg-open", url)
+	}
+
+	if err := cmd.Start(); err != nil {
+		return fmt.Errorf("failed to start browser: %w", err)
+	}
+
+	// Reap the launcher in the background so it does not linger as a zombie.
+	go func() { _ = cmd.Wait() }()
+
+	return nil
+}
diff --git a/internal/oauth/callback.go b/internal/oauth/callback.go
new file mode 100644
index 0000000..b42b878
--- /dev/null
+++ b/internal/oauth/callback.go
@@ -0,0 +1,165 @@
+package oauth
+
+import (
+	"context"
+	"crypto/subtle"
+	"errors"
+	"fmt"
+	"net"
+	"net/http"
+	"net/url"
+	"sync"
+	"time"
+)
+
+const (
+	callbackPath = "/callback"
+
+	// loginTimeout bounds how long the CLI waits for the user to finish in the
+	// browser before giving up.
+	loginTimeout = 5 * time.Minute
+
+	// shutdownTimeout bounds how long Close waits for the browser's connection
+	// to drain before dropping it.
+	shutdownTimeout = 2 * time.Second
+)
+
+// Error is a failure the authorization server reported, either on the redirect
+// back to the CLI or from the token endpoint.
+type Error struct {
+	Code        string
+	Description string
+}
+
+func (e *Error) Error() string {
+	if e.Description == "" {
+		return e.Code
+	}
+
+	return fmt.Sprintf("%s: %s", e.Code, e.Description)
+}
+
+type callbackResult struct {
+	code string
+	err  error
+}
+
+// callbackServer is the loopback HTTP server the browser lands on once the
+// user has approved or denied the request. It accepts exactly one outcome.
+type callbackServer struct {
+	listener net.Listener
+	server   *http.Server
+	state    string
+	results  chan callbackResult
+	once     sync.Once
+}
+
+// listenCallback starts serving on a free port of the IPv4 loopback interface.
+// The redirect URI must use the 127.0.0.1 literal, not localhost, so that is
+// what we bind to.
+func listenCallback(state string) (*callbackServer, error) {
+	listener, err := net.Listen("tcp", "127.0.0.1:0")
+	if err != nil {
+		return nil, fmt.Errorf("failed to listen for the browser callback: %w", err)
+	}
+
+	server := &callbackServer{
+		listener: listener,
+		state:    state,
+		results:  make(chan callbackResult, 1),
+	}
+
+	mux := http.NewServeMux()
+	mux.HandleFunc("GET "+callbackPath, server.handle)
+	server.server = &http.Server{
+		Handler:           mux,
+		ReadHeaderTimeout: 10 * time.Second,
+	}
+
+	go func() {
+		// Serve always returns a non-nil error; after Shutdown it is
+		// ErrServerClosed, which is the expected way to stop.
+		_ = server.server.Serve(listener)
+	}()
+
+	return server, nil
+}
+
+// RedirectURI is the address the authorization server sends the browser back
+// to. The exact same string must be presented at the token endpoint.
+func (s *callbackServer) RedirectURI() string {
+	return "http://" + s.listener.Addr().String() + callbackPath
+}
+
+// Wait blocks until the browser delivers an outcome, the context ends, or the
+// login timeout passes.
+func (s *callbackServer) Wait(ctx context.Context) (string, error) {
+	ctx, cancel := context.WithTimeout(ctx, loginTimeout)
+	defer cancel()
+
+	select {
+	case result := <-s.results:
+		return result.code, result.err
+	case <-ctx.Done():
+		if errors.Is(ctx.Err(), context.DeadlineExceeded) {
+			return "", fmt.Errorf("timed out waiting for the browser sign-in: %w", ctx.Err())
+		}
+
+		return "", ctx.Err()
+	}
+}
+
+// Close stops the server, giving the browser a moment to read its response.
+func (s *callbackServer) Close() {
+	ctx, cancel := context.WithTimeout(context.Background(), shutdownTimeout)
+	defer cancel()
+
+	if err := s.server.Shutdown(ctx); err != nil {
+		_ = s.server.Close()
+	}
+}
+
+func (s *callbackServer) handle(w http.ResponseWriter, r *http.Request) {
+	result := s.resolve(r.URL.Query())
+
+	w.Header().Set("Content-Type", "text/html; charset=utf-8")
+	w.Header().Set("Cache-Control", "no-store")
+
+	if result.err != nil {
+		w.WriteHeader(http.StatusBadRequest)
+		writePage(w, callbackPage{
+			Title:   "Sign-in failed",
+			Message: "Could not sign in to Requesty CLI: " + result.err.Error() + ".",
+			Hint:    "You can close this tab and return to the terminal.",
+		})
+	} else {
+		writePage(w, callbackPage{
+			Success: true,
+			Title:   "Signed in",
+			Message: "You're signed in to Requesty CLI. You can close this tab.",
+			Hint:    "Return to the terminal to continue.",
+		})
+	}
+
+	s.once.Do(func() { s.results <- result })
+}
+
+// resolve turns the authorization response into a code or an error. The state
+// check comes first so that a response meant for another attempt, or forged
+// by a page that guessed the port, is never acted on.
+func (s *callbackServer) resolve(query url.Values) callbackResult {
+	if subtle.ConstantTimeCompare([]byte(query.Get("state")), []byte(s.state)) != 1 {
+		return callbackResult{err: errors.New("state mismatch: the response did not belong to this sign-in attempt")}
+	}
+
+	if code := query.Get("error"); code != "" {
+		return callbackResult{err: &Error{Code: code, Description: query.Get("error_description")}}
+	}
+
+	code := query.Get("code")
+	if code == "" {
+		return callbackResult{err: errors.New("authorization response has no code")}
+	}
+
+	return callbackResult{code: code}
+}
diff --git a/internal/oauth/callback_test.go b/internal/oauth/callback_test.go
new file mode 100644
index 0000000..8ae3c61
--- /dev/null
+++ b/internal/oauth/callback_test.go
@@ -0,0 +1,165 @@
+package oauth
+
+import (
+	"context"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// visit plays the browser: it follows the redirect the authorization server
+// would have issued and returns what the callback page said.
+func visit(t *testing.T, server *callbackServer, query url.Values) (int, string) {
+	t.Helper()
+
+	resp, err := http.Get(server.RedirectURI() + "?" + query.Encode())
+	require.NoError(t, err)
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(resp.Body)
+	require.NoError(t, err)
+
+	return resp.StatusCode, string(body)
+}
+
+func TestCallbackRedirectURIUsesLoopbackIPLiteral(t *testing.T) {
+	server, err := listenCallback("state")
+	require.NoError(t, err)
+	defer server.Close()
+
+	redirect, err := url.Parse(server.RedirectURI())
+	require.NoError(t, err)
+
+	assert.Equal(t, "http", redirect.Scheme)
+	assert.Equal(t, "127.0.0.1", redirect.Hostname())
+	assert.NotEmpty(t, redirect.Port())
+	assert.Equal(t, "/callback", redirect.Path)
+}
+
+func TestCallbackDeliversCode(t *testing.T) {
+	server, err := listenCallback("expected-state")
+	require.NoError(t, err)
+	defer server.Close()
+
+	status, body := visit(t, server, url.Values{
+		"code":  {"the-code"},
+		"state": {"expected-state"},
+		"iss":   {"https://api-v2.requesty.ai"},
+	})
+	assert.Equal(t, http.StatusOK, status)
+	assert.Contains(t, body, "You&#39;re signed in to Requesty CLI. You can close this tab.")
+
+	code, err := server.Wait(context.Background())
+	require.NoError(t, err)
+	assert.Equal(t, "the-code", code)
+}
+
+func TestCallbackRejectsStateMismatch(t *testing.T) {
+	server, err := listenCallback("expected-state")
+	require.NoError(t, err)
+	defer server.Close()
+
+	status, body := visit(t, server, url.Values{
+		"code":  {"the-code"},
+		"state": {"forged-state"},
+	})
+	assert.Equal(t, http.StatusBadRequest, status)
+	assert.Contains(t, body, "state mismatch")
+
+	code, err := server.Wait(context.Background())
+	require.ErrorContains(t, err, "state mismatch")
+	assert.Empty(t, code)
+}
+
+func TestCallbackSurfacesErrorParameters(t *testing.T) {
+	server, err := listenCallback("expected-state")
+	require.NoError(t, err)
+	defer server.Close()
+
+	status, body := visit(t, server, url.Values{
+		"error":             {"access_denied"},
+		"error_description": {"the user denied the request"},
+		"state":             {"expected-state"},
+	})
+	assert.Equal(t, http.StatusBadRequest, status)
+	assert.Contains(t, body, "access_denied: the user denied the request")
+
+	_, err = server.Wait(context.Background())
+	var oauthErr *Error
+	require.ErrorAs(t, err, &oauthErr)
+	assert.Equal(t, "access_denied", oauthErr.Code)
+	assert.Equal(t, "the user denied the request", oauthErr.Description)
+}
+
+func TestCallbackRejectsResponseWithoutCode(t *testing.T) {
+	server, err := listenCallback("expected-state")
+	require.NoError(t, err)
+	defer server.Close()
+
+	visit(t, server, url.Values{"state": {"expected-state"}})
+
+	_, err = server.Wait(context.Background())
+	require.ErrorContains(t, err, "no code")
+}
+
+func TestCallbackEscapesHTMLInErrors(t *testing.T) {
+	server, err := listenCallback("expected-state")
+	require.NoError(t, err)
+	defer server.Close()
+
+	_, body := visit(t, server, url.Values{
+		"error":             {"access_denied"},
+		"error_description": {"<script>alert(1)</script>"},
+		"state":             {"expected-state"},
+	})
+
+	assert.False(t, strings.Contains(body, "<script>"), "error description must be escaped: %s", body)
+	assert.Contains(t, body, "&lt;script&gt;")
+}
+
+func TestCallbackKeepsFirstOutcome(t *testing.T) {
+	server, err := listenCallback("expected-state")
+	require.NoError(t, err)
+	defer server.Close()
+
+	visit(t, server, url.Values{"code": {"first"}, "state": {"expected-state"}})
+	visit(t, server, url.Values{"code": {"second"}, "state": {"expected-state"}})
+
+	code, err := server.Wait(context.Background())
+	require.NoError(t, err)
+	assert.Equal(t, "first", code)
+}
+
+func TestCallbackIgnoresOtherPaths(t *testing.T) {
+	server, err := listenCallback("expected-state")
+	require.NoError(t, err)
+	defer server.Close()
+
+	resp, err := http.Get(strings.TrimSuffix(server.RedirectURI(), callbackPath) + "/favicon.ico")
+	require.NoError(t, err)
+	resp.Body.Close()
+	assert.Equal(t, http.StatusNotFound, resp.StatusCode)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 50*time.Millisecond)
+	defer cancel()
+	_, err = server.Wait(ctx)
+	require.ErrorIs(t, err, context.DeadlineExceeded)
+}
+
+func TestCallbackWaitStopsWhenContextIsCancelled(t *testing.T) {
+	server, err := listenCallback("expected-state")
+	require.NoError(t, err)
+	defer server.Close()
+
+	ctx, cancel := context.WithCancel(context.Background())
+	cancel()
+
+	_, err = server.Wait(ctx)
+	require.ErrorIs(t, err, context.Canceled)
+}
diff --git a/internal/oauth/flow.go b/internal/oauth/flow.go
new file mode 100644
index 0000000..bca5ead
--- /dev/null
+++ b/internal/oauth/flow.go
@@ -0,0 +1,207 @@
+package oauth
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"os"
+	"strings"
+	"time"
+)
+
+const (
+	// ClientID identifies the CLI to the authorization server. It is a public
+	// client: there is no secret, and PKCE binds the code to this process.
+	ClientID = "requesty-cli"
+
+	// Scope is everything the CLI asks for: enough to list groups and create
+	// an API key in one of them.
+	Scope = "manage:group:r manage:apikey:w"
+
+	authorizePath = "/v1/oauth/authorize"
+	tokenPath     = "/v1/oauth/token"
+	resourcePath  = "/v1/manage"
+)
+
+// Token is a short-lived credential for the management API. The refresh token
+// the server also returns is deliberately dropped: the CLI provisions an API
+// key within the access token's lifetime and never needs to renew it.
+type Token struct {
+	AccessToken string
+	TokenType   string
+	Scope       string
+	ExpiresIn   time.Duration
+}
+
+// Scopes splits the granted scope into its individual permissions.
+func (t *Token) Scopes() []string {
+	return strings.Fields(t.Scope)
+}
+
+// Options configures Login. Only APIBaseURL is required; the rest exist so
+// tests can stand in for the browser, the terminal, and the network.
+type Options struct {
+	// APIBaseURL is the management API address, for example
+	// https://api-v2.requesty.ai, which also hosts the authorization server.
+	APIBaseURL string
+
+	// Status receives progress messages, including the URL to visit for users
+	// whose browser cannot be opened from the terminal. Defaults to stderr.
+	Status io.Writer
+
+	// OpenBrowser opens url in the user's browser. Defaults to the platform
+	// launcher. A failure is reported on Status but does not abort the login.
+	OpenBrowser func(url string) error
+
+	// HTTPClient sends the token request. Defaults to one with a timeout.
+	HTTPClient *http.Client
+}
+
+// Login runs the authorization code flow end to end: it starts a loopback
+// listener, sends the user to the consent page, waits for the redirect, and
+// exchanges the code for a token.
+func Login(ctx context.Context, opts Options) (*Token, error) {
+	apiBaseURL := strings.TrimRight(opts.APIBaseURL, "/")
+	if apiBaseURL == "" {
+		return nil, errors.New("api base url is required")
+	}
+
+	status := opts.Status
+	if status == nil {
+		status = os.Stderr
+	}
+	open := opts.OpenBrowser
+	if open == nil {
+		open = openBrowser
+	}
+	httpClient := opts.HTTPClient
+	if httpClient == nil {
+		httpClient = &http.Client{Timeout: 30 * time.Second}
+	}
+
+	verifier, err := NewVerifier()
+	if err != nil {
+		return nil, err
+	}
+	state, err := NewState()
+	if err != nil {
+		return nil, err
+	}
+
+	server, err := listenCallback(state)
+	if err != nil {
+		return nil, err
+	}
+	defer server.Close()
+
+	redirectURI := server.RedirectURI()
+	authorizeURL := authorizeURL(apiBaseURL, redirectURI, state, Challenge(verifier))
+
+	_, _ = fmt.Fprintf(status,
+		"Opening your browser to sign in to Requesty.\n\nIf it does not open, visit this address:\n\n  %s\n\n",
+		authorizeURL)
+	if err := open(authorizeURL); err != nil {
+		_, _ = fmt.Fprintf(status, "Could not open a browser (%v); paste the address above into one.\n\n", err)
+	}
+	_, _ = fmt.Fprintln(status, "Waiting for you to finish signing in...")
+
+	code, err := server.Wait(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("sign-in was not completed: %w", err)
+	}
+
+	return exchangeCode(ctx, httpClient, apiBaseURL, code, redirectURI, verifier)
+}
+
+// authorizeURL builds the address the browser visits to start the flow.
+func authorizeURL(apiBaseURL, redirectURI, state, challenge string) string {
+	query := url.Values{
+		"response_type":         {"code"},
+		"client_id":             {ClientID},
+		"redirect_uri":          {redirectURI},
+		"scope":                 {Scope},
+		"resource":              {apiBaseURL + resourcePath},
+		"state":                 {state},
+		"code_challenge":        {challenge},
+		"code_challenge_method": {"S256"},
+	}
+
+	return apiBaseURL + authorizePath + "?" + query.Encode()
+}
+
+// exchangeCode redeems an authorization code at the token endpoint. The
+// request is form-encoded, as the OAuth token endpoint requires, and the
+// redirect URI must be byte-for-byte what the authorize request carried.
+func exchangeCode(ctx context.Context, httpClient *http.Client, apiBaseURL, code, redirectURI, verifier string) (*Token, error) {
+	form := url.Values{
+		"grant_type":    {"authorization_code"},
+		"code":          {code},
+		"redirect_uri":  {redirectURI},
+		"client_id":     {ClientID},
+		"code_verifier": {verifier},
+	}
+
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, apiBaseURL+tokenPath, strings.NewReader(form.Encode()))
+	if err != nil {
+		return nil, fmt.Errorf("failed to create token request: %w", err)
+	}
+	req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
+	req.Header.Set("Accept", "application/json")
+
+	resp, err := httpClient.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("failed to request token: %w", err)
+	}
+	defer resp.Body.Close()
+
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 1<<20))
+	if err != nil {
+		return nil, fmt.Errorf("failed to read token response: %w", err)
+	}
+
+	if resp.StatusCode != http.StatusOK {
+		return nil, tokenError(resp.StatusCode, body)
+	}
+
+	var payload struct {
+		AccessToken string `json:"access_token"`
+		TokenType   string `json:"token_type"`
+		ExpiresIn   int64  `json:"expires_in"`
+		Scope       string `json:"scope"`
+	}
+	if err := json.Unmarshal(body, &payload); err != nil {
+		return nil, fmt.Errorf("failed to decode token response: %w", err)
+	}
+	if payload.AccessToken == "" {
+		return nil, errors.New("token response has no access_token")
+	}
+	if !strings.EqualFold(payload.TokenType, "Bearer") {
+		return nil, fmt.Errorf("token response has unsupported token_type %q", payload.TokenType)
+	}
+
+	return &Token{
+		AccessToken: payload.AccessToken,
+		TokenType:   payload.TokenType,
+		Scope:       payload.Scope,
+		ExpiresIn:   time.Duration(payload.ExpiresIn) * time.Second,
+	}, nil
+}
+
+// tokenError describes a rejected token request, preferring the server's
+// error and error_description over the bare status code.
+func tokenError(statusCode int, body []byte) error {
+	var payload struct {
+		Error       string `json:"error"`
+		Description string `json:"error_description"`
+	}
+
+	if err := json.Unmarshal(body, &payload); err == nil && payload.Error != "" {
+		return fmt.Errorf("token exchange failed: %w", &Error{Code: payload.Error, Description: payload.Description})
+	}
+
+	return fmt.Errorf("token exchange failed: status code not ok: %d", statusCode)
+}
diff --git a/internal/oauth/flow_test.go b/internal/oauth/flow_test.go
new file mode 100644
index 0000000..96ae88a
--- /dev/null
+++ b/internal/oauth/flow_test.go
@@ -0,0 +1,261 @@
+package oauth
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"net/url"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// fakeBrowser stands in for the user's browser: it fetches the authorize URL
+// and follows the redirect back to the CLI's loopback server.
+func fakeBrowser(t *testing.T) func(string) error {
+	return func(address string) error {
+		go func() {
+			resp, err := http.Get(address)
+			if err != nil {
+				t.Errorf("browser failed: %v", err)
+				return
+			}
+			resp.Body.Close()
+		}()
+
+		return nil
+	}
+}
+
+// authServer is a minimal authorization server. It records what the CLI sent
+// so tests can assert the wire contract.
+type authServer struct {
+	t         *testing.T
+	authorize url.Values
+	tokenForm url.Values
+	tokenReq  *http.Request
+
+	// consent decides how the browser is redirected back. nil approves.
+	consent func(redirect *url.URL, authorize url.Values)
+	// token writes the token response. nil issues a normal token.
+	token func(w http.ResponseWriter)
+}
+
+func (s *authServer) handler() http.Handler {
+	mux := http.NewServeMux()
+
+	mux.HandleFunc("GET /v1/oauth/authorize", func(w http.ResponseWriter, r *http.Request) {
+		s.authorize = r.URL.Query()
+
+		redirect, err := url.Parse(s.authorize.Get("redirect_uri"))
+		require.NoError(s.t, err)
+
+		if s.consent != nil {
+			s.consent(redirect, s.authorize)
+		} else {
+			query := redirect.Query()
+			query.Set("code", "issued-code")
+			query.Set("state", s.authorize.Get("state"))
+			query.Set("iss", "http://"+r.Host)
+			redirect.RawQuery = query.Encode()
+		}
+
+		http.Redirect(w, r, redirect.String(), http.StatusFound)
+	})
+
+	mux.HandleFunc("POST /v1/oauth/token", func(w http.ResponseWriter, r *http.Request) {
+		s.tokenReq = r
+		require.NoError(s.t, r.ParseForm())
+		s.tokenForm = r.PostForm
+
+		w.Header().Set("Content-Type", "application/json")
+		if s.token != nil {
+			s.token(w)
+			return
+		}
+
+		_ = json.NewEncoder(w).Encode(map[string]any{
+			"access_token":  "access-token",
+			"token_type":    "Bearer",
+			"expires_in":    300,
+			"refresh_token": "refresh-token",
+			"scope":         Scope,
+		})
+	})
+
+	return mux
+}
+
+func TestLoginCompletesAuthorizationCodeFlow(t *testing.T) {
+	auth := &authServer{t: t}
+	server := httptest.NewServer(auth.handler())
+	defer server.Close()
+
+	var status bytes.Buffer
+	token, err := Login(context.Background(), Options{
+		APIBaseURL:  server.URL + "/",
+		Status:      &status,
+		OpenBrowser: fakeBrowser(t),
+	})
+	require.NoError(t, err)
+
+	assert.Equal(t, "access-token", token.AccessToken)
+	assert.Equal(t, "Bearer", token.TokenType)
+	assert.Equal(t, 5*time.Minute, token.ExpiresIn)
+	assert.Equal(t, []string{"manage:group:r", "manage:apikey:w"}, token.Scopes())
+
+	// The authorize request carries the full OAuth 2.1 + PKCE + RFC 8707 set.
+	assert.Equal(t, "code", auth.authorize.Get("response_type"))
+	assert.Equal(t, "requesty-cli", auth.authorize.Get("client_id"))
+	assert.Equal(t, "manage:group:r manage:apikey:w", auth.authorize.Get("scope"))
+	assert.Equal(t, server.URL+"/v1/manage", auth.authorize.Get("resource"))
+	assert.Equal(t, "S256", auth.authorize.Get("code_challenge_method"))
+	assert.NotEmpty(t, auth.authorize.Get("state"))
+	assert.NotEmpty(t, auth.authorize.Get("code_challenge"))
+
+	redirectURI := auth.authorize.Get("redirect_uri")
+	assert.True(t, strings.HasPrefix(redirectURI, "http://127.0.0.1:"), redirectURI)
+	assert.True(t, strings.HasSuffix(redirectURI, "/callback"), redirectURI)
+
+	// The token request is form-encoded with exactly the fields the backend
+	// binds, and the redirect URI matches the authorize request verbatim.
+	assert.Equal(t, "application/x-www-form-urlencoded", auth.tokenReq.Header.Get("Content-Type"))
+	assert.Empty(t, auth.tokenReq.Header.Get("Authorization"), "public client must not send credentials")
+	assert.Equal(t, url.Values{
+		"grant_type":    {"authorization_code"},
+		"code":          {"issued-code"},
+		"redirect_uri":  {redirectURI},
+		"client_id":     {"requesty-cli"},
+		"code_verifier": {auth.tokenForm.Get("code_verifier")},
+	}, auth.tokenForm)
+
+	// The verifier the CLI redeemed is the one behind the challenge it sent.
+	assert.Equal(t, auth.authorize.Get("code_challenge"), Challenge(auth.tokenForm.Get("code_verifier")))
+
+	// The URL is always printed so headless users can paste it.
+	assert.Contains(t, status.String(), server.URL+"/v1/oauth/authorize?")
+}
+
+func TestLoginReportsDeniedConsent(t *testing.T) {
+	auth := &authServer{t: t}
+	auth.consent = func(redirect *url.URL, authorize url.Values) {
+		query := redirect.Query()
+		query.Set("error", "access_denied")
+		query.Set("error_description", "the user denied the request")
+		query.Set("state", authorize.Get("state"))
+		redirect.RawQuery = query.Encode()
+	}
+	server := httptest.NewServer(auth.handler())
+	defer server.Close()
+
+	_, err := Login(context.Background(), Options{
+		APIBaseURL:  server.URL,
+		Status:      &bytes.Buffer{},
+		OpenBrowser: fakeBrowser(t),
+	})
+
+	var oauthErr *Error
+	require.ErrorAs(t, err, &oauthErr)
+	assert.Equal(t, "access_denied", oauthErr.Code)
+	assert.Nil(t, auth.tokenReq, "no token request should be made after a denial")
+}
+
+func TestLoginRejectsStateMismatchFromServer(t *testing.T) {
+	auth := &authServer{t: t}
+	auth.consent = func(redirect *url.URL, _ url.Values) {
+		query := redirect.Query()
+		query.Set("code", "issued-code")
+		query.Set("state", "not-the-state-we-sent")
+		redirect.RawQuery = query.Encode()
+	}
+	server := httptest.NewServer(auth.handler())
+	defer server.Close()
+
+	_, err := Login(context.Background(), Options{
+		APIBaseURL:  server.URL,
+		Status:      &bytes.Buffer{},
+		OpenBrowser: fakeBrowser(t),
+	})
+
+	require.ErrorContains(t, err, "state mismatch")
+	assert.Nil(t, auth.tokenReq)
+}
+
+func TestLoginSurfacesTokenEndpointError(t *testing.T) {
+	auth := &authServer{t: t}
+	auth.token = func(w http.ResponseWriter) {
+		w.WriteHeader(http.StatusBadRequest)
+		_ = json.NewEncoder(w).Encode(map[string]string{
+			"error":             "invalid_grant",
+			"error_description": "PKCE verification failed",
+		})
+	}
+	server := httptest.NewServer(auth.handler())
+	defer server.Close()
+
+	_, err := Login(context.Background(), Options{
+		APIBaseURL:  server.URL,
+		Status:      &bytes.Buffer{},
+		OpenBrowser: fakeBrowser(t),
+	})
+
+	require.EqualError(t, err, "token exchange failed: invalid_grant: PKCE verification failed")
+	var oauthErr *Error
+	require.ErrorAs(t, err, &oauthErr)
+	assert.Equal(t, "invalid_grant", oauthErr.Code)
+}
+
+func TestLoginContinuesWhenBrowserCannotOpen(t *testing.T) {
+	auth := &authServer{t: t}
+	server := httptest.NewServer(auth.handler())
+	defer server.Close()
+
+	var status bytes.Buffer
+	browser := fakeBrowser(t)
+	token, err := Login(context.Background(), Options{
+		APIBaseURL: server.URL,
+		Status:     &status,
+		OpenBrowser: func(address string) error {
+			_ = browser(address)
+			return assert.AnError
+		},
+	})
+
+	require.NoError(t, err)
+	assert.Equal(t, "access-token", token.AccessToken)
+	assert.Contains(t, status.String(), "Could not open a browser")
+}
+
+func TestLoginRequiresAPIBaseURL(t *testing.T) {
+	_, err := Login(context.Background(), Options{})
+
+	require.EqualError(t, err, "api base url is required")
+}
+
+func TestExchangeCodeRejectsNonBearerToken(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		_ = json.NewEncoder(w).Encode(map[string]any{"access_token": "x", "token_type": "MAC"})
+	}))
+	defer server.Close()
+
+	_, err := exchangeCode(context.Background(), server.Client(), server.URL, "code", "http://127.0.0.1:1/callback", "verifier")
+
+	require.ErrorContains(t, err, `unsupported token_type "MAC"`)
+}
+
+func TestExchangeCodeFallsBackToStatusCode(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+		_, _ = w.Write([]byte("upstream exploded"))
+	}))
+	defer server.Close()
+
+	_, err := exchangeCode(context.Background(), server.Client(), server.URL, "code", "http://127.0.0.1:1/callback", "verifier")
+
+	require.EqualError(t, err, "token exchange failed: status code not ok: 500")
+}
diff --git a/internal/oauth/page.go b/internal/oauth/page.go
new file mode 100644
index 0000000..1aed1ff
--- /dev/null
+++ b/internal/oauth/page.go
@@ -0,0 +1,161 @@
+package oauth
+
+import (
+	"html/template"
+	"net/http"
+)
+
+// callbackPage is what the browser shows once the redirect has landed. It
+// mirrors the dashboard's consent card so the hand-off feels like one flow.
+type callbackPage struct {
+	Success bool
+	Title   string
+	Message string
+	Hint    string
+}
+
+func writePage(w http.ResponseWriter, page callbackPage) {
+	_ = pageTemplate.Execute(w, page)
+}
+
+// pageTemplate is self-contained: no scripts, fonts, or images are fetched, so
+// it renders the same offline and never leaks the callback URL to a third
+// party. Colours follow the dashboard's Tailwind palette in both schemes.
+var pageTemplate = template.Must(template.New("callback").Parse(`<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{{.Title}} · Requesty CLI</title>
+<style>
+  :root {
+    --page: #ffffff;
+    --card: #ffffff;
+    --border: #e5e7eb;
+    --fg: #111827;
+    --muted: #6b7280;
+    --tile-blue-bg: #dbeafe;
+    --tile-blue-fg: #2563eb;
+    --tile-gray-bg: #f3f4f6;
+    --tile-gray-fg: #4b5563;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --page: #0a0d14;
+      --card: #111827;
+      --border: #1f2937;
+      --fg: #f9fafb;
+      --muted: #9ca3af;
+      --tile-blue-bg: #1e3a8a;
+      --tile-blue-fg: #60a5fa;
+      --tile-gray-bg: #1f2937;
+      --tile-gray-fg: #9ca3af;
+    }
+  }
+  * { box-sizing: border-box; }
+  html, body { height: 100%; margin: 0; }
+  body {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: var(--page);
+    color: var(--fg);
+    font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+    -webkit-font-smoothing: antialiased;
+  }
+  .card {
+    width: 500px;
+    max-width: calc(100% - 2rem);
+    background: var(--card);
+    border: 2px solid var(--border);
+    border-radius: 0.75rem;
+    box-shadow: 0 20px 25px -5px rgb(0 0 0 / 0.1), 0 8px 10px -6px rgb(0 0 0 / 0.1);
+    overflow: hidden;
+  }
+  .header {
+    padding: 1.5rem;
+    text-align: center;
+    border-bottom: 1px solid var(--border);
+  }
+  .tiles {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: 1rem;
+  }
+  .tile {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 3rem;
+    height: 3rem;
+    border-radius: 0.5rem;
+    font-size: 1.25rem;
+    font-weight: 700;
+  }
+  .tile.blue { background: var(--tile-blue-bg); color: var(--tile-blue-fg); }
+  .tile.gray { background: var(--tile-gray-bg); color: var(--tile-gray-fg); }
+  .link {
+    position: relative;
+    width: 3rem;
+    height: 2px;
+    background: var(--border);
+  }
+  .dot {
+    position: absolute;
+    top: 50%;
+    left: 50%;
+    transform: translate(-50%, -50%);
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 1.25rem;
+    height: 1.25rem;
+    border-radius: 9999px;
+    color: #ffffff;
+    font-size: 9px;
+    font-weight: 500;
+    line-height: 1;
+  }
+  .dot.ok { background: #2da44e; }
+  .dot.bad { background: #dc2626; }
+  h1 {
+    margin: 1rem 0 0;
+    font-size: 1.25rem;
+    font-weight: 600;
+  }
+  .body {
+    padding: 1.5rem;
+    text-align: center;
+  }
+  .message {
+    margin: 0;
+    font-size: 0.875rem;
+    line-height: 1.5;
+    overflow-wrap: anywhere;
+  }
+  .hint {
+    margin: 1rem 0 0;
+    font-size: 0.75rem;
+    color: var(--muted);
+  }
+</style>
+</head>
+<body>
+  <main class="card" role="status">
+    <div class="header">
+      <div class="tiles">
+        <div class="tile blue">R</div>
+        <div class="link"><div class="dot {{if .Success}}ok{{else}}bad{{end}}">{{if .Success}}✓{{else}}✕{{end}}</div></div>
+        <div class="tile gray">R</div>
+      </div>
+      <h1>{{.Title}}</h1>
+    </div>
+    <div class="body">
+      <p class="message">{{.Message}}</p>
+      <p class="hint">{{.Hint}}</p>
+    </div>
+  </main>
+</body>
+</html>
+`))
diff --git a/internal/oauth/pkce.go b/internal/oauth/pkce.go
new file mode 100644
index 0000000..cb6b79e
--- /dev/null
+++ b/internal/oauth/pkce.go
@@ -0,0 +1,37 @@
+// Package oauth signs the user in to Requesty with the OAuth 2.1 authorization
+// code flow: PKCE, a loopback redirect, and a form-encoded token exchange.
+package oauth
+
+import (
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/base64"
+	"fmt"
+)
+
+// NewVerifier returns a fresh PKCE code verifier: 32 random bytes encoded as
+// 43 unpadded base64url characters (RFC 7636 Section 4.1).
+func NewVerifier() (string, error) {
+	return randomToken(32)
+}
+
+// Challenge derives the S256 code challenge for verifier (RFC 7636 Section 4.2).
+func Challenge(verifier string) string {
+	sum := sha256.Sum256([]byte(verifier))
+	return base64.RawURLEncoding.EncodeToString(sum[:])
+}
+
+// NewState returns a random value that ties the authorization response back to
+// the request that started it.
+func NewState() (string, error) {
+	return randomToken(16)
+}
+
+func randomToken(size int) (string, error) {
+	raw := make([]byte, size)
+	if _, err := rand.Read(raw); err != nil {
+		return "", fmt.Errorf("failed to read random bytes: %w", err)
+	}
+
+	return base64.RawURLEncoding.EncodeToString(raw), nil
+}
diff --git a/internal/oauth/pkce_test.go b/internal/oauth/pkce_test.go
new file mode 100644
index 0000000..e2a73ee
--- /dev/null
+++ b/internal/oauth/pkce_test.go
@@ -0,0 +1,44 @@
+package oauth
+
+import (
+	"encoding/base64"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestChallengeMatchesRFC7636Vector(t *testing.T) {
+	// RFC 7636 Appendix B.
+	challenge := Challenge("dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk")
+
+	assert.Equal(t, "E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM", challenge)
+}
+
+func TestNewVerifierIsUnpaddedBase64URLOf32Bytes(t *testing.T) {
+	verifier, err := NewVerifier()
+	require.NoError(t, err)
+
+	assert.Len(t, verifier, 43)
+	raw, err := base64.RawURLEncoding.DecodeString(verifier)
+	require.NoError(t, err)
+	assert.Len(t, raw, 32)
+}
+
+func TestNewVerifierIsRandom(t *testing.T) {
+	first, err := NewVerifier()
+	require.NoError(t, err)
+	second, err := NewVerifier()
+	require.NoError(t, err)
+
+	assert.NotEqual(t, first, second)
+}
+
+func TestNewStateIsUnpaddedBase64URLOf16Bytes(t *testing.T) {
+	state, err := NewState()
+	require.NoError(t, err)
+
+	raw, err := base64.RawURLEncoding.DecodeString(state)
+	require.NoError(t, err)
+	assert.Len(t, raw, 16)
+}

From ddc7fa4b340202d9f4cf9f095fc7d48b2aa63c20 Mon Sep 17 00:00:00 2001
From: fayzan <fayzan@requesty.ai>
Date: Wed, 16 Sep 2026 14:13:09 +0100
Subject: [PATCH 2/9] Implement launching a harness

---
 cmd/harness.go                     | 163 +++++++++++++++++++++++++++++
 cmd/harness_test.go                | 126 ++++++++++++++++++++++
 cmd/requesty.go                    |  14 ++-
 internal/harnesses/claude.go       | 128 +++++++++++++++++++++-
 internal/harnesses/claude_test.go  | 123 ++++++++++++++++++++++
 internal/harnesses/codex.go        |  74 ++++++++++++-
 internal/harnesses/codex_test.go   | 114 ++++++++++++++++++++
 internal/harnesses/deepseek.go     |   4 +
 internal/harnesses/exec_unix.go    |  12 +++
 internal/harnesses/exec_windows.go |  32 ++++++
 internal/harnesses/harnesses.go    |  18 +++-
 internal/harnesses/hermes.go       |   4 +
 internal/harnesses/launch.go       |  92 ++++++++++++++++
 internal/harnesses/launch_test.go  |  93 ++++++++++++++++
 internal/harnesses/opencode.go     |   4 +
 internal/harnesses/pi.go           |   4 +
 16 files changed, 999 insertions(+), 6 deletions(-)
 create mode 100644 cmd/harness.go
 create mode 100644 cmd/harness_test.go
 create mode 100644 internal/harnesses/exec_unix.go
 create mode 100644 internal/harnesses/exec_windows.go
 create mode 100644 internal/harnesses/launch.go
 create mode 100644 internal/harnesses/launch_test.go

diff --git a/cmd/harness.go b/cmd/harness.go
new file mode 100644
index 0000000..8176f7d
--- /dev/null
+++ b/cmd/harness.go
@@ -0,0 +1,163 @@
+package cmd
+
+import (
+	"errors"
+	"fmt"
+	"slices"
+	"strings"
+
+	"github.com/requestyai/cli/internal/config"
+	"github.com/requestyai/cli/internal/harnesses"
+	"github.com/spf13/cobra"
+)
+
+const (
+	harnessModelFlag  = "--model"
+	harnessEffortFlag = "--reasoning-effort"
+)
+
+// errHarnessHelp signals that the leading flags asked for help.
+var errHarnessHelp = errors.New("help requested")
+
+// newHarnessCommands returns the `requesty <harness>` commands, each of which
+// starts a harness with Requesty injected for that run.
+func newHarnessCommands(env environment) []*cobra.Command {
+	cfg := withRouterDefault(env.config)
+
+	return []*cobra.Command{
+		newHarnessCommand(env, "claude", "Claude Code", func() (harnesses.Harness, error) {
+			dir, err := harnesses.DefaultConfigDirClaudeCode()
+			if err != nil {
+				return nil, err
+			}
+			return harnesses.NewClaudeHarness(cfg, dir), nil
+		}),
+		newHarnessCommand(env, "codex", "Codex", func() (harnesses.Harness, error) {
+			dir, err := harnesses.DefaultConfigDirCodex()
+			if err != nil {
+				return nil, err
+			}
+			return harnesses.NewCodexHarness(cfg, dir), nil
+		}),
+	}
+}
+
+// newHarnessCommand builds `requesty <binary>`. The harness is constructed
+// lazily so a machine without a resolvable home directory still gets a help
+// page and a clear error, rather than a missing command.
+func newHarnessCommand(env environment, binary, displayName string, newHarness func() (harnesses.Harness, error)) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   fmt.Sprintf("%s [--model <id>] [--reasoning-effort <level>] [-- ] [%s args...]", binary, binary),
+		Short: fmt.Sprintf("Launch %s through Requesty", displayName),
+		Long: fmt.Sprintf("Launch %s with its traffic routed through Requesty for this run only.\n\n", displayName) +
+			"Flags:\n" +
+			fmt.Sprintf("  %-28s %s\n", harnessModelFlag+" <id>", "Model to use for this run (any Requesty model id)") +
+			fmt.Sprintf("  %-28s %s\n", harnessEffortFlag+" <level>", "Reasoning effort: "+strings.Join(harnesses.Efforts, ", ")) +
+			fmt.Sprintf("  %-28s %s", "-h, --help", "Show this help"),
+		// We take over parsing so harness flags are never interpreted as ours.
+		DisableFlagParsing:    true,
+		DisableFlagsInUseLine: true,
+		SilenceUsage:          true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			opts, err := parseHarnessArgs(args)
+			if errors.Is(err, errHarnessHelp) {
+				return cmd.Help()
+			}
+			if err != nil {
+				return err
+			}
+
+			if env.config.APIKey == "" {
+				return fmt.Errorf("no Requesty API key configured; run `requesty` to set one up")
+			}
+
+			harness, err := newHarness()
+			if err != nil {
+				return fmt.Errorf("failed to set up %s: %w", displayName, err)
+			}
+
+			launch := env.launchHarness
+			if launch == nil {
+				launch = harnesses.Harness.Launch
+			}
+
+			return launch(harness, opts)
+		},
+	}
+
+	return cmd
+}
+
+// parseHarnessArgs splits our leading flags from the harness's own arguments.
+// A bare `--` ends our flags explicitly; otherwise the first token we do not
+// recognise does. That keeps `requesty claude --model x -p "hi"` and
+// `requesty claude -p "hi"` both working, and lets a harness flag that happens
+// to share a name with ours (`codex --model`) still reach the harness when it
+// appears later.
+func parseHarnessArgs(args []string) (harnesses.LaunchOptions, error) {
+	var opts harnesses.LaunchOptions
+
+	for len(args) > 0 {
+		arg := args[0]
+
+		switch {
+		case arg == "--":
+			opts.Args = args[1:]
+			return opts, nil
+
+		case arg == "-h" || arg == "--help":
+			return opts, errHarnessHelp
+
+		case arg == harnessModelFlag || arg == harnessEffortFlag:
+			if len(args) < 2 {
+				return opts, fmt.Errorf("%s requires a value", arg)
+			}
+			if err := setHarnessFlag(&opts, arg, args[1]); err != nil {
+				return opts, err
+			}
+			args = args[2:]
+
+		case strings.HasPrefix(arg, harnessModelFlag+"=") || strings.HasPrefix(arg, harnessEffortFlag+"="):
+			flag, value, _ := strings.Cut(arg, "=")
+			if err := setHarnessFlag(&opts, flag, value); err != nil {
+				return opts, err
+			}
+			args = args[1:]
+
+		default:
+			opts.Args = args
+			return opts, nil
+		}
+	}
+
+	return opts, nil
+}
+
+func setHarnessFlag(opts *harnesses.LaunchOptions, flag, value string) error {
+	value = strings.TrimSpace(value)
+	if value == "" {
+		return fmt.Errorf("%s requires a value", flag)
+	}
+
+	switch flag {
+	case harnessModelFlag:
+		opts.Model = value
+	case harnessEffortFlag:
+		if !slices.Contains(harnesses.Efforts, value) {
+			return fmt.Errorf("%s must be one of %s (got %q)", flag, strings.Join(harnesses.Efforts, ", "), value)
+		}
+		opts.Effort = value
+	}
+
+	return nil
+}
+
+// withRouterDefault fills in the production router when the config predates
+// the field, so a launch never hands a harness an empty base URL.
+func withRouterDefault(cfg config.Config) config.Config {
+	if cfg.RouterBaseURL == "" {
+		cfg.RouterBaseURL = config.DefaultRouterBaseURL
+	}
+
+	return cfg
+}
diff --git a/cmd/harness_test.go b/cmd/harness_test.go
new file mode 100644
index 0000000..eab1430
--- /dev/null
+++ b/cmd/harness_test.go
@@ -0,0 +1,126 @@
+package cmd
+
+import (
+	"bytes"
+	"testing"
+
+	"github.com/requestyai/cli/internal/config"
+	"github.com/requestyai/cli/internal/harnesses"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+type recordedLaunch struct {
+	harness harnesses.Harness
+	opts    harnesses.LaunchOptions
+	called  bool
+}
+
+func recordingEnvironment(cfg config.Config) (environment, *recordedLaunch) {
+	recorded := &recordedLaunch{}
+	env := environment{
+		config: cfg,
+		launchHarness: func(harness harnesses.Harness, opts harnesses.LaunchOptions) error {
+			recorded.harness, recorded.opts, recorded.called = harness, opts, true
+			return nil
+		},
+	}
+
+	return env, recorded
+}
+
+func TestHarnessCommandsAreRegistered(t *testing.T) {
+	command := newRootCommand(environment{})
+
+	for _, name := range []string{"claude", "codex"} {
+		sub, _, err := command.Find([]string{name})
+		require.NoError(t, err)
+		assert.Equal(t, name, sub.Name())
+		assert.True(t, sub.DisableFlagParsing, "%s must not interpret harness flags", name)
+	}
+}
+
+func TestHarnessCommandPassesLeadingFlagsAndPassthrough(t *testing.T) {
+	env, recorded := recordingEnvironment(config.Config{APIKey: "my-api-key"})
+	command := newRootCommand(env)
+	command.SetArgs([]string{"claude", "--model", "anthropic/claude-fable-5", "--reasoning-effort=high", "--dangerously-skip-permissions", "-p", "hi"})
+
+	require.NoError(t, command.Execute())
+
+	require.True(t, recorded.called)
+	assert.Equal(t, "Claude Code", recorded.harness.Name())
+	assert.Equal(t, "anthropic/claude-fable-5", recorded.opts.Model)
+	assert.Equal(t, harnesses.EffortHigh, recorded.opts.Effort)
+	assert.Equal(t, []string{"--dangerously-skip-permissions", "-p", "hi"}, recorded.opts.Args)
+}
+
+func TestHarnessCommandStopsAtFirstForeignArgument(t *testing.T) {
+	env, recorded := recordingEnvironment(config.Config{APIKey: "my-api-key"})
+	command := newRootCommand(env)
+	// The second --model belongs to codex because a codex flag came first.
+	command.SetArgs([]string{"codex", "--full-auto", "--model", "theirs"})
+
+	require.NoError(t, command.Execute())
+
+	assert.Empty(t, recorded.opts.Model)
+	assert.Equal(t, []string{"--full-auto", "--model", "theirs"}, recorded.opts.Args)
+}
+
+func TestHarnessCommandDoubleDashEndsOurFlags(t *testing.T) {
+	env, recorded := recordingEnvironment(config.Config{APIKey: "my-api-key"})
+	command := newRootCommand(env)
+	command.SetArgs([]string{"codex", "--model", "openai/gpt-5", "--", "--model", "theirs"})
+
+	require.NoError(t, command.Execute())
+
+	assert.Equal(t, "openai/gpt-5", recorded.opts.Model)
+	assert.Equal(t, []string{"--model", "theirs"}, recorded.opts.Args)
+}
+
+func TestHarnessCommandRejectsUnknownEffort(t *testing.T) {
+	env, recorded := recordingEnvironment(config.Config{APIKey: "my-api-key"})
+	command := newRootCommand(env)
+	command.SetArgs([]string{"claude", "--reasoning-effort", "turbo"})
+
+	err := command.Execute()
+
+	require.EqualError(t, err, `--reasoning-effort must be one of minimal, low, medium, high, xhigh, max (got "turbo")`)
+	assert.False(t, recorded.called)
+}
+
+func TestHarnessCommandRejectsFlagWithoutValue(t *testing.T) {
+	env, recorded := recordingEnvironment(config.Config{APIKey: "my-api-key"})
+	command := newRootCommand(env)
+	command.SetArgs([]string{"claude", "--model"})
+
+	require.EqualError(t, command.Execute(), "--model requires a value")
+	assert.False(t, recorded.called)
+}
+
+func TestHarnessCommandRequiresAPIKey(t *testing.T) {
+	env, recorded := recordingEnvironment(config.Config{})
+	command := newRootCommand(env)
+	command.SetArgs([]string{"codex"})
+
+	require.EqualError(t, command.Execute(), "no Requesty API key configured; run `requesty` to set one up")
+	assert.False(t, recorded.called)
+}
+
+func TestHarnessCommandHelpDoesNotLaunch(t *testing.T) {
+	env, recorded := recordingEnvironment(config.Config{APIKey: "my-api-key"})
+	command := newRootCommand(env)
+	var output bytes.Buffer
+	command.SetOut(&output)
+	command.SetArgs([]string{"claude", "--help"})
+
+	require.NoError(t, command.Execute())
+
+	assert.False(t, recorded.called)
+	assert.Contains(t, output.String(), "--reasoning-effort")
+	assert.Contains(t, output.String(), "passed to `claude`")
+}
+
+func TestWithRouterDefaultFillsMissingURL(t *testing.T) {
+	assert.Equal(t, config.DefaultRouterBaseURL, withRouterDefault(config.Config{APIKey: "k"}).RouterBaseURL)
+	assert.Equal(t, "https://router.example.test", withRouterDefault(config.Config{RouterBaseURL: "https://router.example.test"}).RouterBaseURL)
+}
diff --git a/cmd/requesty.go b/cmd/requesty.go
index df8d524..78ceafd 100644
--- a/cmd/requesty.go
+++ b/cmd/requesty.go
@@ -7,6 +7,7 @@ import (
 	tea "charm.land/bubbletea/v2"
 	"github.com/requestyai/cli/internal/client"
 	"github.com/requestyai/cli/internal/config"
+	"github.com/requestyai/cli/internal/harnesses"
 	"github.com/requestyai/cli/internal/oauth"
 	"github.com/requestyai/cli/internal/tui"
 	"github.com/spf13/cobra"
@@ -30,6 +31,11 @@ type environment struct {
 
 	// login runs the browser sign-in. nil means the real OAuth flow.
 	login func(context.Context, oauth.Options) (*oauth.Token, error)
+
+	// launchHarness starts a harness through Requesty. nil means the harness's
+	// own Launch, which replaces the current process and so cannot run under
+	// a test.
+	launchHarness func(harnesses.Harness, harnesses.LaunchOptions) error
 }
 
 func newEnvironment() (environment, error) {
@@ -39,9 +45,10 @@ func newEnvironment() (environment, error) {
 	}
 
 	return environment{
-		config:      cfg,
-		apiv2Client: client.New(cfg),
-		login:       oauth.Login,
+		config:        cfg,
+		apiv2Client:   client.New(cfg),
+		login:         oauth.Login,
+		launchHarness: harnesses.Harness.Launch,
 	}, nil
 }
 
@@ -71,6 +78,7 @@ func newRootCommand(env environment) *cobra.Command {
 		newGroupsCommand(env),
 		newAccessListsCommand(env),
 	)
+	root.AddCommand(newHarnessCommands(env)...)
 
 	return root
 }
diff --git a/internal/harnesses/claude.go b/internal/harnesses/claude.go
index 2235f83..496aa96 100644
--- a/internal/harnesses/claude.go
+++ b/internal/harnesses/claude.go
@@ -7,6 +7,8 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"runtime"
+	"strings"
 
 	"github.com/requestyai/cli/internal/config"
 )
@@ -50,8 +52,9 @@ func (c *ClaudeHarness) Description() []string {
 func (c *ClaudeHarness) Status() (Status, error) {
 	status := Status{}
 
-	if _, err := exec.LookPath("claude"); err == nil {
+	if path, err := exec.LookPath("claude"); err == nil {
 		status.Executable = true
+		status.ExecutablePath = path
 	} else if !errors.Is(err, exec.ErrNotFound) {
 		return status, fmt.Errorf("failed to find executable: %w", err)
 	}
@@ -135,3 +138,126 @@ func (c *ClaudeHarness) configureOverwrite(opts ConfigureOptions) error {
 func (c *ClaudeHarness) settingsPath() string {
 	return filepath.Join(c.configDir, "settings.json")
 }
+
+// claudeEfforts maps Launch effort levels onto Claude Code's --effort values.
+var claudeEfforts = map[string]string{
+	EffortLow:    "low",
+	EffortMedium: "medium",
+	EffortHigh:   "high",
+	EffortXHigh:  "xhigh",
+	EffortMax:    "max",
+}
+
+// claudeOverrideSettings are passed inline with --settings so they outrank
+// the user's own settings.json for this run only. Every alternative-provider
+// switch is blanked so a Bedrock or Vertex setup on the machine cannot route
+// around Requesty; the credential itself stays out of argv and travels in
+// the environment.
+var claudeOverrideSettings = map[string]string{
+	"ANTHROPIC_AUTH_TOKEN":                   "",
+	"ANTHROPIC_AWS_BASE_URL":                 "",
+	"ANTHROPIC_BEDROCK_BASE_URL":             "",
+	"ANTHROPIC_BEDROCK_MANTLE_BASE_URL":      "",
+	"ANTHROPIC_FOUNDRY_BASE_URL":             "",
+	"ANTHROPIC_GOOGLE_CLOUD_BASE_URL":        "",
+	"ANTHROPIC_UNIX_SOCKET":                  "",
+	"ANTHROPIC_VERTEX_BASE_URL":              "",
+	"CLAUDE_CODE_OAUTH_TOKEN":                "",
+	"CLAUDE_CODE_USE_ANTHROPIC_AWS":          "",
+	"CLAUDE_CODE_USE_ANTHROPIC_GOOGLE_CLOUD": "",
+	"CLAUDE_CODE_USE_BEDROCK":                "",
+	"CLAUDE_CODE_USE_FOUNDRY":                "",
+	"CLAUDE_CODE_USE_GATEWAY":                "",
+	"CLAUDE_CODE_USE_MANTLE":                 "",
+	"CLAUDE_CODE_USE_VERTEX":                 "",
+}
+
+// claudeSettingsFlags are Claude Code flags that mean the user is managing
+// settings themselves, in which case we do not add our own --settings.
+var claudeSettingsFlags = []string{"--settings", "--setting-sources"}
+
+// Launch replaces this process with Claude Code pointed at Requesty. The base
+// URL and key go in the environment; an inline --settings document pins the
+// base URL above the user's settings.json and disables every other provider
+// path. Nothing is written to disk.
+func (c *ClaudeHarness) Launch(opts LaunchOptions) error {
+	status, err := c.Status()
+	if err != nil {
+		return fmt.Errorf("failed to check %s: %w", c.Name(), err)
+	}
+	if !status.Executable {
+		return fmt.Errorf("`claude` is not on PATH; install Claude Code (https://code.claude.com/docs/en/setup) and try again")
+	}
+
+	effort, err := mapEffort(c.Name(), claudeEfforts, opts.Effort)
+	if err != nil {
+		return err
+	}
+
+	env := parseEnvironmentVariables(opts.Env)
+	env["ANTHROPIC_BASE_URL"] = c.config.RouterBaseURL
+	env["ANTHROPIC_API_KEY"] = c.config.APIKey
+	env["REQUESTY_API_KEY"] = c.config.APIKey
+	delete(env, "ANTHROPIC_AUTH_TOKEN")
+	// The fast-mode check calls an Anthropic-only org endpoint that a gateway
+	// cannot answer; skipping it avoids a startup warning.
+	env["CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK"] = "1"
+	if opts.Model != "" {
+		env["ANTHROPIC_MODEL"] = opts.Model
+	}
+
+	argv := []string{"claude"}
+	if !hasAnyFlag(opts.Args, claudeSettingsFlags) {
+		settings, err := c.inlineSettings()
+		if err != nil {
+			return err
+		}
+		argv = append(argv, "--settings", settings)
+	}
+	if effort != "" {
+		argv = append(argv, "--effort", effort)
+	}
+	argv = append(argv, opts.Args...)
+
+	if err := execProcess(status.ExecutablePath, argv, formatEnvironmentVariables(env)); err != nil {
+		return fmt.Errorf("failed to launch claude: %w", err)
+	}
+
+	return nil
+}
+
+func (c *ClaudeHarness) inlineSettings() (string, error) {
+	settingsEnv := make(map[string]string, len(claudeOverrideSettings)+1)
+	for key, value := range claudeOverrideSettings {
+		settingsEnv[key] = value
+	}
+	settingsEnv["ANTHROPIC_BASE_URL"] = c.config.RouterBaseURL
+
+	settings := map[string]any{"env": settingsEnv}
+	if runtime.GOOS != "windows" {
+		// Claude Code runs the helper through a shell, which Windows lacks a
+		// reliable one for; there the ANTHROPIC_API_KEY variable carries it.
+		settings["apiKeyHelper"] = `printf %s "$REQUESTY_API_KEY"`
+	}
+
+	data, err := json.Marshal(settings)
+	if err != nil {
+		return "", fmt.Errorf("failed to encode inline settings: %w", err)
+	}
+
+	return string(data), nil
+}
+
+// hasAnyFlag reports whether args names one of flags, as `--flag` or
+// `--flag=value`.
+func hasAnyFlag(args []string, flags []string) bool {
+	for _, arg := range args {
+		for _, flag := range flags {
+			if arg == flag || strings.HasPrefix(arg, flag+"=") {
+				return true
+			}
+		}
+	}
+
+	return false
+}
diff --git a/internal/harnesses/claude_test.go b/internal/harnesses/claude_test.go
index 75b3aa3..5765fdf 100644
--- a/internal/harnesses/claude_test.go
+++ b/internal/harnesses/claude_test.go
@@ -1,8 +1,11 @@
 package harnesses
 
 import (
+	"encoding/json"
+	"errors"
 	"os"
 	"path/filepath"
+	"runtime"
 	"testing"
 
 	"github.com/requestyai/cli/internal/config"
@@ -64,6 +67,126 @@ func TestClaudeHarnessConfigureCreatesMissingConfig(t *testing.T) {
 	}`, string(settings))
 }
 
+func TestClaudeHarnessLaunchInjectsRequesty(t *testing.T) {
+	binaryPath := fakeBinary(t, "claude")
+	captured := captureExec(t)
+	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
+	harness := NewClaudeHarness(cfg, t.TempDir())
+
+	err := harness.Launch(LaunchOptions{
+		Model:  "anthropic/claude-fable-5",
+		Effort: EffortHigh,
+		Args:   []string{"--dangerously-skip-permissions", "-p", "hello"},
+		Env: []string{
+			"HOME=/home/me",
+			"ANTHROPIC_AUTH_TOKEN=stale-token",
+			"ANTHROPIC_API_KEY=someone-elses-key",
+		},
+	})
+	require.NoError(t, err)
+
+	assert.Equal(t, binaryPath, captured.path)
+
+	// Environment: Requesty replaces any Anthropic credential already present.
+	assert.Contains(t, captured.env, "HOME=/home/me")
+	assert.Contains(t, captured.env, "ANTHROPIC_BASE_URL=https://router.requesty.ai")
+	assert.Contains(t, captured.env, "ANTHROPIC_API_KEY=my-api-key")
+	assert.Contains(t, captured.env, "REQUESTY_API_KEY=my-api-key")
+	assert.Contains(t, captured.env, "ANTHROPIC_MODEL=anthropic/claude-fable-5")
+	assert.Contains(t, captured.env, "CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1")
+	for _, entry := range captured.env {
+		assert.NotContains(t, entry, "ANTHROPIC_AUTH_TOKEN=", "the bearer token path must be cleared")
+	}
+
+	// Arguments: argv[0], then our --settings and --effort, then the user's flags verbatim.
+	require.Len(t, captured.argv, 8)
+	assert.Equal(t, "claude", captured.argv[0])
+	assert.Equal(t, "--settings", captured.argv[1])
+	assert.Equal(t, []string{"--effort", "high", "--dangerously-skip-permissions", "-p", "hello"}, captured.argv[3:])
+
+	var settings struct {
+		APIKeyHelper string            `json:"apiKeyHelper"`
+		Env          map[string]string `json:"env"`
+	}
+	require.NoError(t, json.Unmarshal([]byte(captured.argv[2]), &settings))
+	assert.Equal(t, "https://router.requesty.ai", settings.Env["ANTHROPIC_BASE_URL"])
+	assert.Equal(t, "", settings.Env["CLAUDE_CODE_USE_BEDROCK"])
+	assert.Equal(t, "", settings.Env["CLAUDE_CODE_USE_VERTEX"])
+	assert.Equal(t, "", settings.Env["ANTHROPIC_AUTH_TOKEN"])
+	assert.NotContains(t, captured.argv[2], "my-api-key", "the key stays out of argv")
+	if runtime.GOOS == "windows" {
+		assert.Empty(t, settings.APIKeyHelper)
+	} else {
+		assert.Equal(t, `printf %s "$REQUESTY_API_KEY"`, settings.APIKeyHelper)
+	}
+}
+
+func TestClaudeHarnessLaunchWithoutOverridesIsMinimal(t *testing.T) {
+	fakeBinary(t, "claude")
+	captured := captureExec(t)
+	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
+	harness := NewClaudeHarness(cfg, t.TempDir())
+
+	require.NoError(t, harness.Launch(LaunchOptions{Env: []string{}}))
+
+	require.Len(t, captured.argv, 3, "only claude --settings <json>")
+	assert.Equal(t, "--settings", captured.argv[1])
+	for _, entry := range captured.env {
+		assert.NotContains(t, entry, "ANTHROPIC_MODEL=", "no model means the harness keeps its default")
+	}
+}
+
+func TestClaudeHarnessLaunchRespectsUserSettingsFlag(t *testing.T) {
+	fakeBinary(t, "claude")
+	captured := captureExec(t)
+	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
+	harness := NewClaudeHarness(cfg, t.TempDir())
+
+	for _, userArgs := range [][]string{
+		{"--settings", "/tmp/mine.json"},
+		{"--settings=/tmp/mine.json"},
+		{"--setting-sources", "user"},
+	} {
+		require.NoError(t, harness.Launch(LaunchOptions{Args: userArgs, Env: []string{}}))
+		assert.Equal(t, userArgs, captured.argv[1:], "user-managed settings must pass through untouched")
+	}
+}
+
+func TestClaudeHarnessLaunchRejectsUnsupportedEffort(t *testing.T) {
+	fakeBinary(t, "claude")
+	captured := captureExec(t)
+	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
+	harness := NewClaudeHarness(cfg, t.TempDir())
+
+	err := harness.Launch(LaunchOptions{Effort: EffortMinimal, Env: []string{}})
+
+	require.EqualError(t, err, `Claude Code does not support reasoning effort "minimal" (accepted: low, medium, high, xhigh, max)`)
+	assert.Empty(t, captured.path, "nothing should be launched")
+}
+
+func TestClaudeHarnessLaunchRequiresBinary(t *testing.T) {
+	t.Setenv("PATH", t.TempDir())
+	captured := captureExec(t)
+	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
+	harness := NewClaudeHarness(cfg, t.TempDir())
+
+	err := harness.Launch(LaunchOptions{Env: []string{}})
+
+	require.EqualError(t, err, "`claude` is not on PATH; install Claude Code (https://code.claude.com/docs/en/setup) and try again")
+	assert.Empty(t, captured.path)
+}
+
+func TestClaudeHarnessLaunchWrapsExecFailure(t *testing.T) {
+	fakeBinary(t, "claude")
+	previous := execProcess
+	execProcess = func(string, []string, []string) error { return errors.New("boom") }
+	t.Cleanup(func() { execProcess = previous })
+	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
+	harness := NewClaudeHarness(cfg, t.TempDir())
+
+	require.EqualError(t, harness.Launch(LaunchOptions{Env: []string{}}), "failed to launch claude: boom")
+}
+
 func TestClaudeHarnessDefaultConfigDir(t *testing.T) {
 	homePath, err := os.UserHomeDir()
 	require.NoError(t, err)
diff --git a/internal/harnesses/codex.go b/internal/harnesses/codex.go
index 06fb148..4999a9c 100644
--- a/internal/harnesses/codex.go
+++ b/internal/harnesses/codex.go
@@ -6,6 +6,8 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strconv"
+	"strings"
 
 	"github.com/pelletier/go-toml/v2"
 	"github.com/requestyai/cli/internal/config"
@@ -69,8 +71,9 @@ func (c *CodexHarness) Description() []string {
 func (c *CodexHarness) Status() (Status, error) {
 	status := Status{}
 
-	if _, err := exec.LookPath("codex"); err == nil {
+	if path, err := exec.LookPath("codex"); err == nil {
 		status.Executable = true
+		status.ExecutablePath = path
 	} else if !errors.Is(err, exec.ErrNotFound) {
 		return status, fmt.Errorf("failed to find executable: %w", err)
 	}
@@ -186,3 +189,72 @@ func (c *CodexHarness) configureOverwrite(opts ConfigureOptions) error {
 func (c *CodexHarness) configPath() string {
 	return filepath.Join(c.configDir, "config.toml")
 }
+
+// codexEfforts maps Launch effort levels onto Codex's model_reasoning_effort.
+var codexEfforts = map[string]string{
+	EffortMinimal: "minimal",
+	EffortLow:     "low",
+	EffortMedium:  "medium",
+	EffortHigh:    "high",
+	EffortXHigh:   "xhigh",
+}
+
+// Launch replaces this process with Codex pointed at Requesty using
+// `-c key=value` overrides, which outrank ~/.codex/config.toml for this run
+// only. Nothing is written to disk; the key is fetched on demand through
+// `requesty auth token`, so it appears in neither argv nor the environment.
+func (c *CodexHarness) Launch(opts LaunchOptions) error {
+	status, err := c.Status()
+	if err != nil {
+		return fmt.Errorf("failed to check %s: %w", c.Name(), err)
+	}
+	if !status.Executable {
+		return fmt.Errorf("`codex` is not on PATH; install Codex (https://developers.openai.com/codex/cli) and try again")
+	}
+
+	effort, err := mapEffort(c.Name(), codexEfforts, opts.Effort)
+	if err != nil {
+		return err
+	}
+
+	provider := "model_providers." + codexModelProvider
+	argv := []string{
+		"codex",
+		"-c", "model_provider=" + tomlString(codexModelProvider),
+		"-c", provider + ".name=" + tomlString("Requesty"),
+		"-c", provider + ".base_url=" + tomlString(c.config.RouterBaseURL+"/v1"),
+		"-c", provider + ".http_headers.X-Title=" + tomlString("OpenAI Codex"),
+		"-c", provider + ".auth.command=" + tomlString(requestyExecutable()),
+		"-c", provider + ".auth.args=[" + tomlString("auth") + "," + tomlString("token") + "]",
+		"-c", "model_supports_reasoning_summaries=false",
+	}
+	if opts.Model != "" {
+		argv = append(argv, "-m", opts.Model)
+	}
+	if effort != "" {
+		argv = append(argv, "-c", "model_reasoning_effort="+tomlString(effort))
+	}
+	argv = append(argv, opts.Args...)
+
+	env := opts.Env
+	if env == nil {
+		env = os.Environ()
+	}
+
+	if err := execProcess(status.ExecutablePath, argv, env); err != nil {
+		return fmt.Errorf("failed to launch codex: %w", err)
+	}
+
+	return nil
+}
+
+// tomlString quotes s as a TOML string for a Codex -c override. Codex parses
+// the value side as TOML, so unquoted text with spaces or slashes would be
+// rejected. Literal strings are preferred because they need no escaping.
+func tomlString(s string) string {
+	if !strings.ContainsAny(s, "'\n\r") {
+		return "'" + s + "'"
+	}
+
+	return strconv.Quote(s)
+}
diff --git a/internal/harnesses/codex_test.go b/internal/harnesses/codex_test.go
index 45f7036..1984fa1 100644
--- a/internal/harnesses/codex_test.go
+++ b/internal/harnesses/codex_test.go
@@ -3,6 +3,7 @@ package harnesses
 import (
 	"os"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	"github.com/pelletier/go-toml/v2"
@@ -94,6 +95,119 @@ func TestCodexHarnessConfigureOverwriteUsesProviderAuth(t *testing.T) {
 	assert.ErrorIs(t, err, os.ErrNotExist)
 }
 
+// codexOverrides collects the `-c key=value` pairs from a launch and checks
+// each value parses the way Codex parses it: as the right-hand side of a TOML
+// assignment.
+func codexOverrides(t *testing.T, args []string) map[string]any {
+	t.Helper()
+
+	overrides := map[string]any{}
+	for i := 0; i+1 < len(args); i++ {
+		if args[i] != "-c" {
+			continue
+		}
+		key, value, found := strings.Cut(args[i+1], "=")
+		require.True(t, found, "override %q has no '='", args[i+1])
+
+		var parsed struct {
+			Value any `toml:"value"`
+		}
+		require.NoError(t, toml.Unmarshal([]byte("value = "+value), &parsed), "override %q is not valid TOML", args[i+1])
+		overrides[key] = parsed.Value
+	}
+
+	return overrides
+}
+
+func TestCodexHarnessLaunchInjectsRequestyOverrides(t *testing.T) {
+	binaryPath := fakeBinary(t, "codex")
+	captured := captureExec(t)
+	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
+	harness := NewCodexHarness(cfg, t.TempDir())
+
+	err := harness.Launch(LaunchOptions{
+		Model:  "openai/gpt-5",
+		Effort: EffortXHigh,
+		Args:   []string{"--full-auto", "fix the tests"},
+		Env:    []string{"HOME=/home/me"},
+	})
+	require.NoError(t, err)
+
+	assert.Equal(t, binaryPath, captured.path)
+	assert.Equal(t, "codex", captured.argv[0])
+	assert.Equal(t, []string{"HOME=/home/me"}, captured.env, "the key travels through auth.command, not the environment")
+
+	overrides := codexOverrides(t, captured.argv)
+	assert.Equal(t, "requesty", overrides["model_provider"])
+	assert.Equal(t, "Requesty", overrides["model_providers.requesty.name"])
+	assert.Equal(t, "https://router.requesty.ai/v1", overrides["model_providers.requesty.base_url"])
+	assert.Equal(t, "OpenAI Codex", overrides["model_providers.requesty.http_headers.X-Title"])
+	assert.Equal(t, []any{"auth", "token"}, overrides["model_providers.requesty.auth.args"])
+	assert.Equal(t, false, overrides["model_supports_reasoning_summaries"])
+	assert.Equal(t, "xhigh", overrides["model_reasoning_effort"])
+
+	authCommand, _ := overrides["model_providers.requesty.auth.command"].(string)
+	executable, err := os.Executable()
+	require.NoError(t, err)
+	assert.Equal(t, executable, authCommand, "auth.command points at this very binary")
+
+	// Model, effort and then the user's own arguments come after the overrides, in order.
+	tail := captured.argv[len(captured.argv)-6:]
+	assert.Equal(t, []string{"-m", "openai/gpt-5", "-c", "model_reasoning_effort='xhigh'", "--full-auto", "fix the tests"}, tail)
+	assert.NotContains(t, strings.Join(captured.argv, " "), "my-api-key")
+}
+
+func TestCodexHarnessLaunchWithoutOverridesOmitsModelAndEffort(t *testing.T) {
+	fakeBinary(t, "codex")
+	captured := captureExec(t)
+	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
+	harness := NewCodexHarness(cfg, t.TempDir())
+
+	require.NoError(t, harness.Launch(LaunchOptions{Env: []string{}}))
+
+	assert.NotContains(t, captured.argv, "-m")
+	_, hasEffort := codexOverrides(t, captured.argv)["model_reasoning_effort"]
+	assert.False(t, hasEffort)
+}
+
+func TestCodexHarnessLaunchRejectsUnsupportedEffort(t *testing.T) {
+	fakeBinary(t, "codex")
+	captured := captureExec(t)
+	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
+	harness := NewCodexHarness(cfg, t.TempDir())
+
+	err := harness.Launch(LaunchOptions{Effort: EffortMax, Env: []string{}})
+
+	require.EqualError(t, err, `Codex does not support reasoning effort "max" (accepted: minimal, low, medium, high, xhigh)`)
+	assert.Empty(t, captured.path, "nothing should be launched")
+}
+
+func TestCodexHarnessLaunchRequiresBinary(t *testing.T) {
+	t.Setenv("PATH", t.TempDir())
+	captured := captureExec(t)
+	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
+	harness := NewCodexHarness(cfg, t.TempDir())
+
+	err := harness.Launch(LaunchOptions{Env: []string{}})
+
+	require.EqualError(t, err, "`codex` is not on PATH; install Codex (https://developers.openai.com/codex/cli) and try again")
+	assert.Empty(t, captured.path)
+}
+
+func TestTomlStringQuotesForCodexOverrides(t *testing.T) {
+	assert.Equal(t, `'plain'`, tomlString("plain"))
+	assert.Equal(t, `'/Users/me/My Tools/requesty'`, tomlString("/Users/me/My Tools/requesty"))
+	assert.Equal(t, `"it's"`, tomlString("it's"))
+
+	for _, value := range []string{"plain", "/Users/me/My Tools/requesty", "it's", `C:\Program Files\requesty.exe`} {
+		var parsed struct {
+			Value string `toml:"value"`
+		}
+		require.NoError(t, toml.Unmarshal([]byte("value = "+tomlString(value)), &parsed))
+		assert.Equal(t, value, parsed.Value)
+	}
+}
+
 func TestCodexHarnessDefaultConfigDir(t *testing.T) {
 	homePath, err := os.UserHomeDir()
 	require.NoError(t, err)
diff --git a/internal/harnesses/deepseek.go b/internal/harnesses/deepseek.go
index 0519bc5..cf2e323 100644
--- a/internal/harnesses/deepseek.go
+++ b/internal/harnesses/deepseek.go
@@ -154,6 +154,10 @@ func (d *DeepSeekHarness) Status() (Status, error) {
 	return status, nil
 }
 
+func (d *DeepSeekHarness) Launch(LaunchOptions) error {
+	return launchNotImplemented(d.Name())
+}
+
 func (d *DeepSeekHarness) Configure(opts ConfigureOptions) error {
 	if opts.Overwrite {
 		return d.configureOverwrite(opts)
diff --git a/internal/harnesses/exec_unix.go b/internal/harnesses/exec_unix.go
new file mode 100644
index 0000000..e66858e
--- /dev/null
+++ b/internal/harnesses/exec_unix.go
@@ -0,0 +1,12 @@
+//go:build !windows
+
+package harnesses
+
+import "syscall"
+
+// execProcess replaces the current process with the harness, so the harness
+// owns the terminal directly and requesty leaves no wrapper behind. It is a
+// variable so tests can capture the launch instead of performing it.
+var execProcess = func(path string, argv []string, env []string) error {
+	return syscall.Exec(path, argv, env)
+}
diff --git a/internal/harnesses/exec_windows.go b/internal/harnesses/exec_windows.go
new file mode 100644
index 0000000..ee19135
--- /dev/null
+++ b/internal/harnesses/exec_windows.go
@@ -0,0 +1,32 @@
+//go:build windows
+
+package harnesses
+
+import (
+	"errors"
+	"os"
+	"os/exec"
+)
+
+// execProcess runs the harness as a child with our terminal and exits with
+// its status once it finishes. Windows has no exec(2), so this is the closest
+// equivalent. It is a variable so tests can capture the launch instead.
+var execProcess = func(path string, argv []string, env []string) error {
+	cmd := exec.Command(path, argv[1:]...)
+	cmd.Env = env
+	cmd.Stdin = os.Stdin
+	cmd.Stdout = os.Stdout
+	cmd.Stderr = os.Stderr
+
+	err := cmd.Run()
+	var exitErr *exec.ExitError
+	if errors.As(err, &exitErr) {
+		os.Exit(exitErr.ExitCode())
+	}
+	if err != nil {
+		return err
+	}
+
+	os.Exit(0)
+	return nil
+}
diff --git a/internal/harnesses/harnesses.go b/internal/harnesses/harnesses.go
index 0b0ac63..d533de0 100644
--- a/internal/harnesses/harnesses.go
+++ b/internal/harnesses/harnesses.go
@@ -9,7 +9,9 @@ import (
 type Status struct {
 	Files      []string
 	Executable bool
-	Configured bool
+
+	ExecutablePath string
+	Configured     bool
 }
 
 type ConfigureOptions struct {
@@ -17,11 +19,25 @@ type ConfigureOptions struct {
 	Overwrite bool
 }
 
+type LaunchOptions struct {
+	// Model overrides the harness's default model for this run. Empty leaves
+	// whatever the harness would pick on its own (including a model our
+	// Configure wrote into its settings file earlier).
+	Model string
+	// Effort is one of Efforts, or empty for the harness default.
+	Effort string
+	// Args is passed to the harness binary untouched, after our own flags.
+	Args []string
+	// Env is the environment to start from. nil means os.Environ().
+	Env []string
+}
+
 type Harness interface {
 	Name() string
 	Description() []string
 	Status() (Status, error)
 	Configure(ConfigureOptions) error
+	Launch(LaunchOptions) error
 }
 
 func Harnesses(config config.Config) ([]Harness, error) {
diff --git a/internal/harnesses/hermes.go b/internal/harnesses/hermes.go
index 6e1adfb..c57cada 100644
--- a/internal/harnesses/hermes.go
+++ b/internal/harnesses/hermes.go
@@ -112,6 +112,10 @@ func (h *HermesHarness) Status() (Status, error) {
 	return status, nil
 }
 
+func (h *HermesHarness) Launch(LaunchOptions) error {
+	return launchNotImplemented(h.Name())
+}
+
 func (h *HermesHarness) Configure(opts ConfigureOptions) error {
 	if opts.Overwrite {
 		return h.configureOverwrite(opts)
diff --git a/internal/harnesses/launch.go b/internal/harnesses/launch.go
new file mode 100644
index 0000000..677d444
--- /dev/null
+++ b/internal/harnesses/launch.go
@@ -0,0 +1,92 @@
+package harnesses
+
+import (
+	"fmt"
+	"os"
+	"slices"
+	"sort"
+	"strings"
+)
+
+// Effort levels understood by Launch. Each harness translates them to its own
+// vocabulary and rejects the ones it cannot express.
+const (
+	EffortMinimal = "minimal"
+	EffortLow     = "low"
+	EffortMedium  = "medium"
+	EffortHigh    = "high"
+	EffortXHigh   = "xhigh"
+	EffortMax     = "max"
+)
+
+// Efforts lists every level Launch accepts, weakest first.
+var Efforts = []string{EffortMinimal, EffortLow, EffortMedium, EffortHigh, EffortXHigh, EffortMax}
+
+// mapEffort translates a Launch effort level through a harness's own table.
+func mapEffort(harness string, table map[string]string, effort string) (string, error) {
+	if effort == "" {
+		return "", nil
+	}
+
+	if native, ok := table[effort]; ok {
+		return native, nil
+	}
+
+	accepted := make([]string, 0, len(table))
+	for level := range table {
+		accepted = append(accepted, level)
+	}
+	sort.Slice(accepted, func(i, j int) bool {
+		return slices.Index(Efforts, accepted[i]) < slices.Index(Efforts, accepted[j])
+	})
+
+	return "", fmt.Errorf("%s does not support reasoning effort %q (accepted: %s)",
+		harness, effort, strings.Join(accepted, ", "))
+}
+
+// launchNotImplemented is what harnesses without a launcher say instead of
+// doing anything.
+func launchNotImplemented(name string) error {
+	_, _ = fmt.Fprintf(os.Stderr, "Launching %s through Requesty is not implemented yet.\n", name)
+	return nil
+}
+
+// requestyExecutable is the command a harness should shell out to for
+// credentials. It prefers our own absolute path so the launch does not depend
+// on `requesty` being on the harness's PATH.
+func requestyExecutable() string {
+	if path, err := os.Executable(); err == nil && path != "" {
+		return path
+	}
+
+	return "requesty"
+}
+
+// parseEnvironmentVariables turns the "KEY=value" strings os.Environ produces into a map,
+// so a harness can set or delete variables by name. nil means the current
+// process environment.
+func parseEnvironmentVariables(env []string) map[string]string {
+	if env == nil {
+		env = os.Environ()
+	}
+
+	parsed := make(map[string]string, len(env))
+	for _, entry := range env {
+		key, value, _ := strings.Cut(entry, "=")
+		parsed[key] = value
+	}
+
+	return parsed
+}
+
+// formatEnvironmentVariables is the inverse of parseEnvironmentVariables: it returns the "KEY=value"
+// strings exec expects, sorted so the result is deterministic.
+func formatEnvironmentVariables(env map[string]string) []string {
+	formatted := make([]string, 0, len(env))
+	for key, value := range env {
+		formatted = append(formatted, key+"="+value)
+	}
+	slices.Sort(formatted)
+
+	return formatted
+}
diff --git a/internal/harnesses/launch_test.go b/internal/harnesses/launch_test.go
new file mode 100644
index 0000000..be802c2
--- /dev/null
+++ b/internal/harnesses/launch_test.go
@@ -0,0 +1,93 @@
+package harnesses
+
+import (
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+
+	"github.com/requestyai/cli/internal/config"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// capturedLaunch is what a harness's Launch handed to execProcess.
+type capturedLaunch struct {
+	path string
+	argv []string
+	env  []string
+}
+
+// captureExec swaps the process replacement for a recorder for one test.
+func captureExec(t *testing.T) *capturedLaunch {
+	t.Helper()
+
+	captured := &capturedLaunch{}
+	previous := execProcess
+	execProcess = func(path string, argv []string, env []string) error {
+		captured.path, captured.argv, captured.env = path, argv, env
+		return nil
+	}
+	t.Cleanup(func() { execProcess = previous })
+
+	return captured
+}
+
+// fakeBinary drops an executable named name into a temp dir that leads PATH
+// and returns its path.
+func fakeBinary(t *testing.T, name string) string {
+	t.Helper()
+
+	dir := t.TempDir()
+	if runtime.GOOS == "windows" {
+		name += ".exe"
+	}
+	path := filepath.Join(dir, name)
+	require.NoError(t, os.WriteFile(path, []byte("#!/bin/sh\n"), 0o755))
+	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
+
+	return path
+}
+
+func TestUnsupportedHarnessesLaunchAsNoOp(t *testing.T) {
+	captured := captureExec(t)
+	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
+
+	for _, harness := range []Harness{
+		NewOpenCodeHarness(cfg, t.TempDir()),
+		NewPiHarness(cfg, t.TempDir()),
+		NewHermesHarness(cfg, t.TempDir()),
+		NewDeepSeekHarness(cfg, t.TempDir()),
+	} {
+		require.NoError(t, harness.Launch(LaunchOptions{}), harness.Name())
+	}
+	assert.Empty(t, captured.path, "nothing should be launched")
+}
+
+func TestMapEffortListsAcceptedLevelsInOrder(t *testing.T) {
+	_, err := mapEffort("Codex", codexEfforts, EffortMax)
+
+	require.EqualError(t, err, `Codex does not support reasoning effort "max" (accepted: minimal, low, medium, high, xhigh)`)
+}
+
+func TestMapEffortEmptyMeansHarnessDefault(t *testing.T) {
+	native, err := mapEffort("Codex", codexEfforts, "")
+
+	require.NoError(t, err)
+	assert.Empty(t, native)
+}
+
+func TestEnvironRoundTripsAndSorts(t *testing.T) {
+	env := parseEnvironmentVariables([]string{"C=3", "A=1", "B=2", "EQUALS=a=b"})
+	env["B"] = "two"
+	delete(env, "A")
+	env["D"] = "4"
+
+	assert.Equal(t, []string{"B=two", "C=3", "D=4", "EQUALS=a=b"}, formatEnvironmentVariables(env))
+}
+
+func TestParseEnvironNilMeansProcessEnvironment(t *testing.T) {
+	t.Setenv("REQUESTY_TEST_MARKER", "present")
+
+	assert.Equal(t, "present", parseEnvironmentVariables(nil)["REQUESTY_TEST_MARKER"])
+}
diff --git a/internal/harnesses/opencode.go b/internal/harnesses/opencode.go
index fd456bd..c48ecee 100644
--- a/internal/harnesses/opencode.go
+++ b/internal/harnesses/opencode.go
@@ -97,6 +97,10 @@ func (o *OpenCodeHarness) Status() (Status, error) {
 	return status, nil
 }
 
+func (o *OpenCodeHarness) Launch(LaunchOptions) error {
+	return launchNotImplemented(o.Name())
+}
+
 func (o *OpenCodeHarness) Configure(opts ConfigureOptions) error {
 	if opts.Overwrite {
 		return o.configureOverwrite(opts)
diff --git a/internal/harnesses/pi.go b/internal/harnesses/pi.go
index 964caf9..8fa67f9 100644
--- a/internal/harnesses/pi.go
+++ b/internal/harnesses/pi.go
@@ -125,6 +125,10 @@ func (p *PiHarness) Status() (Status, error) {
 	return status, nil
 }
 
+func (p *PiHarness) Launch(LaunchOptions) error {
+	return launchNotImplemented(p.Name())
+}
+
 func (p *PiHarness) Configure(opts ConfigureOptions) error {
 	if opts.Overwrite {
 		return p.configureOverwrite(opts)

From 7f58c3c5890c9487c75443a970de9ea9b759ea30 Mon Sep 17 00:00:00 2001
From: fayzan <fayzan@requesty.ai>
Date: Mon, 21 Sep 2026 13:08:40 +0100
Subject: [PATCH 3/9] Implement onboarding flow

---
 .gitignore                                    |   3 +
 README.md                                     |  80 ++++-
 cmd/harness.go                                |  40 +--
 cmd/harness_test.go                           | 181 +++++-----
 cmd/login.go                                  | 104 ++++--
 cmd/login_test.go                             | 127 +++----
 cmd/requesty.go                               |  44 ++-
 internal/client/api_keys.go                   |   3 +
 internal/client/api_keys_test.go              |  15 +-
 internal/client/auth.go                       |   7 +-
 internal/client/auth_test.go                  |   4 +-
 internal/client/client.go                     |  11 +-
 internal/client/usage.go                      |   7 +-
 internal/client/usage_test.go                 |   2 +-
 internal/config/config.go                     |  48 +--
 internal/config/config_test.go                |  86 ++++-
 internal/oauth/flow.go                        |   7 +
 internal/oauth/flow_test.go                   |  12 +-
 internal/onboarding/flow.go                   | 180 ++++++++++
 internal/onboarding/flow_test.go              | 178 ++++++++++
 internal/onboarding/model.go                  | 330 ++++++++++++++++++
 internal/onboarding/model_test.go             | 141 ++++++++
 internal/onboarding/run.go                    |  57 +++
 internal/tui/onboarding_app.go                |  41 ---
 .../tui/pages/onboarding/apikey/api_key.go    | 138 --------
 internal/tui/root.go                          |  25 +-
 26 files changed, 1377 insertions(+), 494 deletions(-)
 create mode 100644 internal/onboarding/flow.go
 create mode 100644 internal/onboarding/flow_test.go
 create mode 100644 internal/onboarding/model.go
 create mode 100644 internal/onboarding/model_test.go
 create mode 100644 internal/onboarding/run.go
 delete mode 100644 internal/tui/onboarding_app.go
 delete mode 100644 internal/tui/pages/onboarding/apikey/api_key.go

diff --git a/.gitignore b/.gitignore
index 5d93552..1046a9b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -30,6 +30,9 @@ go.work.sum
 # GoReleaser output
 dist/
 
+# Local build of the CLI
+/requesty
+
 # Editor/IDE
 .idea/
 # .vscode/
diff --git a/README.md b/README.md
index 0689a9b..b0a5864 100644
--- a/README.md
+++ b/README.md
@@ -41,12 +41,15 @@ a new terminal, or run the `source` command it prints, then run `requesty`.
 
 ## First run
 
-**Paste an API key**
+**Sign in with your browser**
 
-On first run the CLI asks for a key. Create one on the
-[API keys page](https://app.requesty.ai/api-keys). The key is checked against the gateway before
-it is saved, so a typo is rejected here instead of failing later. It is stored in
-`~/.requesty/config.json` and reused on every later run, so this happens once.
+The first time you run `requesty`, `requesty claude` or `requesty codex` on a machine without a key,
+the CLI opens with a welcome page that says what is about to happen. Press enter and it signs you in
+to Requesty in your browser; once you approve, it creates an API key in your account, named after
+this machine (`Requesty CLI (my-laptop)`), and saves it to `~/.requesty/config.json`. The app then
+carries on to its dashboard, or the harness you asked for starts. Every later run reuses that key,
+so this happens once. The key shows up on the [API keys page](https://app.requesty.ai/api-keys)
+like any other, and can be revoked there.
 
 ```text
 ╭──────────────────────────────────────────────────────────────────╮
@@ -54,14 +57,40 @@ it is saved, so a typo is rejected here instead of failing later. It is stored i
 │ One gateway for every model, in every tool you use, or app you   │
 │ build.                                                           │
 │                                                                  │
-│ Paste an API key from https://app.requesty.ai/api-keys to begin. │
+│ Sign in with your browser to get started. This creates an API    │
+│ key named "Requesty CLI (my-laptop)" in your Requesty account    │
+│ and saves it to /home/you/.requesty/config.json.                 │
+│ Claude Code starts as soon as the key is saved.                  │
 │                                                                  │
-│ ❯ rqsty-...                                                      │
+│ Working over SSH, or already have a key? Quit and run `requesty  │
+│ login --api-key <key>` instead.                                  │
 │                                                                  │
-│ enter continue · ctrl+c quit                                 dev │
+│ enter sign in · q/esc quit                                   dev │
 ╰──────────────────────────────────────────────────────────────────╯
 ```
 
+While the browser is open a dialog shows the sign-in address, for when the browser did not open on
+its own; `esc` cancels. The key is created in your group. If you belong to several groups a dialog
+asks which one; if you belong to none it is a personal key. Organizations that require keys to live
+in a group will say so, in which case ask an admin to add you to one.
+
+Without a terminal to ask on (a script, a CI job) a harness launch stops and tells you to run
+`requesty login` first.
+
+**`requesty login`**
+
+`requesty login` runs the same sign-in from the command line. Use it to set up a machine before
+launching anything, to pick a group without being asked (`--group Engineering`), or to replace a
+key that was revoked or has expired. When a working key is already saved it does nothing unless
+you pass `--force`.
+
+**Over SSH, or with a key you already have**
+
+The browser hands the sign-in back to the CLI on `127.0.0.1`, which does not work over SSH. Create
+a key on the [API keys page](https://app.requesty.ai/api-keys) and run
+`requesty login --api-key <key>` instead. The key is checked against the gateway before it is
+saved, so a typo is rejected here instead of failing later.
+
 **Pick a harness**
 
 Harnesses found on your `PATH` are listed first. The ones that are not installed stay dimmed and
@@ -159,8 +188,14 @@ through `requesty auth token`; other harnesses may also store it in their own co
 is how they authenticate. All files containing the key are written so that only your user can
 read them.
 
+A key created by signing in can make completions and read its own usage, nothing more. The
+management subcommands (`requesty api-keys`, `requesty groups`, `requesty access-lists`) need a
+key with manage permissions from the [API keys page](https://app.requesty.ai/api-keys). The
+short-lived token from the browser sign-in is used once to create the key and is never stored.
+
 Treat those files as secrets and do not commit them. Keys can be rotated or revoked at any time
-on the [API keys page](https://app.requesty.ai/api-keys).
+on the [API keys page](https://app.requesty.ai/api-keys); run `requesty login` afterwards to get
+a new one.
 
 ## Configuration
 
@@ -247,13 +282,28 @@ gofmt -l .          # CI fails if this prints anything
 **A harness is listed but cannot be configured.** Its executable was not found on your `PATH`.
 Install the harness, then refresh the list.
 
-**`That key was not recognised`.** The gateway does not accept the key you pasted. Copy it again
-from the [API keys page](https://app.requesty.ai/api-keys).
+**`that API key was not recognised`.** The gateway does not accept the key you gave
+`requesty login --api-key`. Copy it again from the [API keys page](https://app.requesty.ai/api-keys).
+
+**The browser never comes back to the terminal.** The sign-in finishes by redirecting your browser
+to `127.0.0.1` on the machine running the CLI, so it cannot complete over SSH or in a container.
+Run `requesty login --api-key <key>` with a key from the
+[API keys page](https://app.requesty.ai/api-keys) instead, or forward the port shown in the
+sign-in URL.
+
+**`no Requesty API key configured; run requesty login`.** The CLI ran without a key and without a
+terminal to ask on. Run `requesty login` once, interactively, or `requesty login --api-key <key>`.
+
+**`group_id is required for organizations in group budget mode`.** Your organization tracks spend
+per group, and you are not in one yet. Ask an organization admin to add you to a group, then sign
+in again.
+
+**Claude Code or Codex gets a `401`.** The key was revoked or has expired. Run `requesty login`;
+it notices the saved key no longer works and creates a new one.
 
-**`Could not load usage`.** The usage panel calls the management API with your key. A `401` means
-the key was revoked or has expired: create a new one on the
-[API keys page](https://app.requesty.ai/api-keys) and delete `~/.requesty/config.json` to
-re-onboard. Routing itself is unaffected by this panel.
+**`Could not load usage`.** The usage panel asks the management API about your own key, which any
+key may do. A `401` means the key was revoked or has expired: run `requesty login` to get a new
+one. Routing itself is unaffected by this panel.
 
 **The harness still uses its old provider.** Restart it. Configuration is read at startup.
 
diff --git a/cmd/harness.go b/cmd/harness.go
index 8176f7d..c00c9e3 100644
--- a/cmd/harness.go
+++ b/cmd/harness.go
@@ -22,17 +22,15 @@ var errHarnessHelp = errors.New("help requested")
 // newHarnessCommands returns the `requesty <harness>` commands, each of which
 // starts a harness with Requesty injected for that run.
 func newHarnessCommands(env environment) []*cobra.Command {
-	cfg := withRouterDefault(env.config)
-
 	return []*cobra.Command{
-		newHarnessCommand(env, "claude", "Claude Code", func() (harnesses.Harness, error) {
+		newHarnessCommand(env, "claude", "Claude Code", func(cfg config.Config) (harnesses.Harness, error) {
 			dir, err := harnesses.DefaultConfigDirClaudeCode()
 			if err != nil {
 				return nil, err
 			}
 			return harnesses.NewClaudeHarness(cfg, dir), nil
 		}),
-		newHarnessCommand(env, "codex", "Codex", func() (harnesses.Harness, error) {
+		newHarnessCommand(env, "codex", "Codex", func(cfg config.Config) (harnesses.Harness, error) {
 			dir, err := harnesses.DefaultConfigDirCodex()
 			if err != nil {
 				return nil, err
@@ -43,9 +41,10 @@ func newHarnessCommands(env environment) []*cobra.Command {
 }
 
 // newHarnessCommand builds `requesty <binary>`. The harness is constructed
-// lazily so a machine without a resolvable home directory still gets a help
-// page and a clear error, rather than a missing command.
-func newHarnessCommand(env environment, binary, displayName string, newHarness func() (harnesses.Harness, error)) *cobra.Command {
+// lazily, from the config as it stands after any onboarding, so a machine
+// without a resolvable home directory still gets a help page and a clear
+// error, rather than a missing command.
+func newHarnessCommand(env environment, binary, displayName string, newHarness func(config.Config) (harnesses.Harness, error)) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   fmt.Sprintf("%s [--model <id>] [--reasoning-effort <level>] [-- ] [%s args...]", binary, binary),
 		Short: fmt.Sprintf("Launch %s through Requesty", displayName),
@@ -53,7 +52,8 @@ func newHarnessCommand(env environment, binary, displayName string, newHarness f
 			"Flags:\n" +
 			fmt.Sprintf("  %-28s %s\n", harnessModelFlag+" <id>", "Model to use for this run (any Requesty model id)") +
 			fmt.Sprintf("  %-28s %s\n", harnessEffortFlag+" <level>", "Reasoning effort: "+strings.Join(harnesses.Efforts, ", ")) +
-			fmt.Sprintf("  %-28s %s", "-h, --help", "Show this help"),
+			fmt.Sprintf("  %-28s %s\n\n", "-h, --help", "Show this help") +
+			fmt.Sprintf("Anything else, or everything after `--`, is passed to `%s` untouched.\n\n", binary),
 		// We take over parsing so harness flags are never interpreted as ours.
 		DisableFlagParsing:    true,
 		DisableFlagsInUseLine: true,
@@ -67,21 +67,17 @@ func newHarnessCommand(env environment, binary, displayName string, newHarness f
 				return err
 			}
 
-			if env.config.APIKey == "" {
-				return fmt.Errorf("no Requesty API key configured; run `requesty` to set one up")
+			cfg, err := env.ensureAPIKey(cmd, displayName)
+			if err != nil {
+				return err
 			}
 
-			harness, err := newHarness()
+			harness, err := newHarness(cfg)
 			if err != nil {
 				return fmt.Errorf("failed to set up %s: %w", displayName, err)
 			}
 
-			launch := env.launchHarness
-			if launch == nil {
-				launch = harnesses.Harness.Launch
-			}
-
-			return launch(harness, opts)
+			return harness.Launch(opts)
 		},
 	}
 
@@ -151,13 +147,3 @@ func setHarnessFlag(opts *harnesses.LaunchOptions, flag, value string) error {
 
 	return nil
 }
-
-// withRouterDefault fills in the production router when the config predates
-// the field, so a launch never hands a harness an empty base URL.
-func withRouterDefault(cfg config.Config) config.Config {
-	if cfg.RouterBaseURL == "" {
-		cfg.RouterBaseURL = config.DefaultRouterBaseURL
-	}
-
-	return cfg
-}
diff --git a/cmd/harness_test.go b/cmd/harness_test.go
index eab1430..d73aaa8 100644
--- a/cmd/harness_test.go
+++ b/cmd/harness_test.go
@@ -10,25 +10,6 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-type recordedLaunch struct {
-	harness harnesses.Harness
-	opts    harnesses.LaunchOptions
-	called  bool
-}
-
-func recordingEnvironment(cfg config.Config) (environment, *recordedLaunch) {
-	recorded := &recordedLaunch{}
-	env := environment{
-		config: cfg,
-		launchHarness: func(harness harnesses.Harness, opts harnesses.LaunchOptions) error {
-			recorded.harness, recorded.opts, recorded.called = harness, opts, true
-			return nil
-		},
-	}
-
-	return env, recorded
-}
-
 func TestHarnessCommandsAreRegistered(t *testing.T) {
 	command := newRootCommand(environment{})
 
@@ -40,87 +21,121 @@ func TestHarnessCommandsAreRegistered(t *testing.T) {
 	}
 }
 
-func TestHarnessCommandPassesLeadingFlagsAndPassthrough(t *testing.T) {
-	env, recorded := recordingEnvironment(config.Config{APIKey: "my-api-key"})
-	command := newRootCommand(env)
-	command.SetArgs([]string{"claude", "--model", "anthropic/claude-fable-5", "--reasoning-effort=high", "--dangerously-skip-permissions", "-p", "hi"})
-
-	require.NoError(t, command.Execute())
-
-	require.True(t, recorded.called)
-	assert.Equal(t, "Claude Code", recorded.harness.Name())
-	assert.Equal(t, "anthropic/claude-fable-5", recorded.opts.Model)
-	assert.Equal(t, harnesses.EffortHigh, recorded.opts.Effort)
-	assert.Equal(t, []string{"--dangerously-skip-permissions", "-p", "hi"}, recorded.opts.Args)
-}
-
-func TestHarnessCommandStopsAtFirstForeignArgument(t *testing.T) {
-	env, recorded := recordingEnvironment(config.Config{APIKey: "my-api-key"})
-	command := newRootCommand(env)
-	// The second --model belongs to codex because a codex flag came first.
-	command.SetArgs([]string{"codex", "--full-auto", "--model", "theirs"})
-
-	require.NoError(t, command.Execute())
-
-	assert.Empty(t, recorded.opts.Model)
-	assert.Equal(t, []string{"--full-auto", "--model", "theirs"}, recorded.opts.Args)
-}
-
-func TestHarnessCommandDoubleDashEndsOurFlags(t *testing.T) {
-	env, recorded := recordingEnvironment(config.Config{APIKey: "my-api-key"})
-	command := newRootCommand(env)
-	command.SetArgs([]string{"codex", "--model", "openai/gpt-5", "--", "--model", "theirs"})
+func TestParseHarnessArgs(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+		want harnesses.LaunchOptions
+	}{
+		{
+			name: "no arguments",
+			args: nil,
+			want: harnesses.LaunchOptions{},
+		},
+		{
+			name: "leading flags then passthrough",
+			args: []string{"--model", "anthropic/claude-fable-5", "--reasoning-effort=high", "--dangerously-skip-permissions", "-p", "hi"},
+			want: harnesses.LaunchOptions{
+				Model:  "anthropic/claude-fable-5",
+				Effort: harnesses.EffortHigh,
+				Args:   []string{"--dangerously-skip-permissions", "-p", "hi"},
+			},
+		},
+		{
+			name: "equals form for both flags",
+			args: []string{"--model=openai/gpt-5", "--reasoning-effort=low"},
+			want: harnesses.LaunchOptions{Model: "openai/gpt-5", Effort: harnesses.EffortLow},
+		},
+		{
+			// The second --model belongs to the harness because a foreign flag came first.
+			name: "stops at first foreign argument",
+			args: []string{"--full-auto", "--model", "theirs"},
+			want: harnesses.LaunchOptions{Args: []string{"--full-auto", "--model", "theirs"}},
+		},
+		{
+			name: "double dash ends our flags",
+			args: []string{"--model", "openai/gpt-5", "--", "--model", "theirs"},
+			want: harnesses.LaunchOptions{Model: "openai/gpt-5", Args: []string{"--model", "theirs"}},
+		},
+		{
+			name: "bare double dash passes nothing",
+			args: []string{"--"},
+			want: harnesses.LaunchOptions{Args: []string{}},
+		},
+	}
 
-	require.NoError(t, command.Execute())
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got, err := parseHarnessArgs(tt.args)
 
-	assert.Equal(t, "openai/gpt-5", recorded.opts.Model)
-	assert.Equal(t, []string{"--model", "theirs"}, recorded.opts.Args)
+			require.NoError(t, err)
+			assert.Equal(t, tt.want, got)
+		})
+	}
 }
 
-func TestHarnessCommandRejectsUnknownEffort(t *testing.T) {
-	env, recorded := recordingEnvironment(config.Config{APIKey: "my-api-key"})
-	command := newRootCommand(env)
-	command.SetArgs([]string{"claude", "--reasoning-effort", "turbo"})
-
-	err := command.Execute()
-
-	require.EqualError(t, err, `--reasoning-effort must be one of minimal, low, medium, high, xhigh, max (got "turbo")`)
-	assert.False(t, recorded.called)
-}
+func TestParseHarnessArgsErrors(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{
+			name: "unknown effort",
+			args: []string{"--reasoning-effort", "turbo"},
+			want: `--reasoning-effort must be one of minimal, low, medium, high, xhigh, max (got "turbo")`,
+		},
+		{
+			name: "model without value",
+			args: []string{"--model"},
+			want: "--model requires a value",
+		},
+		{
+			name: "effort without value",
+			args: []string{"--reasoning-effort"},
+			want: "--reasoning-effort requires a value",
+		},
+		{
+			name: "empty equals value",
+			args: []string{"--model="},
+			want: "--model requires a value",
+		},
+		{
+			name: "blank value",
+			args: []string{"--model", "  "},
+			want: "--model requires a value",
+		},
+	}
 
-func TestHarnessCommandRejectsFlagWithoutValue(t *testing.T) {
-	env, recorded := recordingEnvironment(config.Config{APIKey: "my-api-key"})
-	command := newRootCommand(env)
-	command.SetArgs([]string{"claude", "--model"})
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			_, err := parseHarnessArgs(tt.args)
 
-	require.EqualError(t, command.Execute(), "--model requires a value")
-	assert.False(t, recorded.called)
+			require.EqualError(t, err, tt.want)
+		})
+	}
 }
 
-func TestHarnessCommandRequiresAPIKey(t *testing.T) {
-	env, recorded := recordingEnvironment(config.Config{})
-	command := newRootCommand(env)
-	command.SetArgs([]string{"codex"})
+func TestParseHarnessArgsHelp(t *testing.T) {
+	for _, args := range [][]string{{"-h"}, {"--help"}, {"--model", "x", "--help"}} {
+		_, err := parseHarnessArgs(args)
+		assert.ErrorIs(t, err, errHarnessHelp, "%v", args)
+	}
 
-	require.EqualError(t, command.Execute(), "no Requesty API key configured; run `requesty` to set one up")
-	assert.False(t, recorded.called)
+	// After the harness's own flags begin, -h belongs to the harness.
+	got, err := parseHarnessArgs([]string{"-p", "hi", "--help"})
+	require.NoError(t, err)
+	assert.Equal(t, []string{"-p", "hi", "--help"}, got.Args)
 }
 
-func TestHarnessCommandHelpDoesNotLaunch(t *testing.T) {
-	env, recorded := recordingEnvironment(config.Config{APIKey: "my-api-key"})
-	command := newRootCommand(env)
+func TestHarnessCommandHelpShowsOurFlags(t *testing.T) {
+	command := newRootCommand(environment{config: config.Config{APIKey: "my-api-key"}})
 	var output bytes.Buffer
 	command.SetOut(&output)
 	command.SetArgs([]string{"claude", "--help"})
 
 	require.NoError(t, command.Execute())
 
-	assert.False(t, recorded.called)
 	assert.Contains(t, output.String(), "--reasoning-effort")
 	assert.Contains(t, output.String(), "passed to `claude`")
 }
-
-func TestWithRouterDefaultFillsMissingURL(t *testing.T) {
-	assert.Equal(t, config.DefaultRouterBaseURL, withRouterDefault(config.Config{APIKey: "k"}).RouterBaseURL)
-	assert.Equal(t, "https://router.example.test", withRouterDefault(config.Config{RouterBaseURL: "https://router.example.test"}).RouterBaseURL)
-}
diff --git a/cmd/login.go b/cmd/login.go
index d35bd70..6ec24b8 100644
--- a/cmd/login.go
+++ b/cmd/login.go
@@ -1,58 +1,100 @@
 package cmd
 
 import (
+	"errors"
 	"fmt"
-	"strings"
 
-	"github.com/requestyai/cli/internal/oauth"
+	"github.com/requestyai/cli/internal/client"
+	"github.com/requestyai/cli/internal/config"
+	"github.com/requestyai/cli/internal/onboarding"
 	"github.com/spf13/cobra"
 )
 
 const (
-	loginPrintTokenFlag = "print-token"
+	loginGroupFlag  = "group"
+	loginForceFlag  = "force"
+	loginAPIKeyFlag = "api-key"
 )
 
+var errUnrecognisedAPIKey = errors.New("that API key was not recognised; copy it again from " + onboarding.APIKeysURL)
+
 func newLoginCommand(env environment) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "login",
-		Short: "Sign in to Requesty in your browser",
-		Long: "Sign in to Requesty in your browser.\n\n" +
-			"The CLI opens the Requesty consent page and, once you approve, receives a\n" +
-			"short-lived token on this machine. Nothing is written to disk.",
+		Use:   "login [--group <name>] [--api-key <key>] [--force]",
+		Short: "Sign in to Requesty and set this machine up",
+		Long: "Sign in to Requesty in your browser and set this machine up.\n\n" +
+			"Once you approve in the browser, the CLI creates an API key in your Requesty\n" +
+			"account and saves it to " + config.DisplayPath() + ", where `requesty claude`,\n" +
+			"`requesty codex` and the terminal app pick it up. The key is named after this\n" +
+			"machine so you can recognise it on " + onboarding.APIKeysURL + ".\n\n" +
+			"The key goes in your group. With several groups you are asked which, or you can\n" +
+			"name one with --group. Without any group the key is a personal one.\n\n" +
+			"The browser hands the sign-in back to this machine on 127.0.0.1, which does not\n" +
+			"work over SSH. There, pass --api-key with a key from " + onboarding.APIKeysURL + "\n" +
+			"instead; it is checked against the gateway and saved.\n\n" +
+			"When a working key is already saved nothing is created; pass --force to replace\n" +
+			"it with a new one.",
 		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
-			login := env.login
-			if login == nil {
-				login = oauth.Login
-			}
+			groupID, _ := cmd.Flags().GetString(loginGroupFlag)
+			apiKey, _ := cmd.Flags().GetString(loginAPIKeyFlag)
+			force, _ := cmd.Flags().GetBool(loginForceFlag)
 
-			token, err := login(cmd.Context(), oauth.Options{
-				APIBaseURL: env.config.ResolveAPIBaseURL(),
-				Status:     cmd.ErrOrStderr(),
-			})
-			if err != nil {
-				return err
+			if env.config.APIKey != "" && !force {
+				err := env.apiv2Client.CheckAPIKey(cmd.Context())
+				switch {
+				case err == nil:
+					_, err := fmt.Fprintf(cmd.OutOrStdout(),
+						"Already signed in: an API key is saved in %s.\nRun `requesty login --force` to replace it with a new one.\n",
+						config.DisplayPath())
+					return err
+				case errors.Is(err, client.ErrInvalidAPIKey):
+					_, _ = fmt.Fprintln(cmd.ErrOrStderr(), "The saved API key is no longer valid; signing in again.")
+				default:
+					return fmt.Errorf("failed to check the saved API key: %w", err)
+				}
 			}
 
-			out := cmd.OutOrStdout()
-			if _, err := fmt.Fprintln(out, "Signed in to Requesty."); err != nil {
-				return err
+			if apiKey != "" {
+				return env.saveAPIKey(cmd, apiKey)
 			}
 
-			fields := [][2]string{
-				{"Scopes", strings.Join(token.Scopes(), " ")},
-				{"Expires in", token.ExpiresIn.String()},
-			}
-			if printToken, _ := cmd.Flags().GetBool(loginPrintTokenFlag); printToken {
-				fields = append(fields, [2]string{"Access token", token.AccessToken})
-			}
+			_, err := onboarding.RunHeadless(cmd.Context(), onboarding.Options{
+				Config:  env.config,
+				GroupID: groupID,
+			})
 
-			return writeFields(out, fields)
+			return err
 		},
 	}
 
-	cmd.Flags().Bool(loginPrintTokenFlag, false, "print the access token for manual testing")
-	_ = cmd.Flags().MarkHidden(loginPrintTokenFlag)
+	cmd.Flags().String(loginGroupFlag, "", "group to create the API key in, by name or id")
+	cmd.Flags().String(loginAPIKeyFlag, "", "save an existing API key instead of signing in")
+	cmd.Flags().Bool(loginForceFlag, false, "create a new API key even when one is already saved")
 
 	return cmd
 }
+
+// saveAPIKey stores a key the user already has, once the gateway confirms it
+// is live. This is the route for machines where the browser cannot hand the
+// sign-in back, such as over SSH.
+func (env environment) saveAPIKey(cmd *cobra.Command, apiKey string) error {
+	cfg := env.config
+	cfg.APIKey = apiKey
+
+	err := client.New(cfg).CheckAPIKey(cmd.Context())
+	if errors.Is(err, client.ErrInvalidAPIKey) {
+		return errUnrecognisedAPIKey
+	}
+	if err != nil {
+		return fmt.Errorf("failed to check the api key: %w", err)
+	}
+
+	if err := config.Save(cfg); err != nil {
+		return fmt.Errorf("failed to save config: %w", err)
+	}
+
+	_, err = fmt.Fprintf(cmd.OutOrStdout(), "Saved your API key to %s.\n", config.DisplayPath())
+
+	return err
+}
diff --git a/cmd/login_test.go b/cmd/login_test.go
index 09aaed4..2e7d708 100644
--- a/cmd/login_test.go
+++ b/cmd/login_test.go
@@ -2,94 +2,101 @@ package cmd
 
 import (
 	"bytes"
-	"context"
-	"errors"
+	"net/http"
+	"net/http/httptest"
 	"testing"
-	"time"
 
+	"github.com/requestyai/cli/internal/client"
 	"github.com/requestyai/cli/internal/config"
-	"github.com/requestyai/cli/internal/oauth"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
-func TestLoginPrintsScopesAndExpiry(t *testing.T) {
-	var gotOptions oauth.Options
+// checkServer answers /v1/auth/check with status, standing in for the gateway
+// when a login has to decide whether the saved key still works.
+func checkServer(t *testing.T, status int) *httptest.Server {
+	t.Helper()
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/v1/auth/check", r.URL.Path)
+		w.WriteHeader(status)
+	}))
+	t.Cleanup(server.Close)
+
+	return server
+}
+
+func loginEnvironment(cfg config.Config) environment {
+	return environment{config: cfg, apiv2Client: client.New(cfg)}
+}
+
+func TestLoginDoesNothingWhenKeyStillWorks(t *testing.T) {
+	server := checkServer(t, http.StatusOK)
+	env := loginEnvironment(config.Config{APIKey: "rqsty-old", RouterBaseURL: server.URL})
 	var output bytes.Buffer
-	command := newRootCommand(environment{
-		config: config.Config{APIBaseURL: "http://localhost:40003"},
-		login: func(_ context.Context, opts oauth.Options) (*oauth.Token, error) {
-			gotOptions = opts
-			return &oauth.Token{
-				AccessToken: "secret-token",
-				TokenType:   "Bearer",
-				Scope:       "manage:group:r manage:apikey:w",
-				ExpiresIn:   5 * time.Minute,
-			}, nil
-		},
-	})
+	command := newRootCommand(env)
 	command.SetOut(&output)
 	command.SetArgs([]string{"login"})
 
 	require.NoError(t, command.Execute())
 
-	assert.Equal(t, "http://localhost:40003", gotOptions.APIBaseURL)
-	assert.NotNil(t, gotOptions.Status)
-	assert.Equal(t,
-		"Signed in to Requesty.\n"+
-			"Scopes      manage:group:r manage:apikey:w\n"+
-			"Expires in  5m0s\n",
-		output.String())
-	assert.NotContains(t, output.String(), "secret-token")
+	assert.Contains(t, output.String(), "Already signed in")
+	assert.Contains(t, output.String(), "requesty login --force")
 }
 
-func TestLoginDefaultsToProductionAPI(t *testing.T) {
-	var gotOptions oauth.Options
-	command := newRootCommand(environment{
-		login: func(_ context.Context, opts oauth.Options) (*oauth.Token, error) {
-			gotOptions = opts
-			return &oauth.Token{AccessToken: "t", ExpiresIn: time.Minute}, nil
-		},
-	})
-	command.SetOut(&bytes.Buffer{})
+func TestLoginReportsCheckFailure(t *testing.T) {
+	server := checkServer(t, http.StatusBadGateway)
+	env := loginEnvironment(config.Config{APIKey: "rqsty-old", RouterBaseURL: server.URL})
+	command := newRootCommand(env)
 	command.SetArgs([]string{"login"})
 
-	require.NoError(t, command.Execute())
-	assert.Equal(t, config.DefaultAPIBaseURL, gotOptions.APIBaseURL)
+	err := command.Execute()
+
+	require.ErrorContains(t, err, "failed to check the saved API key")
 }
 
-func TestLoginPrintTokenFlagRevealsToken(t *testing.T) {
+func TestLoginSavesAValidatedAPIKey(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	server := checkServer(t, http.StatusOK)
+	env := loginEnvironment(config.Config{RouterBaseURL: server.URL})
 	var output bytes.Buffer
-	command := newRootCommand(environment{
-		login: func(context.Context, oauth.Options) (*oauth.Token, error) {
-			return &oauth.Token{AccessToken: "secret-token", Scope: "manage:group:r", ExpiresIn: time.Minute}, nil
-		},
-	})
+	command := newRootCommand(env)
 	command.SetOut(&output)
-	command.SetArgs([]string{"login", "--print-token"})
+	command.SetArgs([]string{"login", "--api-key", "rqsty-existing"})
 
 	require.NoError(t, command.Execute())
-	assert.Contains(t, output.String(), "Access token  secret-token\n")
+
+	saved, err := config.Load()
+	require.NoError(t, err)
+	assert.Equal(t, config.Config{
+		APIKey:        "rqsty-existing",
+		RouterBaseURL: server.URL,
+	}, saved, "the key is added to the loaded config, which is otherwise saved as it was")
+	assert.Contains(t, output.String(), "Saved your API key")
+	assert.NotContains(t, output.String(), "rqsty-existing")
 }
 
-func TestLoginPrintTokenFlagIsHidden(t *testing.T) {
-	command := newRootCommand(environment{})
+func TestLoginRejectsAnUnrecognisedAPIKey(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	server := checkServer(t, http.StatusUnauthorized)
+	env := loginEnvironment(config.Config{RouterBaseURL: server.URL})
+	command := newRootCommand(env)
+	command.SetArgs([]string{"login", "--api-key", "rqsty-typo"})
 
-	login, _, err := command.Find([]string{"login"})
-	require.NoError(t, err)
+	require.ErrorIs(t, command.Execute(), errUnrecognisedAPIKey)
 
-	flag := login.Flags().Lookup(loginPrintTokenFlag)
-	require.NotNil(t, flag)
-	assert.True(t, flag.Hidden)
+	saved, err := config.Load()
+	require.NoError(t, err)
+	assert.Empty(t, saved.APIKey, "a rejected key must not be written")
 }
 
-func TestLoginReportsFailure(t *testing.T) {
-	command := newRootCommand(environment{
-		login: func(context.Context, oauth.Options) (*oauth.Token, error) {
-			return nil, errors.New("sign-in was not completed: access_denied")
-		},
-	})
-	command.SetArgs([]string{"login"})
+func TestLoginFlagsAreRegistered(t *testing.T) {
+	command := newRootCommand(environment{})
+
+	login, _, err := command.Find([]string{"login"})
+	require.NoError(t, err)
 
-	require.EqualError(t, command.Execute(), "sign-in was not completed: access_denied")
+	for _, name := range []string{loginGroupFlag, loginAPIKeyFlag, loginForceFlag} {
+		assert.NotNil(t, login.Flags().Lookup(name), "missing --%s", name)
+	}
 }
diff --git a/cmd/requesty.go b/cmd/requesty.go
index 78ceafd..cf565f4 100644
--- a/cmd/requesty.go
+++ b/cmd/requesty.go
@@ -1,14 +1,12 @@
 package cmd
 
 import (
-	"context"
 	"fmt"
 
 	tea "charm.land/bubbletea/v2"
 	"github.com/requestyai/cli/internal/client"
 	"github.com/requestyai/cli/internal/config"
-	"github.com/requestyai/cli/internal/harnesses"
-	"github.com/requestyai/cli/internal/oauth"
+	"github.com/requestyai/cli/internal/onboarding"
 	"github.com/requestyai/cli/internal/tui"
 	"github.com/spf13/cobra"
 )
@@ -23,19 +21,10 @@ func Run() error {
 	return newRootCommand(env).Execute()
 }
 
-// environment is everything the commands need from the outside world, kept
-// behind function fields so tests can stand in for the gateway and the UI.
+// environment is the loaded config and the gateway client the commands share.
 type environment struct {
 	config      config.Config
 	apiv2Client *client.Client
-
-	// login runs the browser sign-in. nil means the real OAuth flow.
-	login func(context.Context, oauth.Options) (*oauth.Token, error)
-
-	// launchHarness starts a harness through Requesty. nil means the harness's
-	// own Launch, which replaces the current process and so cannot run under
-	// a test.
-	launchHarness func(harnesses.Harness, harnesses.LaunchOptions) error
 }
 
 func newEnvironment() (environment, error) {
@@ -45,13 +34,25 @@ func newEnvironment() (environment, error) {
 	}
 
 	return environment{
-		config:        cfg,
-		apiv2Client:   client.New(cfg),
-		login:         oauth.Login,
-		launchHarness: harnesses.Harness.Launch,
+		config:      cfg,
+		apiv2Client: client.New(cfg),
 	}, nil
 }
 
+// ensureAPIKey is the config to launch with, onboarding first when no key is
+// saved yet. harness is the display name of the harness about to start, or
+// empty for the dashboard.
+func (env environment) ensureAPIKey(cmd *cobra.Command, harness string) (config.Config, error) {
+	if env.config.APIKey != "" {
+		return env.config, nil
+	}
+
+	return onboarding.Run(cmd.Context(), onboarding.Options{
+		Config:  env.config,
+		Harness: harness,
+	})
+}
+
 func newRootCommand(env environment) *cobra.Command {
 	root := &cobra.Command{
 		Use:   "requesty",
@@ -62,8 +63,13 @@ func newRootCommand(env environment) *cobra.Command {
 		Args:          cobra.NoArgs,
 		SilenceUsage:  true,
 		SilenceErrors: true,
-		RunE: func(_ *cobra.Command, _ []string) error {
-			if _, err := tea.NewProgram(tui.NewRoot(env.config)).Run(); err != nil {
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			cfg, err := env.ensureAPIKey(cmd, "")
+			if err != nil {
+				return err
+			}
+
+			if _, err := tea.NewProgram(tui.NewRoot(cfg)).Run(); err != nil {
 				return fmt.Errorf("failed to run program: %w", err)
 			}
 
diff --git a/internal/client/api_keys.go b/internal/client/api_keys.go
index 89c6d2e..cee4cd7 100644
--- a/internal/client/api_keys.go
+++ b/internal/client/api_keys.go
@@ -71,6 +71,7 @@ type CreateAPIKeyInput struct {
 	Name         string
 	MonthlyLimit *decimal.Decimal
 	Permissions  *APIKeyPermissions
+	GroupID      string
 }
 
 // CreatedAPIKey carries the secret the API returns once and never again.
@@ -122,10 +123,12 @@ func (c *Client) CreateAPIKey(ctx context.Context, input CreateAPIKeyInput) (Cre
 		Name         string             `json:"name"`
 		MonthlyLimit *decimal.Decimal   `json:"monthly_limit,omitempty"`
 		Permissions  *APIKeyPermissions `json:"permissions,omitempty"`
+		GroupID      string             `json:"group_id,omitempty"`
 	}{
 		Name:         input.Name,
 		MonthlyLimit: input.MonthlyLimit,
 		Permissions:  input.Permissions,
+		GroupID:      input.GroupID,
 	}
 
 	var created CreatedAPIKey
diff --git a/internal/client/api_keys_test.go b/internal/client/api_keys_test.go
index 0e6e7d2..25e64d9 100644
--- a/internal/client/api_keys_test.go
+++ b/internal/client/api_keys_test.go
@@ -48,7 +48,7 @@ func newTestClient(t *testing.T, status int, reply string) (*Client, *recorder)
 	}))
 	t.Cleanup(server.Close)
 
-	return New(config.Config{APIBaseURL: server.URL, APIKey: "test-key"}), seen
+	return New(config.Config{RouterBaseURL: server.URL, APIKey: "test-key"}), seen
 }
 
 func mustParseTime(t *testing.T, value string) *time.Time {
@@ -135,6 +135,15 @@ func TestClientCreateAPIKey(t *testing.T) {
 	assert.Equal(t, CreatedAPIKey{ID: "key-1", Secret: "rqsty-secret"}, created)
 }
 
+func TestClientCreateAPIKeyInGroup(t *testing.T) {
+	client, seen := newTestClient(t, http.StatusOK, `{"api_key_id":"key-1","api_key":"rqsty-secret"}`)
+
+	_, err := client.CreateAPIKey(context.Background(), CreateAPIKeyInput{Name: "cli", GroupID: "group-1"})
+
+	require.NoError(t, err)
+	assert.JSONEq(t, `{"name":"cli","group_id":"group-1"}`, seen.body)
+}
+
 func TestClientCreateAPIKeyOmitsUnsetFields(t *testing.T) {
 	client, seen := newTestClient(t, http.StatusOK, `{"api_key_id":"key-1","api_key":"rqsty-secret"}`)
 
@@ -245,7 +254,7 @@ func TestClientAPIKeysUnauthenticated(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := New(config.Config{APIBaseURL: server.URL})
+	client := New(config.Config{RouterBaseURL: server.URL})
 	keys, err := client.APIKeys(context.Background())
 
 	require.NoError(t, err)
@@ -261,7 +270,7 @@ func TestClientCreateAPIKeySendsJSONContentType(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := New(config.Config{APIBaseURL: server.URL, APIKey: "test-key"})
+	client := New(config.Config{RouterBaseURL: server.URL, APIKey: "test-key"})
 	_, err := client.CreateAPIKey(context.Background(), CreateAPIKeyInput{Name: "production"})
 
 	require.NoError(t, err)
diff --git a/internal/client/auth.go b/internal/client/auth.go
index 1f57483..f00cfa7 100644
--- a/internal/client/auth.go
+++ b/internal/client/auth.go
@@ -13,12 +13,7 @@ var ErrInvalidAPIKey = errors.New("invalid api key")
 // CheckAPIKey asks the gateway whether the configured key is a live one of its
 // own, rejecting a key that was never issued, was deleted, or has expired.
 func (c *Client) CheckAPIKey(ctx context.Context) error {
-	apiBaseURL, err := c.apiBaseURL()
-	if err != nil {
-		return fmt.Errorf("failed to get api base url: %w", err)
-	}
-
-	req, err := http.NewRequestWithContext(ctx, http.MethodGet, apiBaseURL+"/v1/auth/check", nil)
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, c.config.APIBaseURL()+"/v1/auth/check", nil)
 	if err != nil {
 		return fmt.Errorf("failed to create request: %w", err)
 	}
diff --git a/internal/client/auth_test.go b/internal/client/auth_test.go
index 55ee948..14d95ee 100644
--- a/internal/client/auth_test.go
+++ b/internal/client/auth_test.go
@@ -31,7 +31,7 @@ func TestClientCheckAPIKey(t *testing.T) {
 			}))
 			defer server.Close()
 
-			client := New(config.Config{APIBaseURL: server.URL, APIKey: "test-key"})
+			client := New(config.Config{RouterBaseURL: server.URL, APIKey: "test-key"})
 			err := client.CheckAPIKey(context.Background())
 
 			if tc.wantErr == nil {
@@ -49,7 +49,7 @@ func TestClientCheckAPIKeyUnexpectedStatus(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := New(config.Config{APIBaseURL: server.URL, APIKey: "test-key"})
+	client := New(config.Config{RouterBaseURL: server.URL, APIKey: "test-key"})
 	err := client.CheckAPIKey(context.Background())
 
 	require.Error(t, err)
diff --git a/internal/client/client.go b/internal/client/client.go
index ed35c38..2ae0508 100644
--- a/internal/client/client.go
+++ b/internal/client/client.go
@@ -30,10 +30,6 @@ func New(cfg config.Config) *Client {
 	}
 }
 
-func (c *Client) apiBaseURL() (string, error) {
-	return c.config.ResolveAPIBaseURL(), nil
-}
-
 func (c *Client) authorize(req *http.Request) {
 	if c.config.APIKey != "" {
 		req.Header.Set("Authorization", "Bearer "+c.config.APIKey)
@@ -43,17 +39,12 @@ func (c *Client) authorize(req *http.Request) {
 // manageURL builds a management API address. Each element is escaped, so an
 // identifier that came from a user cannot reach into another path.
 func (c *Client) manageURL(elements ...string) (string, error) {
-	apiBaseURL, err := c.apiBaseURL()
-	if err != nil {
-		return "", fmt.Errorf("failed to get api base url: %w", err)
-	}
-
 	escaped := make([]string, 0, len(elements))
 	for _, element := range elements {
 		escaped = append(escaped, url.PathEscape(element))
 	}
 
-	endpoint := fmt.Sprintf("%s/v1/manage/%s", apiBaseURL, strings.Join(escaped, "/"))
+	endpoint := fmt.Sprintf("%s/v1/manage/%s", c.config.APIBaseURL(), strings.Join(escaped, "/"))
 	return endpoint, nil
 }
 
diff --git a/internal/client/usage.go b/internal/client/usage.go
index 8342f4f..1cc9f70 100644
--- a/internal/client/usage.go
+++ b/internal/client/usage.go
@@ -49,12 +49,7 @@ type UsageInput struct {
 // Usage returns the organization's usage for the requested period.
 // If End or Resolution is unset, the API's defaults are used.
 func (c *Client) Usage(ctx context.Context, input UsageInput) (map[string]UsageEntry, error) {
-	apiBaseURL, err := c.apiBaseURL()
-	if err != nil {
-		return nil, fmt.Errorf("failed to get api base url: %w", err)
-	}
-
-	endpoint, err := url.Parse(fmt.Sprintf("%s/v1/manage/apikey/self/usage", apiBaseURL))
+	endpoint, err := url.Parse(fmt.Sprintf("%s/v1/manage/apikey/self/usage", c.config.APIBaseURL()))
 	if err != nil {
 		return nil, fmt.Errorf("failed to parse url: %w", err)
 	}
diff --git a/internal/client/usage_test.go b/internal/client/usage_test.go
index f6e8d9e..a2caf0c 100644
--- a/internal/client/usage_test.go
+++ b/internal/client/usage_test.go
@@ -30,7 +30,7 @@ func TestClientUsage(t *testing.T) {
 	}))
 	defer server.Close()
 
-	client := New(config.Config{APIBaseURL: server.URL, APIKey: "test-key"})
+	client := New(config.Config{RouterBaseURL: server.URL, APIKey: "test-key"})
 	usage, err := client.Usage(context.Background(), UsageInput{
 		Start:      start,
 		End:        end,
diff --git a/internal/config/config.go b/internal/config/config.go
index d186ce1..e17f1ad 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -22,42 +22,50 @@ const (
 type Config struct {
 	APIKey        string `json:"api_key"`
 	RouterBaseURL string `json:"router_base_url"`
-	APIBaseURL    string `json:"api_base_url,omitempty"`
 }
 
-// ResolveAPIBaseURL returns the management API address: the configured one,
-// else the one implied by the router address, else the production default.
-// The fallback matters before onboarding, when the config file does not exist.
-func (c Config) ResolveAPIBaseURL() string {
-	if c.APIBaseURL != "" {
-		return c.APIBaseURL
-	}
-	if c.RouterBaseURL != "" {
-		return strings.Replace(c.RouterBaseURL, "router", "api-v2", 1)
+func (c Config) APIBaseURL() string {
+	apiBaseURL := strings.Replace(c.RouterBaseURL, "router", "api-v2", 1)
+	apiBaseURL = strings.Replace(apiBaseURL, "40000", "40003", 1)
+
+	return apiBaseURL
+}
+
+// DisplayPath is where the settings file lives, for messages: the real
+// location when it can be worked out, else the conventional one.
+func DisplayPath() string {
+	path, err := configPath()
+	if err != nil {
+		return "~/" + dirName + "/" + fileName
 	}
 
-	return DefaultAPIBaseURL
+	return path
 }
 
-// Load reads the settings. A missing file is not an error: it means the user
-// has not onboarded yet, so the zero Config comes back.
+// Load reads the settings and fills in the production router when the file
+// leaves it blank. A missing file is not an error: it means the user has not
+// onboarded yet, so the defaults come back with no API key.
 func Load() (Config, error) {
 	path, err := configPath()
 	if err != nil {
 		return Config{}, err
 	}
 
+	var config Config
 	data, err := os.ReadFile(path)
-	if errors.Is(err, fs.ErrNotExist) {
-		return Config{}, nil
-	}
-	if err != nil {
+	switch {
+	case errors.Is(err, fs.ErrNotExist):
+		// Not onboarded yet: defaults only.
+	case err != nil:
 		return Config{}, fmt.Errorf("failed to read config: %w", err)
+	default:
+		if err := json.Unmarshal(data, &config); err != nil {
+			return Config{}, fmt.Errorf("failed to parse config: %w", err)
+		}
 	}
 
-	var config Config
-	if err := json.Unmarshal(data, &config); err != nil {
-		return Config{}, fmt.Errorf("failed to parse config: %w", err)
+	if config.RouterBaseURL == "" {
+		config.RouterBaseURL = DefaultRouterBaseURL
 	}
 
 	return config, nil
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index 0f8505d..63fbcd1 100644
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -1,26 +1,98 @@
 package config
 
 import (
+	"os"
+	"path/filepath"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
-func TestResolveAPIBaseURL(t *testing.T) {
+func TestAPIBaseURL(t *testing.T) {
 	tests := []struct {
 		name   string
-		config Config
+		router string
 		want   string
 	}{
-		{name: "explicit api base url wins", config: Config{APIBaseURL: "http://localhost:40003", RouterBaseURL: "https://router.requesty.ai"}, want: "http://localhost:40003"},
-		{name: "derived from router", config: Config{RouterBaseURL: "https://router.requesty.ai"}, want: "https://api-v2.requesty.ai"},
-		{name: "derived from staging router", config: Config{RouterBaseURL: "https://router.staging.requesty.ai"}, want: "https://api-v2.staging.requesty.ai"},
-		{name: "zero config uses production default", config: Config{}, want: DefaultAPIBaseURL},
+		{name: "production", router: DefaultRouterBaseURL, want: DefaultAPIBaseURL},
+		{name: "staging", router: "https://router.staging.requesty.ai", want: "https://api-v2.staging.requesty.ai"},
+		{name: "local stack moves port", router: "http://localhost:40000", want: "http://localhost:40003"},
+		{name: "local stack by ip", router: "http://127.0.0.1:40000", want: "http://127.0.0.1:40003"},
+		{name: "hostname and port both rewritten", router: "http://router.local:40000", want: "http://api-v2.local:40003"},
+		{name: "other port is left alone", router: "http://127.0.0.1:55123", want: "http://127.0.0.1:55123"},
+		{name: "unrelated host is left alone", router: "https://gateway.example.test", want: "https://gateway.example.test"},
+		{name: "path and trailing slash survive", router: "https://router.requesty.ai/prefix/", want: "https://api-v2.requesty.ai/prefix/"},
+		{name: "router in path is not touched", router: "https://gateway.example.test/router", want: "https://gateway.example.test/router"},
+		{name: "unparseable address comes back as is", router: "http://[::1", want: "http://[::1"},
 	}
 
 	for _, tc := range tests {
 		t.Run(tc.name, func(t *testing.T) {
-			assert.Equal(t, tc.want, tc.config.ResolveAPIBaseURL())
+			assert.Equal(t, tc.want, Config{RouterBaseURL: tc.router}.APIBaseURL())
 		})
 	}
 }
+
+func TestLoad(t *testing.T) {
+	tests := []struct {
+		name string
+		file string // empty means no file on disk
+		want Config
+	}{
+		{
+			name: "missing file gives defaults with no key",
+			want: Config{RouterBaseURL: DefaultRouterBaseURL},
+		},
+		{
+			name: "blank router is filled in, key kept",
+			file: `{"api_key": "rqsty-old"}`,
+			want: Config{APIKey: "rqsty-old", RouterBaseURL: DefaultRouterBaseURL},
+		},
+		{
+			name: "explicit router is returned verbatim",
+			file: `{"api_key": "rqsty-old", "router_base_url": "http://localhost:40000"}`,
+			want: Config{APIKey: "rqsty-old", RouterBaseURL: "http://localhost:40000"},
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			home := t.TempDir()
+			t.Setenv("HOME", home)
+			if tc.file != "" {
+				dir := filepath.Join(home, dirName)
+				require.NoError(t, os.MkdirAll(dir, 0o700))
+				require.NoError(t, os.WriteFile(filepath.Join(dir, fileName), []byte(tc.file), 0o600))
+			}
+
+			got, err := Load()
+
+			require.NoError(t, err)
+			assert.Equal(t, tc.want, got)
+		})
+	}
+}
+
+func TestLoadRejectsMalformedFile(t *testing.T) {
+	home := t.TempDir()
+	t.Setenv("HOME", home)
+	dir := filepath.Join(home, dirName)
+	require.NoError(t, os.MkdirAll(dir, 0o700))
+	require.NoError(t, os.WriteFile(filepath.Join(dir, fileName), []byte("{not json"), 0o600))
+
+	_, err := Load()
+
+	require.ErrorContains(t, err, "failed to parse config")
+}
+
+func TestSaveRoundTrips(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	want := Config{APIKey: "rqsty-new", RouterBaseURL: "http://localhost:40000"}
+
+	require.NoError(t, Save(want))
+	got, err := Load()
+
+	require.NoError(t, err)
+	assert.Equal(t, want, got)
+}
diff --git a/internal/oauth/flow.go b/internal/oauth/flow.go
index bca5ead..a93f978 100644
--- a/internal/oauth/flow.go
+++ b/internal/oauth/flow.go
@@ -57,6 +57,10 @@ type Options struct {
 	// launcher. A failure is reported on Status but does not abort the login.
 	OpenBrowser func(url string) error
 
+	// OnAuthorizeURL, when set, is told the address the browser is sent to,
+	// for front ends that draw it themselves rather than reading Status.
+	OnAuthorizeURL func(url string)
+
 	// HTTPClient sends the token request. Defaults to one with a timeout.
 	HTTPClient *http.Client
 }
@@ -100,6 +104,9 @@ func Login(ctx context.Context, opts Options) (*Token, error) {
 
 	redirectURI := server.RedirectURI()
 	authorizeURL := authorizeURL(apiBaseURL, redirectURI, state, Challenge(verifier))
+	if opts.OnAuthorizeURL != nil {
+		opts.OnAuthorizeURL(authorizeURL)
+	}
 
 	_, _ = fmt.Fprintf(status,
 		"Opening your browser to sign in to Requesty.\n\nIf it does not open, visit this address:\n\n  %s\n\n",
diff --git a/internal/oauth/flow_test.go b/internal/oauth/flow_test.go
index 96ae88a..69ea04f 100644
--- a/internal/oauth/flow_test.go
+++ b/internal/oauth/flow_test.go
@@ -97,10 +97,12 @@ func TestLoginCompletesAuthorizationCodeFlow(t *testing.T) {
 	defer server.Close()
 
 	var status bytes.Buffer
+	var told string
 	token, err := Login(context.Background(), Options{
-		APIBaseURL:  server.URL + "/",
-		Status:      &status,
-		OpenBrowser: fakeBrowser(t),
+		APIBaseURL:     server.URL + "/",
+		Status:         &status,
+		OpenBrowser:    fakeBrowser(t),
+		OnAuthorizeURL: func(url string) { told = url },
 	})
 	require.NoError(t, err)
 
@@ -137,8 +139,10 @@ func TestLoginCompletesAuthorizationCodeFlow(t *testing.T) {
 	// The verifier the CLI redeemed is the one behind the challenge it sent.
 	assert.Equal(t, auth.authorize.Get("code_challenge"), Challenge(auth.tokenForm.Get("code_verifier")))
 
-	// The URL is always printed so headless users can paste it.
+	// The URL is always printed so headless users can paste it, and handed to
+	// any front end that wants to draw it.
 	assert.Contains(t, status.String(), server.URL+"/v1/oauth/authorize?")
+	assert.True(t, strings.HasPrefix(told, server.URL+"/v1/oauth/authorize?"), told)
 }
 
 func TestLoginReportsDeniedConsent(t *testing.T) {
diff --git a/internal/onboarding/flow.go b/internal/onboarding/flow.go
new file mode 100644
index 0000000..86e9af3
--- /dev/null
+++ b/internal/onboarding/flow.go
@@ -0,0 +1,180 @@
+package onboarding
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"os"
+	"strings"
+
+	"github.com/requestyai/cli/internal/client"
+	"github.com/requestyai/cli/internal/config"
+	"github.com/requestyai/cli/internal/oauth"
+)
+
+// APIKeysURL is where keys are managed once created.
+const APIKeysURL = "https://app.requesty.ai/api-keys"
+
+var (
+	errGroupChoiceRequired = errors.New("choose a group for the API key")
+	errGroupNotFound       = errors.New("group not found")
+)
+
+// Options configures onboarding. Only Config is needed.
+type Options struct {
+	// Config is the current settings; the new key is added to it.
+	Config config.Config
+	// GroupID picks the group for the key by id or name instead of asking.
+	GroupID string
+	// Harness is the display name of the harness that starts once the key is
+	// saved, set only by `requesty <harness>`.
+	Harness string
+}
+
+// defaultKeyName is what the created key is called, so it can be recognised on
+// the API keys page: the CLI plus this machine's hostname.
+func defaultKeyName() string {
+	host, _ := os.Hostname()
+	return keyNameFor(host)
+}
+
+type result struct {
+	Config  config.Config
+	KeyName string
+	Group   *client.Group
+}
+
+// session is a browser sign-in that has not yet created a key.
+type session struct {
+	opts   Options
+	api    *client.Client
+	groups []client.Group
+}
+
+func signIn(ctx context.Context, opts Options, onAuthorizeURL func(string)) (*session, error) {
+	var status io.Writer = os.Stderr
+	if onAuthorizeURL != nil {
+		// The interactive UI owns progress output and displays the URL itself.
+		status = io.Discard
+	}
+	token, err := oauth.Login(ctx, oauth.Options{
+		APIBaseURL:     opts.Config.APIBaseURL(),
+		Status:         status,
+		OnAuthorizeURL: onAuthorizeURL,
+	})
+	if err != nil {
+		return nil, err
+	}
+
+	authConfig := opts.Config
+	authConfig.APIKey = token.AccessToken
+	api := client.New(authConfig)
+	groups, err := api.Groups(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("failed to list groups: %w", err)
+	}
+
+	return &session{opts: opts, api: api, groups: groups}, nil
+}
+
+func (s *session) chooseGroup() (*client.Group, error) {
+	if s.opts.GroupID != "" {
+		group, ok := findGroup(s.groups, s.opts.GroupID)
+		if !ok {
+			return nil, fmt.Errorf("%w: %q is not one of your groups", errGroupNotFound, s.opts.GroupID)
+		}
+		return group, nil
+	}
+
+	switch len(s.groups) {
+	case 0:
+		return nil, nil
+	case 1:
+		return &s.groups[0], nil
+	default:
+		return nil, fmt.Errorf("%w: you belong to %d groups (%s)",
+			errGroupChoiceRequired, len(s.groups), strings.Join(groupNames(s.groups), ", "))
+	}
+}
+
+func (s *session) createKey(ctx context.Context, group *client.Group) (result, error) {
+	name := defaultKeyName()
+	input := client.CreateAPIKeyInput{Name: name}
+	if group != nil {
+		input.GroupID = group.ID
+	}
+	created, err := s.api.CreateAPIKey(ctx, input)
+	if err != nil {
+		return result{}, fmt.Errorf("failed to create api key: %w", err)
+	}
+
+	cfg := s.opts.Config
+	cfg.APIKey = created.Secret
+	if err := config.Save(cfg); err != nil {
+		return result{}, fmt.Errorf("failed to save config: %w", err)
+	}
+
+	return result{Config: cfg, KeyName: name, Group: group}, nil
+}
+
+func provision(ctx context.Context, opts Options) (result, error) {
+	s, err := signIn(ctx, opts, nil)
+	if err != nil {
+		return result{}, err
+	}
+	group, err := s.chooseGroup()
+	if errors.Is(err, errGroupChoiceRequired) {
+		return result{}, fmt.Errorf("%w; run `requesty login --group <name>` to pick one", err)
+	}
+	if err != nil {
+		return result{}, err
+	}
+	return s.createKey(ctx, group)
+}
+
+func findGroup(groups []client.Group, idOrName string) (*client.Group, bool) {
+	for i := range groups {
+		if groups[i].ID == idOrName {
+			return &groups[i], true
+		}
+	}
+	for i := range groups {
+		if strings.EqualFold(groups[i].Name, idOrName) {
+			return &groups[i], true
+		}
+	}
+	return nil, false
+}
+
+func groupNames(groups []client.Group) []string {
+	names := make([]string, 0, len(groups))
+	for _, group := range groups {
+		names = append(names, group.Name)
+	}
+	return names
+}
+
+const (
+	keyNamePrefix  = "Requesty CLI"
+	keyNameHostMax = 40
+)
+
+func keyNameFor(host string) string {
+	host, _, _ = strings.Cut(host, ".")
+	host = strings.Map(func(r rune) rune {
+		switch {
+		case r >= '0' && r <= '9', r >= 'a' && r <= 'z', r >= 'A' && r <= 'Z', r == '-', r == '_':
+			return r
+		default:
+			return -1
+		}
+	}, host)
+	if len(host) > keyNameHostMax {
+		host = host[:keyNameHostMax]
+	}
+	if host == "" {
+		return keyNamePrefix
+	}
+	return keyNamePrefix + " (" + host + ")"
+}
diff --git a/internal/onboarding/flow_test.go b/internal/onboarding/flow_test.go
new file mode 100644
index 0000000..036cd0b
--- /dev/null
+++ b/internal/onboarding/flow_test.go
@@ -0,0 +1,178 @@
+package onboarding
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/requestyai/cli/internal/client"
+	"github.com/requestyai/cli/internal/config"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// manageServer stands in for the gateway's key-creation endpoint.
+type manageServer struct {
+	t             *testing.T
+	createStatus  int
+	createMessage string
+	tokens        []string
+	creates       []map[string]any
+}
+
+func (s *manageServer) handler() http.Handler {
+	mux := http.NewServeMux()
+	mux.HandleFunc("POST /v1/manage/apikey", func(w http.ResponseWriter, r *http.Request) {
+		s.tokens = append(s.tokens, r.Header.Get("Authorization"))
+		var body map[string]any
+		require.NoError(s.t, json.NewDecoder(r.Body).Decode(&body))
+		s.creates = append(s.creates, body)
+		if s.createStatus != 0 {
+			w.WriteHeader(s.createStatus)
+			_ = json.NewEncoder(w).Encode(map[string]any{"error": map[string]string{"message": s.createMessage}})
+			return
+		}
+		_ = json.NewEncoder(w).Encode(map[string]string{"api_key_id": "key-1", "api_key": "rqsty-new"})
+	})
+	return mux
+}
+
+// signedIn is a session as signIn would leave it, minus the browser: an
+// OAuth token in the client and the caller's groups listed. The router points
+// at the fake, which the management API address follows. Config is written
+// under a throwaway HOME.
+func signedIn(t *testing.T, groups ...client.Group) (*session, *manageServer) {
+	t.Helper()
+	t.Setenv("HOME", t.TempDir())
+
+	fake := &manageServer{t: t}
+	server := httptest.NewServer(fake.handler())
+	t.Cleanup(server.Close)
+
+	cfg := config.Config{RouterBaseURL: server.URL}
+	authConfig := cfg
+	authConfig.APIKey = "token"
+	return &session{
+		opts:   Options{Config: cfg},
+		api:    client.New(authConfig),
+		groups: groups,
+	}, fake
+}
+
+func group(id, name string) client.Group {
+	return client.Group{ID: id, Name: name}
+}
+
+func TestChooseGroup(t *testing.T) {
+	engineering, research := group("g-1", "Engineering"), group("g-2", "Research")
+
+	tests := []struct {
+		name    string
+		groups  []client.Group
+		groupID string
+		want    *client.Group
+		wantErr error
+	}{
+		{name: "no groups means a personal key", groups: nil, want: nil},
+		{name: "a single group is chosen", groups: []client.Group{engineering}, want: &engineering},
+		{name: "several groups need a choice", groups: []client.Group{engineering, research}, wantErr: errGroupChoiceRequired},
+		{name: "by id", groups: []client.Group{engineering, research}, groupID: "g-2", want: &research},
+		{name: "by name, case-insensitively", groups: []client.Group{engineering, research}, groupID: "research", want: &research},
+		{name: "unknown group", groups: []client.Group{engineering}, groupID: "Research", wantErr: errGroupNotFound},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			s := &session{opts: Options{GroupID: tc.groupID}, groups: tc.groups}
+
+			got, err := s.chooseGroup()
+
+			if tc.wantErr != nil {
+				require.ErrorIs(t, err, tc.wantErr)
+				return
+			}
+			require.NoError(t, err)
+			assert.Equal(t, tc.want, got)
+		})
+	}
+}
+
+func TestChooseGroupNamesTheOptions(t *testing.T) {
+	s := &session{groups: []client.Group{group("g-1", "Engineering"), group("g-2", "Research")}}
+
+	_, err := s.chooseGroup()
+
+	require.ErrorContains(t, err, "you belong to 2 groups (Engineering, Research)")
+}
+
+func TestCreateKeyPersonal(t *testing.T) {
+	s, fake := signedIn(t)
+
+	r, err := s.createKey(context.Background(), nil)
+
+	require.NoError(t, err)
+	assert.Equal(t, "rqsty-new", r.Config.APIKey)
+	assert.Equal(t, s.opts.Config.RouterBaseURL, r.Config.RouterBaseURL, "the loaded router is kept")
+	assert.Equal(t, defaultKeyName(), r.KeyName)
+	assert.Nil(t, r.Group)
+	assert.Equal(t, []string{"Bearer token"}, fake.tokens, "the OAuth token creates the key")
+	assert.Equal(t, map[string]any{"name": defaultKeyName()}, fake.creates[0], "no group_id for a personal key")
+
+	saved, err := config.Load()
+	require.NoError(t, err)
+	assert.Equal(t, r.Config, saved)
+}
+
+func TestCreateKeyInGroup(t *testing.T) {
+	research := group("g-2", "Research")
+	s, fake := signedIn(t, research)
+
+	r, err := s.createKey(context.Background(), &research)
+
+	require.NoError(t, err)
+	assert.Equal(t, &research, r.Group)
+	assert.Equal(t, "g-2", fake.creates[0]["group_id"])
+}
+
+func TestCreateKeyReportsGatewayFailure(t *testing.T) {
+	s, fake := signedIn(t)
+	fake.createStatus = http.StatusBadRequest
+	fake.createMessage = "group_id is required"
+
+	_, err := s.createKey(context.Background(), nil)
+
+	require.ErrorContains(t, err, "group_id is required")
+	saved, loadErr := config.Load()
+	require.NoError(t, loadErr)
+	assert.Empty(t, saved.APIKey, "nothing is written when the gateway refuses")
+}
+
+func TestFindGroup(t *testing.T) {
+	groups := []client.Group{group("g-1", "Engineering"), group("g-2", "Research")}
+
+	byID, ok := findGroup(groups, "g-2")
+	require.True(t, ok)
+	assert.Equal(t, "Research", byID.Name)
+
+	byName, ok := findGroup(groups, "ENGINEERING")
+	require.True(t, ok)
+	assert.Equal(t, "g-1", byName.ID)
+
+	_, ok = findGroup(groups, "Sales")
+	assert.False(t, ok)
+}
+
+func TestKeyNameFor(t *testing.T) {
+	tests := map[string]string{
+		"my-laptop":                 "Requesty CLI (my-laptop)",
+		"Fayzans-MacBook-Pro.local": "Requesty CLI (Fayzans-MacBook-Pro)",
+		"ci:runner#7":               "Requesty CLI (cirunner7)",
+		"...":                       "Requesty CLI",
+		"abcdefghijklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz": "Requesty CLI (abcdefghijklmnopqrstuvwxyzabcdefghijklmn)",
+	}
+	for host, want := range tests {
+		assert.Equal(t, want, keyNameFor(host))
+	}
+}
diff --git a/internal/onboarding/model.go b/internal/onboarding/model.go
new file mode 100644
index 0000000..c2b7b85
--- /dev/null
+++ b/internal/onboarding/model.go
@@ -0,0 +1,330 @@
+package onboarding
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	tea "charm.land/bubbletea/v2"
+	"charm.land/lipgloss/v2"
+	"github.com/requestyai/cli/internal/client"
+	"github.com/requestyai/cli/internal/config"
+	"github.com/requestyai/cli/internal/tui/theme"
+	"github.com/requestyai/cli/internal/tui/ui/table"
+	"github.com/requestyai/cli/internal/tui/ui/text"
+)
+
+const (
+	pageWidth       = 64
+	dialogMinWidth  = 24
+	dialogMaxWidth  = 80
+	groupListHeight = 8
+	membersWidth    = 10
+
+	framePadX     = 2
+	framePadY     = 1
+	defaultWidth  = 80 - 2*framePadX
+	defaultHeight = 24 - 2*framePadY
+)
+
+var frame = lipgloss.NewStyle().Padding(framePadY, framePadX)
+
+type dialogStep uint8
+
+const (
+	dialogSigningIn dialogStep = iota
+	dialogChooseGroup
+	dialogSaving
+)
+
+type dialogState struct {
+	open         bool
+	step         dialogStep
+	cancel       context.CancelFunc
+	authorizeURL string
+	session      *session
+	groupCursor  int
+}
+
+type authorizeURLMsg struct{ url string }
+
+type signedInMsg struct {
+	session *session
+	err     error
+}
+
+type savedMsg struct {
+	result result
+	err    error
+}
+
+// model owns the complete interactive onboarding program.
+type model struct {
+	ctx    context.Context
+	opts   Options
+	dialog dialogState
+	err    error
+	width  int
+	height int
+	done   *config.Config
+}
+
+func newModel(ctx context.Context, opts Options) model {
+	return model{
+		ctx:    ctx,
+		opts:   opts,
+		width:  defaultWidth,
+		height: defaultHeight,
+	}
+}
+
+func (m model) Init() tea.Cmd { return nil }
+
+func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+	switch typedMsg := msg.(type) {
+	case tea.WindowSizeMsg:
+		m.width = max(typedMsg.Width-2*framePadX, 0)
+		m.height = max(typedMsg.Height-2*framePadY, 0)
+
+	case authorizeURLMsg:
+		if m.dialog.open && m.dialog.step == dialogSigningIn {
+			m.dialog.authorizeURL = typedMsg.url
+		}
+
+	case signedInMsg:
+		return m.onSignedIn(typedMsg)
+
+	case savedMsg:
+		if typedMsg.err != nil {
+			return m.fail(typedMsg.err), nil
+		}
+		m.done = &typedMsg.result.Config
+		return m, tea.Quit
+
+	case tea.KeyPressMsg:
+		switch typedMsg.String() {
+		case "ctrl+c":
+			return m, tea.Quit
+		case "q":
+			if !m.dialog.open {
+				return m, tea.Quit
+			}
+		case "esc":
+			if !m.dialog.open {
+				return m, tea.Quit
+			}
+		}
+
+		if m.dialog.open {
+			return m.updateDialog(typedMsg)
+		}
+		if typedMsg.String() == "enter" {
+			return m.signIn()
+		}
+	}
+
+	return m, nil
+}
+
+func (m model) updateDialog(msg tea.KeyPressMsg) (model, tea.Cmd) {
+	switch m.dialog.step {
+	case dialogSigningIn:
+		if msg.String() == "esc" {
+			m.dialog.cancel()
+			m.dialog = dialogState{}
+		}
+	case dialogChooseGroup:
+		groups := m.dialog.session.groups
+		switch msg.String() {
+		case "esc":
+			m.dialog = dialogState{}
+		case "up", "k":
+			if m.dialog.groupCursor > 0 {
+				m.dialog.groupCursor--
+			}
+		case "down", "j":
+			if m.dialog.groupCursor < len(groups)-1 {
+				m.dialog.groupCursor++
+			}
+		case "enter":
+			return m.save(&groups[m.dialog.groupCursor])
+		}
+	case dialogSaving:
+		// Nothing to do but wait.
+	}
+	return m, nil
+}
+
+func (m model) signIn() (model, tea.Cmd) {
+	ctx, cancel := context.WithCancel(m.ctx)
+	m.dialog = dialogState{open: true, step: dialogSigningIn, cancel: cancel}
+	m.err = nil
+
+	opts := m.opts
+	urls := make(chan string, 1)
+	return m, tea.Batch(
+		func() tea.Msg {
+			defer close(urls)
+			session, err := signIn(ctx, opts, func(url string) { urls <- url })
+			return signedInMsg{session: session, err: err}
+		},
+		func() tea.Msg {
+			url, ok := <-urls
+			if !ok {
+				return nil
+			}
+			return authorizeURLMsg{url: url}
+		},
+	)
+}
+
+func (m model) onSignedIn(msg signedInMsg) (model, tea.Cmd) {
+	if !m.dialog.open || m.dialog.step != dialogSigningIn {
+		return m, nil
+	}
+	if errors.Is(msg.err, context.Canceled) {
+		m.dialog = dialogState{}
+		return m, nil
+	}
+	if msg.err != nil {
+		return m.fail(msg.err), nil
+	}
+
+	m.dialog.session = msg.session
+	group, err := msg.session.chooseGroup()
+	if errors.Is(err, errGroupChoiceRequired) {
+		m.dialog.step = dialogChooseGroup
+		m.dialog.groupCursor = 0
+		return m, nil
+	}
+	if err != nil {
+		return m.fail(err), nil
+	}
+	return m.save(group)
+}
+
+func (m model) save(group *client.Group) (model, tea.Cmd) {
+	m.dialog.step = dialogSaving
+	session := m.dialog.session
+	ctx := m.ctx
+	return m, func() tea.Msg {
+		result, err := session.createKey(ctx, group)
+		return savedMsg{result: result, err: err}
+	}
+}
+
+func (m model) fail(err error) model {
+	m.dialog = dialogState{}
+	m.err = err
+	return m
+}
+
+func (m model) View() tea.View {
+	view := tea.NewView(frame.Render(m.pageView()))
+	view.AltScreen = true
+	return view
+}
+
+func (m model) pageView() string {
+	if m.dialog.open {
+		return m.dialogView()
+	}
+
+	inner := max(min(m.width-4, pageWidth), dialogMinWidth)
+	wrap := lipgloss.NewStyle().Width(inner)
+	lines := []string{
+		theme.Heading.Render("Welcome to Requesty"),
+		wrap.Render(theme.Label.Render("One gateway for every model, in every tool you use, or app you build.")),
+		text.LineSeparator,
+		wrap.Render(theme.Body.Render(fmt.Sprintf(
+			"Sign in with your browser to get started. This creates an API key named %q in your Requesty account and saves it to %s.",
+			defaultKeyName(), config.DisplayPath()))),
+	}
+	if m.opts.Harness != "" {
+		lines = append(lines, wrap.Render(theme.Body.Render(m.opts.Harness+" starts as soon as the key is saved.")))
+	}
+	lines = append(lines,
+		text.LineSeparator,
+		wrap.Render(theme.Muted.Render("Working over SSH, or already have a key? Quit and run `requesty login --api-key <key>` instead.")),
+		text.LineSeparator,
+	)
+	if m.err != nil {
+		lines = append(lines, wrap.Render(theme.Bad.Render(m.err.Error())), text.LineSeparator)
+	}
+	lines = append(lines, text.RenderFooterHintList(inner, [2]string{"enter", "sign in"}, [2]string{"q/esc", "quit"}))
+
+	body := theme.Panel.Render(lipgloss.JoinVertical(lipgloss.Left, lines...))
+	return lipgloss.Place(m.width, m.height, lipgloss.Center, lipgloss.Center, body)
+}
+
+type dialogPage struct {
+	title string
+	body  string
+	hints [][2]string
+}
+
+func (m model) dialogView() string {
+	inner := max(min(m.width-8, dialogMaxWidth), dialogMinWidth)
+	page := m.dialogPage(inner)
+	lines := []string{
+		text.RenderSplitHeaderSection(page.title, "", inner),
+		text.LineSeparator,
+		page.body,
+		text.LineSeparator,
+		text.RenderFooterHintList(inner, page.hints...),
+	}
+	body := theme.Panel.Render(lipgloss.JoinVertical(lipgloss.Left, lines...))
+	return lipgloss.Place(m.width, m.height, lipgloss.Center, lipgloss.Center, body)
+}
+
+func (m model) dialogPage(inner int) dialogPage {
+	wrap := lipgloss.NewStyle().Width(inner)
+	switch m.dialog.step {
+	case dialogSigningIn:
+		body := []string{wrap.Render(theme.Body.Render("Waiting for you to finish signing in in your browser…"))}
+		if m.dialog.authorizeURL != "" {
+			body = append(body,
+				text.LineSeparator,
+				wrap.Render(theme.Muted.Render("If it did not open, visit this address:")),
+				wrap.Render(theme.Accent.Render(m.dialog.authorizeURL)),
+			)
+		}
+		return dialogPage{
+			title: "Sign in with your browser",
+			body:  lipgloss.JoinVertical(lipgloss.Left, body...),
+			hints: [][2]string{{"esc", "cancel"}},
+		}
+	case dialogChooseGroup:
+		return dialogPage{
+			title: "Choose a group for the API key",
+			body:  m.groupTable(inner).Render(),
+			hints: [][2]string{{"↑/↓", "move"}, {"enter", "choose"}, {"esc", "cancel"}},
+		}
+	case dialogSaving:
+		return dialogPage{
+			title: "Saving your API key",
+			body:  wrap.Render(theme.Muted.Render("Creating the key and writing " + config.DisplayPath() + "…")),
+			hints: [][2]string{{"ctrl+c", "quit"}},
+		}
+	default:
+		return dialogPage{}
+	}
+}
+
+func (m model) groupTable(inner int) table.Table {
+	groups := m.dialog.session.groups
+	rows := make([][]string, 0, len(groups))
+	for _, group := range groups {
+		rows = append(rows, []string{group.Name, fmt.Sprintf("%d", group.MembersCount)})
+	}
+	return table.Table{
+		Cols: []table.Column{
+			{Title: "GROUP", Width: inner - 2 - membersWidth, Align: table.Left},
+			{Title: "MEMBERS", Width: membersWidth, Align: table.Right},
+		},
+		Rows:   rows,
+		Cursor: m.dialog.groupCursor,
+		Height: groupListHeight,
+		Style:  table.CellStyle(m.dialog.groupCursor),
+	}
+}
diff --git a/internal/onboarding/model_test.go b/internal/onboarding/model_test.go
new file mode 100644
index 0000000..6489fa3
--- /dev/null
+++ b/internal/onboarding/model_test.go
@@ -0,0 +1,141 @@
+package onboarding
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"testing"
+
+	tea "charm.land/bubbletea/v2"
+	"github.com/charmbracelet/x/ansi"
+	"github.com/requestyai/cli/internal/client"
+	"github.com/requestyai/cli/internal/config"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func key(name string) tea.KeyPressMsg {
+	switch name {
+	case "enter":
+		return tea.KeyPressMsg{Code: tea.KeyEnter}
+	case "esc":
+		return tea.KeyPressMsg{Code: tea.KeyEscape}
+	case "up":
+		return tea.KeyPressMsg{Code: tea.KeyUp}
+	case "down":
+		return tea.KeyPressMsg{Code: tea.KeyDown}
+	default:
+		return tea.KeyPressMsg{Code: rune(name[0]), Text: name}
+	}
+}
+
+func update(m model, msg tea.Msg) (model, tea.Cmd) {
+	next, cmd := m.Update(msg)
+	return next.(model), cmd
+}
+
+func signingIn() model {
+	m := newModel(context.Background(), Options{})
+	m.dialog = dialogState{open: true, step: dialogSigningIn, cancel: func() {}}
+	return m
+}
+
+func view(m model) string {
+	return ansi.Strip(m.View().Content)
+}
+
+func TestWelcomeExplainsOnboarding(t *testing.T) {
+	out := view(newModel(context.Background(), Options{Harness: "Claude Code"}))
+
+	assert.Contains(t, out, "Welcome to Requesty")
+	assert.Contains(t, out, fmt.Sprintf("%q", defaultKeyName()))
+	assert.Contains(t, out, "Claude Code starts as soon as the key is saved")
+	assert.Contains(t, out, "--api-key <key>")
+}
+
+func TestEnterOpensSigningInDialog(t *testing.T) {
+	m, cmd := update(newModel(context.Background(), Options{}), key("enter"))
+
+	assert.True(t, m.dialog.open)
+	assert.Equal(t, dialogSigningIn, m.dialog.step)
+	assert.NotNil(t, m.dialog.cancel)
+	assert.NotNil(t, cmd)
+	assert.Contains(t, view(m), "Waiting for you to finish signing in")
+}
+
+func TestSigningInDialogShowsAuthorizeURL(t *testing.T) {
+	m := signingIn()
+
+	m, _ = update(m, authorizeURLMsg{url: "https://api.example/authorize"})
+
+	assert.Contains(t, view(m), "If it did not open")
+	assert.Contains(t, view(m), "https://api.example/authorize")
+}
+
+func TestEscapeCancelsAndIgnoresLateSignIn(t *testing.T) {
+	m := signingIn()
+	cancelled := false
+	m.dialog.cancel = func() { cancelled = true }
+
+	m, _ = update(m, key("esc"))
+	assert.True(t, cancelled)
+	assert.False(t, m.dialog.open)
+
+	m, cmd := update(m, signedInMsg{session: &session{}})
+	assert.False(t, m.dialog.open)
+	assert.Nil(t, cmd)
+}
+
+func TestSignInFailureReturnsToWelcome(t *testing.T) {
+	m := signingIn()
+
+	m, _ = update(m, signedInMsg{err: errors.New("access_denied")})
+
+	assert.False(t, m.dialog.open)
+	assert.Contains(t, view(m), "access_denied")
+}
+
+func TestSeveralGroupsOpenPickerAndMoveCursor(t *testing.T) {
+	s := &session{groups: []client.Group{
+		group("g-1", "Engineering"),
+		group("g-2", "Research"),
+	}}
+	m := signingIn()
+
+	m, cmd := update(m, signedInMsg{session: s})
+	require.Nil(t, cmd)
+	assert.Equal(t, dialogChooseGroup, m.dialog.step)
+	assert.Contains(t, view(m), "Engineering")
+	assert.Contains(t, view(m), "Research")
+
+	m, _ = update(m, key("down"))
+	m, _ = update(m, key("down"))
+	assert.Equal(t, 1, m.dialog.groupCursor)
+	m, _ = update(m, key("up"))
+	assert.Equal(t, 0, m.dialog.groupCursor)
+
+	m, cmd = update(m, key("enter"))
+	assert.Equal(t, dialogSaving, m.dialog.step)
+	assert.NotNil(t, cmd)
+}
+
+func TestSavedResultQuitsWithConfig(t *testing.T) {
+	m := newModel(context.Background(), Options{})
+	m.dialog = dialogState{open: true, step: dialogSaving}
+	cfg := config.Config{APIKey: "rqsty-new"}
+
+	m, cmd := update(m, savedMsg{result: result{Config: cfg}})
+
+	require.NotNil(t, cmd)
+	assert.Equal(t, cfg, *m.done)
+}
+
+func TestKeysAreIgnoredWhileSaving(t *testing.T) {
+	m := newModel(context.Background(), Options{})
+	m.dialog = dialogState{open: true, step: dialogSaving}
+
+	m, cmd := update(m, key("esc"))
+
+	assert.Nil(t, cmd)
+	assert.True(t, m.dialog.open)
+}
diff --git a/internal/onboarding/run.go b/internal/onboarding/run.go
new file mode 100644
index 0000000..d09dbee
--- /dev/null
+++ b/internal/onboarding/run.go
@@ -0,0 +1,57 @@
+package onboarding
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+
+	tea "charm.land/bubbletea/v2"
+	"github.com/requestyai/cli/internal/config"
+)
+
+var (
+	// ErrCancelled reports that interactive onboarding ended before a key was
+	// saved.
+	ErrCancelled = errors.New("sign-in cancelled")
+)
+
+// Run signs a user in with their browser and takes them through to a saved
+// config in the full-screen UI.
+func Run(ctx context.Context, opts Options) (config.Config, error) {
+	final, err := tea.NewProgram(newModel(ctx, opts), tea.WithContext(ctx), tea.WithOutput(os.Stderr)).Run()
+	if err != nil {
+		return config.Config{}, fmt.Errorf("failed to run onboarding: %w", err)
+	}
+
+	finished, ok := final.(model)
+	if !ok || finished.done == nil {
+		return config.Config{}, ErrCancelled
+	}
+	return *finished.done, nil
+}
+
+// RunHeadless signs a user in with their browser and saves the resulting
+// config using plain-text prompts and status output.
+func RunHeadless(ctx context.Context, opts Options) (config.Config, error) {
+	_, _ = fmt.Fprintf(os.Stderr,
+		"Signing in with your browser will create an API key named %q in your Requesty\naccount and save it to %s.\n\n",
+		defaultKeyName(), config.DisplayPath())
+
+	r, err := provision(ctx, opts)
+	if err != nil {
+		return config.Config{}, err
+	}
+
+	if r.Group != nil {
+		_, _ = fmt.Fprintf(os.Stderr,
+			"Created API key %q in group %q and saved it to %s.\nManage it at %s.\n",
+			r.KeyName, r.Group.Name, config.DisplayPath(), APIKeysURL)
+	} else {
+		_, _ = fmt.Fprintf(os.Stderr,
+			"Created API key %q in your personal API keys and saved it to %s.\nManage it at %s.\n",
+			r.KeyName, config.DisplayPath(), APIKeysURL)
+	}
+
+	return r.Config, nil
+}
diff --git a/internal/tui/onboarding_app.go b/internal/tui/onboarding_app.go
deleted file mode 100644
index 7644c73..0000000
--- a/internal/tui/onboarding_app.go
+++ /dev/null
@@ -1,41 +0,0 @@
-package tui
-
-import (
-	tea "charm.land/bubbletea/v2"
-	"github.com/requestyai/cli/internal/tui/pages/onboarding/apikey"
-)
-
-// OnboardingApp collects the configuration needed to enter RequestyApp.
-type OnboardingApp struct {
-	apiKey apikey.Model
-	width  int
-	height int
-}
-
-func NewOnboardingApp() OnboardingApp {
-	return OnboardingApp{
-		apiKey: apikey.New(),
-		width:  contentWidth,
-		height: contentHeight,
-	}
-}
-
-func (a OnboardingApp) Init() tea.Cmd {
-	return a.apiKey.Init()
-}
-
-func (a OnboardingApp) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
-	switch typedMsg := msg.(type) {
-	case tea.WindowSizeMsg:
-		a.width, a.height = typedMsg.Width, typedMsg.Height
-	}
-
-	var cmd tea.Cmd
-	a.apiKey, cmd = a.apiKey.Update(msg)
-
-	return a, cmd
-}
-
-func (a OnboardingApp) View() tea.View {
-	return tea.NewView(a.apiKey.View(a.width, a.height))
-}
diff --git a/internal/tui/pages/onboarding/apikey/api_key.go b/internal/tui/pages/onboarding/apikey/api_key.go
deleted file mode 100644
index 5ffb43b..0000000
--- a/internal/tui/pages/onboarding/apikey/api_key.go
+++ /dev/null
@@ -1,138 +0,0 @@
-package apikey
-
-import (
-	"context"
-	"errors"
-	"strings"
-	"time"
-
-	"charm.land/bubbles/v2/textinput"
-	tea "charm.land/bubbletea/v2"
-	"charm.land/lipgloss/v2"
-	"github.com/requestyai/cli/internal/client"
-	"github.com/requestyai/cli/internal/config"
-	"github.com/requestyai/cli/internal/tui/theme"
-	"github.com/requestyai/cli/internal/tui/ui/text"
-)
-
-const checkTimeout = 10 * time.Second
-
-// DoneMsg reports that onboarding finished and the config is on disk. The
-// root model listens for it to hand over to the Requesty app.
-type DoneMsg struct {
-	Config config.Config
-}
-
-// failedMsg reports that the key could not be saved. The user stays on this
-// step and can try again.
-type failedMsg struct {
-	err error
-}
-
-// Model is the API key step of the onboarding flow.
-type Model struct {
-	input    textinput.Model
-	err      error
-	checking bool
-}
-
-func New() Model {
-	input := textinput.New()
-	input.Prompt = "❯ "
-	input.Placeholder = "rqsty-..."
-	input.EchoMode = textinput.EchoPassword
-	input.CharLimit = 200
-	input.SetWidth(48)
-	input.Focus()
-
-	return Model{input: input}
-}
-
-func (m Model) Init() tea.Cmd {
-	return nil
-}
-
-func (m Model) Update(msg tea.Msg) (Model, tea.Cmd) {
-	switch typedMsg := msg.(type) {
-	case failedMsg:
-		m.err = typedMsg.err
-		m.checking = false
-
-	case tea.KeyPressMsg:
-		switch typedMsg.String() {
-		case "enter":
-			apiKey := strings.TrimSpace(m.input.Value())
-			if apiKey == "" || m.checking {
-				return m, nil
-			}
-
-			m.err = nil
-			m.checking = true
-
-			return m, checkAndSave(apiKey)
-		}
-	}
-
-	var cmd tea.Cmd
-	m.input, cmd = m.input.Update(msg)
-
-	return m, cmd
-}
-
-// checkAndSave rejects a key the gateway does not recognise, so a typo is
-// caught here rather than surfacing later as a failed request. The key is
-// persisted before onboarding reports itself done, so the next run can skip
-// this step.
-func checkAndSave(apiKey string) tea.Cmd {
-	return func() tea.Msg {
-		cfg := config.Config{
-			APIKey:        strings.TrimSpace(apiKey),
-			RouterBaseURL: config.DefaultRouterBaseURL,
-		}
-
-		ctx, cancel := context.WithTimeout(context.Background(), checkTimeout)
-		defer cancel()
-
-		// Anything other than a rejection (offline, gateway trouble) is not
-		// the user's problem, so the key is accepted and the next request
-		// reports the failure.
-		if err := client.New(cfg).CheckAPIKey(ctx); errors.Is(err, client.ErrInvalidAPIKey) {
-			return failedMsg{err: errors.New("That key was not recognised. Copy it again from https://app.requesty.ai/api-keys.")}
-		}
-
-		if err := config.Save(cfg); err != nil {
-			return failedMsg{err: err}
-		}
-
-		return DoneMsg{Config: cfg}
-	}
-}
-
-func (m Model) View(width, height int) string {
-	// The panel's border and padding cost four columns. The input needs two
-	// more for its prompt and one for the cursor sitting past the last rune.
-	inner := min(width-4, 64)
-	m.input.SetWidth(inner - 3)
-
-	wrap := lipgloss.NewStyle().Width(inner)
-	lines := []string{
-		theme.Heading.Render("Welcome to Requesty"),
-		wrap.Render(theme.Label.Render("One gateway for every model, in every tool you use, or app you build.")),
-		text.LineSeparator,
-		wrap.Render(theme.Body.Render("Paste an API key from https://app.requesty.ai/api-keys to begin.")),
-		text.LineSeparator,
-		m.input.View(),
-		text.LineSeparator,
-	}
-	if m.checking {
-		lines = append(lines, wrap.Render(theme.Label.Render("Checking key...")), "")
-	}
-	if m.err != nil {
-		lines = append(lines, wrap.Render(theme.Bad.Render(m.err.Error())), "")
-	}
-	lines = append(lines, text.RenderFooterHintList(inner, [2]string{"enter", "continue"}, [2]string{"ctrl+c", "quit"}))
-
-	body := theme.Panel.Render(lipgloss.JoinVertical(lipgloss.Left, lines...))
-
-	return lipgloss.Place(width, height, lipgloss.Center, lipgloss.Center, body)
-}
diff --git a/internal/tui/root.go b/internal/tui/root.go
index 4de3922..55c84d9 100644
--- a/internal/tui/root.go
+++ b/internal/tui/root.go
@@ -4,7 +4,6 @@ import (
 	tea "charm.land/bubbletea/v2"
 	"charm.land/lipgloss/v2"
 	"github.com/requestyai/cli/internal/config"
-	"github.com/requestyai/cli/internal/tui/pages/onboarding/apikey"
 )
 
 // frame is the breathing room around everything the UI draws.
@@ -19,7 +18,7 @@ const (
 	contentHeight = windowHeight - 2*framePadY
 )
 
-// Root delegates the session to whichever app is currently active.
+// Root frames the configured Requesty app.
 type Root struct {
 	active tea.Model
 
@@ -27,20 +26,13 @@ type Root struct {
 	width, height int
 }
 
-// NewRoot builds the UI. A config, saved by an earlier run, skips
-// onboarding.
+// NewRoot builds the configured Requesty UI.
 func NewRoot(cfg config.Config) Root {
-	root := Root{
-		active: NewOnboardingApp(),
+	return Root{
+		active: NewRequestyApp(cfg),
 		width:  contentWidth,
 		height: contentHeight,
 	}
-
-	if cfg.APIKey != "" {
-		root.active = NewRequestyApp(cfg)
-	}
-
-	return root
 }
 
 func (r Root) Init() tea.Cmd {
@@ -62,15 +54,6 @@ func (r Root) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 		case "ctrl+c":
 			return r, tea.Quit
 		}
-
-	case apikey.DoneMsg:
-		r.active = NewRequestyApp(typedMsg.Config)
-		r.active, _ = r.active.Update(tea.WindowSizeMsg{
-			Width:  r.width,
-			Height: r.height,
-		})
-
-		return r, r.active.Init()
 	}
 
 	var cmd tea.Cmd

From 8d083e0858ac6f871c6e4f3c58024778100d4c73 Mon Sep 17 00:00:00 2001
From: fayzan <fayzan@requesty.ai>
Date: Tue, 22 Sep 2026 14:10:23 +0100
Subject: [PATCH 4/9] Implement profiles

---
 README.md                        | 122 ++++++++++++++++++++--------
 cmd/access_lists.go              |  43 +++++-----
 cmd/api_keys.go                  |  39 ++++-----
 cmd/auth.go                      |  23 +++---
 cmd/environment.go               | 102 ++++++++++++++++++++++++
 cmd/groups.go                    |  33 ++++----
 cmd/harness.go                   |  65 ++++++++-------
 cmd/harness_test.go              |  61 ++++++++++----
 cmd/login.go                     |  94 +++++++++++-----------
 cmd/login_test.go                |  84 ++++++++++---------
 cmd/profiles.go                  | 133 +++++++++++++++++++++++++++++++
 cmd/profiles_test.go             |  91 +++++++++++++++++++++
 cmd/requesty.go                  |  45 ++---------
 cmd/requesty_test.go             |  83 +++++++++++++++++--
 internal/config/config.go        | 114 ++++++++++++++++++++++----
 internal/config/config_test.go   | 104 +++++++++++++++++++++---
 internal/harnesses/codex.go      |  10 ++-
 internal/harnesses/codex_test.go |  25 +++---
 internal/onboarding/flow.go      |   3 -
 internal/onboarding/flow_test.go |   9 +--
 internal/onboarding/run.go       |  16 ++--
 21 files changed, 962 insertions(+), 337 deletions(-)
 create mode 100644 cmd/environment.go
 create mode 100644 cmd/profiles.go
 create mode 100644 cmd/profiles_test.go

diff --git a/README.md b/README.md
index b0a5864..89d8e94 100644
--- a/README.md
+++ b/README.md
@@ -17,6 +17,8 @@ replaced by default.
 
 - [Quick start](#quick-start)
 - [First run](#first-run)
+- [Launching a harness](#launching-a-harness)
+- [Profiles](#profiles)
 - [Supported harnesses](#supported-harnesses)
 - [Usage](#usage)
 - [Merge or overwrite](#merge-or-overwrite)
@@ -43,13 +45,13 @@ a new terminal, or run the `source` command it prints, then run `requesty`.
 
 **Sign in with your browser**
 
-The first time you run `requesty`, `requesty claude` or `requesty codex` on a machine without a key,
+The first time you run `requesty`, `requesty claude` or `requesty codex` on a machine without a profile,
 the CLI opens with a welcome page that says what is about to happen. Press enter and it signs you in
 to Requesty in your browser; once you approve, it creates an API key in your account, named after
-this machine (`Requesty CLI (my-laptop)`), and saves it to `~/.requesty/config.json`. The app then
-carries on to its dashboard, or the harness you asked for starts. Every later run reuses that key,
-so this happens once. The key shows up on the [API keys page](https://app.requesty.ai/api-keys)
-like any other, and can be revoked there.
+this machine (`Requesty CLI (my-laptop)`), and saves it as a [profile](#profiles) in
+`~/.requesty/config.json`. The app then carries on to its dashboard, or the harness you asked for
+starts. Every later run reuses that profile. The key shows up on the
+[API keys page](https://app.requesty.ai/api-keys) like any other, and can be revoked there.
 
 ```text
 ╭──────────────────────────────────────────────────────────────────╮
@@ -72,24 +74,63 @@ like any other, and can be revoked there.
 While the browser is open a dialog shows the sign-in address, for when the browser did not open on
 its own; `esc` cancels. The key is created in your group. If you belong to several groups a dialog
 asks which one; if you belong to none it is a personal key. Organizations that require keys to live
-in a group will say so, in which case ask an admin to add you to one.
-
-Without a terminal to ask on (a script, a CI job) a harness launch stops and tells you to run
-`requesty login` first.
+in a group will say so, in which case ask an admin to add you to one. The profile is named
+`default`; pass `--profile <name>` to choose another name.
 
 **`requesty login`**
 
 `requesty login` runs the same sign-in from the command line. Use it to set up a machine before
-launching anything, to pick a group without being asked (`--group Engineering`), or to replace a
-key that was revoked or has expired. When a working key is already saved it does nothing unless
-you pass `--force`.
+launching anything, to pick a group without being asked (`--group Engineering`), to name the
+profile yourself (`--profile eu`), to point it at another router (`--router-url`), or to replace a
+key that was revoked or has expired. Existing profiles are left alone unless you pass `--force`.
 
 **Over SSH, or with a key you already have**
 
 The browser hands the sign-in back to the CLI on `127.0.0.1`, which does not work over SSH. Create
 a key on the [API keys page](https://app.requesty.ai/api-keys) and run
 `requesty login --api-key <key>` instead. The key is checked against the gateway before it is
-saved, so a typo is rejected here instead of failing later.
+saved, so a typo is rejected here instead of failing later. It is saved as the profile `default`
+unless you pass `--profile`.
+
+## Launching a harness
+
+`requesty claude` and `requesty codex` start the harness with its traffic routed through Requesty
+for that run only; nothing on disk is changed. The current profile is used unless you select
+another. A model flag applies only to that run; without it, the harness uses its configured model.
+
+```sh
+requesty claude                                    # current profile, harness's configured model
+requesty claude --profile eu                       # a named profile
+requesty claude --model anthropic/claude-opus-4-1  # this model, just for this run
+requesty codex --reasoning-effort high -- --full-auto
+```
+
+Profile precedence is `--profile <name>`, then `REQUESTY_PROFILE`, then the current profile set
+with `requesty profiles use`. For a harness command, put `--profile` after the harness name and
+before the first argument that is passed through to the harness.
+
+## Profiles
+
+A profile is one sign-in: an API key and the router it is sent to. Most people have one. You want
+more when your organization gives you keys in
+different groups with different model policies (an EU group and a US group, say), or when you use
+Requesty for work and personally on the same machine. Keys with manage permissions for the
+`api-keys`, `groups` and `access-lists` subcommands fit here too: save one with
+`requesty login --api-key <key> --profile manage` and pass `--profile manage` to those commands.
+
+```sh
+requesty profiles list                                  # what is saved, current marked with *
+requesty profiles use eu                                # make this profile current
+requesty profiles remove personal                       # forget a profile (the key is not revoked)
+```
+
+`requesty login` creates the `default` profile unless you pass `--profile`. The first profile
+becomes current. Every command accepts `--profile <name>`, and `REQUESTY_PROFILE` does the same
+for a whole shell.
+
+Harnesses configured from the dashboard stay pinned to the profile used during configuration.
+Claude Code stores that profile's key in its settings. Codex fetches the key through
+`requesty auth token --profile <name>`. Configure the harness again to move it to another profile.
 
 **Pick a harness**
 
@@ -153,9 +194,9 @@ a later run of the CLI keeps those entries and only adds the model you selected
 
 ## Usage
 
-Above the harness list, the CLI shows spend, requests and tokens for the last 30 days for the key
-you onboarded with, and refreshes them on demand. Full breakdowns by model, user and tool live in
-the [Requesty dashboard](https://app.requesty.ai/analytics).
+Above the harness list, the CLI shows spend, requests and tokens for the last 30 days for the
+profile it is running as, and refreshes them on demand. Full breakdowns by model, user and tool
+live in the [Requesty dashboard](https://app.requesty.ai/analytics).
 
 ## Merge or overwrite
 
@@ -183,19 +224,20 @@ mv ~/.claude/settings.json.requesty.bak ~/.claude/settings.json
 
 ## Keys
 
-Your Requesty API key is written into `~/.requesty/config.json`. Codex retrieves it when needed
-through `requesty auth token`; other harnesses may also store it in their own config because that
-is how they authenticate. All files containing the key are written so that only your user can
-read them.
+Your Requesty API keys are written into `~/.requesty/config.json`, one per profile. Codex
+retrieves the current profile's key when needed through `requesty auth token`; other harnesses
+may also store it in their own config because that is how they authenticate. All files
+containing a key are written so that only your user can read them.
 
 A key created by signing in can make completions and read its own usage, nothing more. The
 management subcommands (`requesty api-keys`, `requesty groups`, `requesty access-lists`) need a
-key with manage permissions from the [API keys page](https://app.requesty.ai/api-keys). The
-short-lived token from the browser sign-in is used once to create the key and is never stored.
+key with manage permissions from the [API keys page](https://app.requesty.ai/api-keys), saved as
+its own profile with `requesty login --api-key <key> --profile <name>`. The short-lived token from
+the browser sign-in is used once to create the key and is never stored.
 
 Treat those files as secrets and do not commit them. Keys can be rotated or revoked at any time
 on the [API keys page](https://app.requesty.ai/api-keys); run `requesty login` afterwards to get
-a new one.
+a new one. Removing a profile with `requesty profiles remove` forgets the key locally only.
 
 ## Configuration
 
@@ -203,18 +245,27 @@ a new one.
 
 ```json
 {
-	"api_key": "rqsty-...",
-	"router_base_url": "https://router.requesty.ai"
+	"current": "engineering",
+	"profiles": {
+		"engineering": {
+			"api_key": "rqsty-..."
+		},
+		"eu": {
+			"api_key": "rqsty-...",
+			"router_base_url": "https://router.eu.requesty.ai"
+		}
+	}
 }
 ```
 
-| Field | Meaning |
-| --- | --- |
-| `api_key` | The key written into harness configs and used for API calls |
-| `router_base_url` | Inference endpoint the harnesses are pointed at |
+- `current` names the profile used when none is selected explicitly. It is required whenever any
+  profiles are saved.
+- `profiles.<name>.api_key` authenticates API and harness requests.
+- `profiles.<name>.router_base_url` is that profile's inference endpoint. When omitted, it defaults
+  to `https://router.requesty.ai`.
 
-Change `router_base_url` to route through a different region or a self-hosted deployment, for
-example `https://router.eu.requesty.ai`. Delete the file to start over from onboarding.
+Set a profile's `router_base_url` to use a different region or self-hosted deployment. The config
+has no legacy single-key format; delete the file to start over from onboarding.
 
 ## Advanced installation options
 
@@ -291,15 +342,16 @@ Run `requesty login --api-key <key>` with a key from the
 [API keys page](https://app.requesty.ai/api-keys) instead, or forward the port shown in the
 sign-in URL.
 
-**`no Requesty API key configured; run requesty login`.** The CLI ran without a key and without a
-terminal to ask on. Run `requesty login` once, interactively, or `requesty login --api-key <key>`.
+**`no Requesty profile configured; run requesty login`.** A command that cannot onboard
+automatically ran without a saved profile. Run `requesty login` or
+`requesty login --api-key <key>`.
 
 **`group_id is required for organizations in group budget mode`.** Your organization tracks spend
 per group, and you are not in one yet. Ask an organization admin to add you to a group, then sign
 in again.
 
-**Claude Code or Codex gets a `401`.** The key was revoked or has expired. Run `requesty login`;
-it notices the saved key no longer works and creates a new one.
+**Claude Code or Codex gets a `401`.** The key was revoked or has expired. Replace that profile
+with `requesty login --profile <name> --force`.
 
 **`Could not load usage`.** The usage panel asks the management API about your own key, which any
 key may do. A `401` means the key was revoked or has expired: run `requesty login` to get a new
diff --git a/cmd/access_lists.go b/cmd/access_lists.go
index 255be0f..f0999cb 100644
--- a/cmd/access_lists.go
+++ b/cmd/access_lists.go
@@ -17,7 +17,7 @@ const (
 	accessListYesFlag         = "yes"
 )
 
-func newAccessListsCommand(env environment) *cobra.Command {
+func newAccessListsCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "access-lists",
 		Aliases: []string{"access-list"},
@@ -27,6 +27,7 @@ func newAccessListsCommand(env environment) *cobra.Command {
 			"the list are allowed, whatever their kind, so a list with only chat models\n" +
 			"blocks embeddings, images and audio too. Models are grouped by modality:\n" +
 			"chat, embedding, image, transcription or speech.",
+		PersistentPreRunE: env.requireProfile,
 	}
 
 	cmd.PersistentFlags().Bool(jsonFlag, false, "print JSON instead of a table")
@@ -42,13 +43,13 @@ func newAccessListsCommand(env environment) *cobra.Command {
 	return cmd
 }
 
-func newAccessListsListCommand(env environment) *cobra.Command {
+func newAccessListsListCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:   "list",
 		Short: "List the access lists in your organization",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
-			lists, err := env.apiv2Client.AccessLists(cmd.Context())
+			lists, err := env.session.client.AccessLists(cmd.Context())
 			if err != nil {
 				return err
 			}
@@ -85,7 +86,7 @@ func newAccessListsListCommand(env environment) *cobra.Command {
 	}
 }
 
-func newAccessListsShowCommand(env environment) *cobra.Command {
+func newAccessListsShowCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:   "show <id>",
 		Short: "Show one access list and the models it allows",
@@ -96,7 +97,7 @@ func newAccessListsShowCommand(env environment) *cobra.Command {
 				return err
 			}
 
-			list, err := env.apiv2Client.AccessList(cmd.Context(), id)
+			list, err := env.session.client.AccessList(cmd.Context(), id)
 			if err != nil {
 				return err
 			}
@@ -136,7 +137,7 @@ func newAccessListsShowCommand(env environment) *cobra.Command {
 	}
 }
 
-func newAccessListsCreateCommand(env environment) *cobra.Command {
+func newAccessListsCreateCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "create",
 		Short: "Create an access list",
@@ -180,7 +181,7 @@ func newAccessListsCreateCommand(env environment) *cobra.Command {
 			input.Transcription = models[client.ModalityTranscription]
 			input.Speech = models[client.ModalitySpeech]
 
-			created, err := env.apiv2Client.CreateAccessList(cmd.Context(), input)
+			created, err := env.session.client.CreateAccessList(cmd.Context(), input)
 			if err != nil {
 				return err
 			}
@@ -226,7 +227,7 @@ func exampleModel(modality client.Modality) string {
 	}
 }
 
-func newAccessListsSetCommand(env environment) *cobra.Command {
+func newAccessListsSetCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "set",
 		Short: "Set a property on an access list",
@@ -240,7 +241,7 @@ func newAccessListsSetCommand(env environment) *cobra.Command {
 	return cmd
 }
 
-func newAccessListsSetNameCommand(env environment) *cobra.Command {
+func newAccessListsSetNameCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:   "name <id> <name>",
 		Short: "Rename an access list",
@@ -256,7 +257,7 @@ func newAccessListsSetNameCommand(env environment) *cobra.Command {
 				return errors.New("missing name")
 			}
 
-			if err := env.apiv2Client.UpdateAccessListName(cmd.Context(), id, name); err != nil {
+			if err := env.session.client.UpdateAccessListName(cmd.Context(), id, name); err != nil {
 				return err
 			}
 
@@ -265,7 +266,7 @@ func newAccessListsSetNameCommand(env environment) *cobra.Command {
 	}
 }
 
-func newAccessListsSetAutoApproveCommand(env environment) *cobra.Command {
+func newAccessListsSetAutoApproveCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:   "auto-approve <id>",
 		Short: "Approve new models matching an access list automatically",
@@ -278,7 +279,7 @@ func newAccessListsSetAutoApproveCommand(env environment) *cobra.Command {
 				return err
 			}
 
-			if err := env.apiv2Client.UpdateAccessListAutoApprove(cmd.Context(), id, true); err != nil {
+			if err := env.session.client.UpdateAccessListAutoApprove(cmd.Context(), id, true); err != nil {
 				return err
 			}
 
@@ -288,7 +289,7 @@ func newAccessListsSetAutoApproveCommand(env environment) *cobra.Command {
 	}
 }
 
-func newAccessListsSetModelsCommand(env environment) *cobra.Command {
+func newAccessListsSetModelsCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:   "models <id> <modality> <model>...",
 		Short: "Set the models of one modality on an access list",
@@ -326,7 +327,7 @@ func newAccessListsSetModelsCommand(env environment) *cobra.Command {
 				return err
 			}
 
-			err = env.apiv2Client.UpdateAccessListModels(cmd.Context(), id, map[client.Modality][]string{modality: models})
+			err = env.session.client.UpdateAccessListModels(cmd.Context(), id, map[client.Modality][]string{modality: models})
 			if err != nil {
 				return err
 			}
@@ -338,7 +339,7 @@ func newAccessListsSetModelsCommand(env environment) *cobra.Command {
 	}
 }
 
-func newAccessListsClearCommand(env environment) *cobra.Command {
+func newAccessListsClearCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "clear",
 		Short: "Clear a property on an access list",
@@ -351,7 +352,7 @@ func newAccessListsClearCommand(env environment) *cobra.Command {
 	return cmd
 }
 
-func newAccessListsClearAutoApproveCommand(env environment) *cobra.Command {
+func newAccessListsClearAutoApproveCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:   "auto-approve <id>",
 		Short: "Stop approving new models on an access list automatically",
@@ -362,7 +363,7 @@ func newAccessListsClearAutoApproveCommand(env environment) *cobra.Command {
 				return err
 			}
 
-			if err := env.apiv2Client.UpdateAccessListAutoApprove(cmd.Context(), id, false); err != nil {
+			if err := env.session.client.UpdateAccessListAutoApprove(cmd.Context(), id, false); err != nil {
 				return err
 			}
 
@@ -372,7 +373,7 @@ func newAccessListsClearAutoApproveCommand(env environment) *cobra.Command {
 	}
 }
 
-func newAccessListsClearModelsCommand(env environment) *cobra.Command {
+func newAccessListsClearModelsCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:   "models <id> <modality>...",
 		Short: "Remove every model of one or more modalities from an access list",
@@ -409,7 +410,7 @@ func newAccessListsClearModelsCommand(env environment) *cobra.Command {
 				names = append(names, string(modality))
 			}
 
-			if err := env.apiv2Client.UpdateAccessListModels(cmd.Context(), id, cleared); err != nil {
+			if err := env.session.client.UpdateAccessListModels(cmd.Context(), id, cleared); err != nil {
 				return err
 			}
 
@@ -419,7 +420,7 @@ func newAccessListsClearModelsCommand(env environment) *cobra.Command {
 	}
 }
 
-func newAccessListsDeleteCommand(env environment) *cobra.Command {
+func newAccessListsDeleteCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "delete <id>",
 		Short: "Delete an access list",
@@ -453,7 +454,7 @@ func newAccessListsDeleteCommand(env environment) *cobra.Command {
 				}
 			}
 
-			if err := env.apiv2Client.DeleteAccessList(cmd.Context(), id); err != nil {
+			if err := env.session.client.DeleteAccessList(cmd.Context(), id); err != nil {
 				return err
 			}
 
diff --git a/cmd/api_keys.go b/cmd/api_keys.go
index e71e36f..0c638f4 100644
--- a/cmd/api_keys.go
+++ b/cmd/api_keys.go
@@ -24,7 +24,7 @@ const (
 	apiKeyYesFlag                   = "yes"
 )
 
-func newAPIKeysCommand(env environment) *cobra.Command {
+func newAPIKeysCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "api-keys",
 		Aliases: []string{"api-key", "keys"},
@@ -32,6 +32,7 @@ func newAPIKeysCommand(env environment) *cobra.Command {
 		Long: "Manage the API keys in your organization.\n\n" +
 			"The show command also takes " + client.SelfAPIKeyID +
 			" as the id, meaning the key this CLI is configured with.",
+		PersistentPreRunE: env.requireProfile,
 	}
 
 	cmd.PersistentFlags().Bool(jsonFlag, false, "print JSON instead of a table")
@@ -47,13 +48,13 @@ func newAPIKeysCommand(env environment) *cobra.Command {
 	return cmd
 }
 
-func newAPIKeysListCommand(env environment) *cobra.Command {
+func newAPIKeysListCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:   "list",
 		Short: "List the API keys in your organization",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
-			keys, err := env.apiv2Client.APIKeys(cmd.Context())
+			keys, err := env.session.client.APIKeys(cmd.Context())
 			if err != nil {
 				return err
 			}
@@ -84,7 +85,7 @@ func newAPIKeysListCommand(env environment) *cobra.Command {
 	}
 }
 
-func newAPIKeysShowCommand(env environment) *cobra.Command {
+func newAPIKeysShowCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:   "show <id>",
 		Short: "Show one API key",
@@ -98,7 +99,7 @@ func newAPIKeysShowCommand(env environment) *cobra.Command {
 				return err
 			}
 
-			key, err := env.apiv2Client.APIKey(cmd.Context(), id)
+			key, err := env.session.client.APIKey(cmd.Context(), id)
 			if err != nil {
 				return err
 			}
@@ -122,7 +123,7 @@ func newAPIKeysShowCommand(env environment) *cobra.Command {
 	}
 }
 
-func newAPIKeysCreateCommand(env environment) *cobra.Command {
+func newAPIKeysCreateCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "create",
 		Short: "Create an API key",
@@ -165,7 +166,7 @@ func newAPIKeysCreateCommand(env environment) *cobra.Command {
 			}
 			input.Permissions = permissions
 
-			created, err := env.apiv2Client.CreateAPIKey(cmd.Context(), input)
+			created, err := env.session.client.CreateAPIKey(cmd.Context(), input)
 			if err != nil {
 				return err
 			}
@@ -199,7 +200,7 @@ func newAPIKeysCreateCommand(env environment) *cobra.Command {
 	return cmd
 }
 
-func newAPIKeysSetCommand(env environment) *cobra.Command {
+func newAPIKeysSetCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "set",
 		Short: "Set a property on an API key",
@@ -213,7 +214,7 @@ func newAPIKeysSetCommand(env environment) *cobra.Command {
 	return cmd
 }
 
-func newAPIKeysSetLimitCommand(env environment) *cobra.Command {
+func newAPIKeysSetLimitCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:   "limit <id> <amount>",
 		Short: "Set the monthly spending cap of an API key",
@@ -231,7 +232,7 @@ func newAPIKeysSetLimitCommand(env environment) *cobra.Command {
 				return err
 			}
 
-			if err := env.apiv2Client.UpdateAPIKeyLimit(cmd.Context(), id, limit); err != nil {
+			if err := env.session.client.UpdateAPIKeyLimit(cmd.Context(), id, limit); err != nil {
 				return err
 			}
 
@@ -241,7 +242,7 @@ func newAPIKeysSetLimitCommand(env environment) *cobra.Command {
 	}
 }
 
-func newAPIKeysSetLabelsCommand(env environment) *cobra.Command {
+func newAPIKeysSetLabelsCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:   "labels <id> <key=value>...",
 		Short: "Set the labels on an API key",
@@ -271,7 +272,7 @@ func newAPIKeysSetLabelsCommand(env environment) *cobra.Command {
 				return err
 			}
 
-			if err := env.apiv2Client.UpdateAPIKeyLabels(cmd.Context(), id, labels); err != nil {
+			if err := env.session.client.UpdateAPIKeyLabels(cmd.Context(), id, labels); err != nil {
 				return err
 			}
 
@@ -281,7 +282,7 @@ func newAPIKeysSetLabelsCommand(env environment) *cobra.Command {
 	}
 }
 
-func newAPIKeysClearCommand(env environment) *cobra.Command {
+func newAPIKeysClearCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "clear",
 		Short: "Clear a property on an API key",
@@ -291,7 +292,7 @@ func newAPIKeysClearCommand(env environment) *cobra.Command {
 	return cmd
 }
 
-func newAPIKeysClearLabelsCommand(env environment) *cobra.Command {
+func newAPIKeysClearLabelsCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:   "labels <id>",
 		Short: "Remove every label from an API key",
@@ -302,7 +303,7 @@ func newAPIKeysClearLabelsCommand(env environment) *cobra.Command {
 				return err
 			}
 
-			if err := env.apiv2Client.UpdateAPIKeyLabels(cmd.Context(), id, nil); err != nil {
+			if err := env.session.client.UpdateAPIKeyLabels(cmd.Context(), id, nil); err != nil {
 				return err
 			}
 
@@ -311,7 +312,7 @@ func newAPIKeysClearLabelsCommand(env environment) *cobra.Command {
 	}
 }
 
-func newAPIKeysSetExpiryCommand(env environment) *cobra.Command {
+func newAPIKeysSetExpiryCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:   "expiry <id> <time|" + util.NeverExpires + ">",
 		Short: "Set when an API key stops working",
@@ -334,7 +335,7 @@ func newAPIKeysSetExpiryCommand(env environment) *cobra.Command {
 				expiresAt = &parsed
 			}
 
-			if err := env.apiv2Client.UpdateAPIKeyExpiry(cmd.Context(), id, expiresAt); err != nil {
+			if err := env.session.client.UpdateAPIKeyExpiry(cmd.Context(), id, expiresAt); err != nil {
 				return err
 			}
 
@@ -348,7 +349,7 @@ func newAPIKeysSetExpiryCommand(env environment) *cobra.Command {
 	}
 }
 
-func newAPIKeysDeleteCommand(env environment) *cobra.Command {
+func newAPIKeysDeleteCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "delete <id>",
 		Short: "Delete an API key",
@@ -381,7 +382,7 @@ func newAPIKeysDeleteCommand(env environment) *cobra.Command {
 				}
 			}
 
-			if err := env.apiv2Client.DeleteAPIKey(cmd.Context(), id); err != nil {
+			if err := env.session.client.DeleteAPIKey(cmd.Context(), id); err != nil {
 				return err
 			}
 
diff --git a/cmd/auth.go b/cmd/auth.go
index a19a480..4dc2c88 100644
--- a/cmd/auth.go
+++ b/cmd/auth.go
@@ -6,24 +6,23 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func newAuthCommand(env environment) *cobra.Command {
+func newAuthCommand(env *environment) *cobra.Command {
 	auth := &cobra.Command{
-		Use:    "auth",
-		Short:  "Credential helpers for integrations",
-		Args:   cobra.NoArgs,
-		Hidden: true,
+		Use:               "auth",
+		Short:             "Credential helpers for integrations",
+		Args:              cobra.NoArgs,
+		Hidden:            true,
+		PersistentPreRunE: env.requireProfile,
 	}
 
 	auth.AddCommand(&cobra.Command{
 		Use:   "token",
-		Short: "Print the configured Requesty API key",
-		Args:  cobra.NoArgs,
+		Short: "Print the Requesty API key of the profile in use",
+		Long: "Print the API key of the profile named with --" + profileFlag + " or " + profileEnv + ", else the\n" +
+			"current one. Harnesses that fetch their key on demand, such as Codex, call this.",
+		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
-			if env.config.APIKey == "" {
-				return fmt.Errorf("no Requesty API key configured")
-			}
-
-			if _, err := fmt.Fprintln(cmd.OutOrStdout(), env.config.APIKey); err != nil {
+			if _, err := fmt.Fprintln(cmd.OutOrStdout(), env.session.config.APIKey); err != nil {
 				return fmt.Errorf("failed to print API key: %w", err)
 			}
 			return nil
diff --git a/cmd/environment.go b/cmd/environment.go
new file mode 100644
index 0000000..530ee86
--- /dev/null
+++ b/cmd/environment.go
@@ -0,0 +1,102 @@
+package cmd
+
+import (
+	"errors"
+	"fmt"
+
+	"github.com/requestyai/cli/internal/client"
+	"github.com/requestyai/cli/internal/config"
+	"github.com/requestyai/cli/internal/onboarding"
+	"github.com/spf13/cobra"
+)
+
+const (
+	// profileFlag names the saved profile to run with. It lives on the root
+	// so every subcommand inherits it; harness commands parse it themselves.
+	profileFlag = "profile"
+	// profileEnv is the environment variable that stands in for --profile.
+	profileEnv = "REQUESTY_PROFILE"
+	// defaultProfileName is what onboarding calls the first profile.
+	defaultProfileName = "default"
+)
+
+// environment is the profile store and, once a profile has been picked, the
+// session the commands share.
+type environment struct {
+	store   config.Store
+	session *session
+}
+
+type session struct {
+	config config.Config
+	client *client.Client
+}
+
+func newSession(cfg config.Config) *session {
+	return &session{config: cfg, client: client.New(cfg)}
+}
+
+func newEnvironment() (*environment, error) {
+	store, err := config.Load()
+	if err != nil {
+		return nil, fmt.Errorf("failed to load config: %w", err)
+	}
+
+	return &environment{store: store}, nil
+}
+
+// requireProfile is the PersistentPreRunE of the command groups that cannot
+// run without a key. It resolves the profile once and hands the commands a
+// client for it.
+func (env *environment) requireProfile(cmd *cobra.Command, _ []string) error {
+	cfg, err := env.resolveProfile(cmd, "")
+	if err != nil {
+		return err
+	}
+	env.session = newSession(cfg)
+
+	return nil
+}
+
+// resolveProfile returns the profile selected for this command.
+func (env *environment) resolveProfile(cmd *cobra.Command, name string) (config.Config, error) {
+	if name == "" {
+		name = requestedProfile(cmd)
+	}
+
+	return env.store.Resolve(name)
+}
+
+// ensureProfile returns the selected profile, running onboarding when none
+// has been saved yet.
+func (env *environment) ensureProfile(cmd *cobra.Command, name, harness string) (config.Config, error) {
+	cfg, err := env.resolveProfile(cmd, name)
+	if !errors.Is(err, config.ErrNoProfiles) {
+		return cfg, err
+	}
+
+	cfg, err = onboarding.Run(cmd.Context(), onboarding.Options{
+		Config:  config.Config{RouterBaseURL: config.DefaultRouterBaseURL},
+		Harness: harness,
+	})
+	if err != nil {
+		return config.Config{}, err
+	}
+	if err := env.save(defaultProfileName, cfg); err != nil {
+		return config.Config{}, err
+	}
+	cfg.Name = defaultProfileName
+
+	return cfg, nil
+}
+
+// save stores cfg as the named profile and writes the file. The first profile
+// saved becomes current.
+func (env *environment) save(name string, cfg config.Config) error {
+	env.store.Set(name, cfg)
+	if err := config.Save(env.store); err != nil {
+		return fmt.Errorf("failed to save config: %w", err)
+	}
+
+	return nil
+}
diff --git a/cmd/groups.go b/cmd/groups.go
index 82c3d39..171310c 100644
--- a/cmd/groups.go
+++ b/cmd/groups.go
@@ -17,7 +17,7 @@ const (
 	groupYesFlag          = "yes"
 )
 
-func newGroupsCommand(env environment) *cobra.Command {
+func newGroupsCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "groups",
 		Aliases: []string{"group"},
@@ -25,6 +25,7 @@ func newGroupsCommand(env environment) *cobra.Command {
 		Long: "Manage the groups in your organization.\n\n" +
 			"A group gathers users under a shared budget. Members are existing users of\n" +
 			"your organization, referred to by their user id.",
+		PersistentPreRunE: env.requireProfile,
 	}
 
 	cmd.PersistentFlags().Bool(jsonFlag, false, "print JSON instead of a table")
@@ -39,13 +40,13 @@ func newGroupsCommand(env environment) *cobra.Command {
 	return cmd
 }
 
-func newGroupsListCommand(env environment) *cobra.Command {
+func newGroupsListCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:   "list",
 		Short: "List the groups in your organization",
 		Args:  cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
-			groups, err := env.apiv2Client.Groups(cmd.Context())
+			groups, err := env.session.client.Groups(cmd.Context())
 			if err != nil {
 				return err
 			}
@@ -77,7 +78,7 @@ func newGroupsListCommand(env environment) *cobra.Command {
 	}
 }
 
-func newGroupsShowCommand(env environment) *cobra.Command {
+func newGroupsShowCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:   "show <id>",
 		Short: "Show one group and its members",
@@ -88,7 +89,7 @@ func newGroupsShowCommand(env environment) *cobra.Command {
 				return err
 			}
 
-			group, err := env.apiv2Client.Group(cmd.Context(), id)
+			group, err := env.session.client.Group(cmd.Context(), id)
 			if err != nil {
 				return err
 			}
@@ -158,7 +159,7 @@ func groupBudgetFields(group client.GroupDetails) [][2]string {
 
 	return fields
 }
-func newGroupsCreateCommand(env environment) *cobra.Command {
+func newGroupsCreateCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "create",
 		Short: "Create a group",
@@ -189,7 +190,7 @@ func newGroupsCreateCommand(env environment) *cobra.Command {
 				input.MonthlyLimit = &limit
 			}
 
-			created, err := env.apiv2Client.CreateGroup(cmd.Context(), input)
+			created, err := env.session.client.CreateGroup(cmd.Context(), input)
 			if err != nil {
 				return err
 			}
@@ -214,7 +215,7 @@ func newGroupsCreateCommand(env environment) *cobra.Command {
 	return cmd
 }
 
-func newGroupsDeleteCommand(env environment) *cobra.Command {
+func newGroupsDeleteCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "delete <id>",
 		Short: "Delete a group",
@@ -248,7 +249,7 @@ func newGroupsDeleteCommand(env environment) *cobra.Command {
 				}
 			}
 
-			if err := env.apiv2Client.DeleteGroup(cmd.Context(), id); err != nil {
+			if err := env.session.client.DeleteGroup(cmd.Context(), id); err != nil {
 				return err
 			}
 
@@ -267,7 +268,7 @@ func newGroupsDeleteCommand(env environment) *cobra.Command {
 	return cmd
 }
 
-func newGroupsMembersCommand(env environment) *cobra.Command {
+func newGroupsMembersCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:     "members",
 		Aliases: []string{"member"},
@@ -285,7 +286,7 @@ func newGroupsMembersCommand(env environment) *cobra.Command {
 	return cmd
 }
 
-func newGroupsMembersAddCommand(env environment) *cobra.Command {
+func newGroupsMembersAddCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "add <group-id> <user-id>",
 		Short: "Add a member to a group",
@@ -305,7 +306,7 @@ func newGroupsMembersAddCommand(env environment) *cobra.Command {
 				return err
 			}
 
-			if err := env.apiv2Client.AddGroupMember(cmd.Context(), groupID, userID, role); err != nil {
+			if err := env.session.client.AddGroupMember(cmd.Context(), groupID, userID, role); err != nil {
 				return err
 			}
 
@@ -329,7 +330,7 @@ func newGroupsMembersAddCommand(env environment) *cobra.Command {
 	return cmd
 }
 
-func newGroupsMembersUpdateCommand(env environment) *cobra.Command {
+func newGroupsMembersUpdateCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "update <group-id> <user-id> --role <admin|member>",
 		Short: "Update the role of a group member",
@@ -349,7 +350,7 @@ func newGroupsMembersUpdateCommand(env environment) *cobra.Command {
 				return err
 			}
 
-			if err := env.apiv2Client.UpdateGroupMemberRole(cmd.Context(), groupID, userID, role); err != nil {
+			if err := env.session.client.UpdateGroupMemberRole(cmd.Context(), groupID, userID, role); err != nil {
 				return err
 			}
 
@@ -366,7 +367,7 @@ func newGroupsMembersUpdateCommand(env environment) *cobra.Command {
 	return cmd
 }
 
-func newGroupsMembersRemoveCommand(env environment) *cobra.Command {
+func newGroupsMembersRemoveCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:     "remove <group-id> <user-id>",
 		Aliases: []string{"rm"},
@@ -380,7 +381,7 @@ func newGroupsMembersRemoveCommand(env environment) *cobra.Command {
 				return err
 			}
 
-			if err := env.apiv2Client.RemoveGroupMember(cmd.Context(), groupID, userID); err != nil {
+			if err := env.session.client.RemoveGroupMember(cmd.Context(), groupID, userID); err != nil {
 				return err
 			}
 
diff --git a/cmd/harness.go b/cmd/harness.go
index c00c9e3..02d1a0b 100644
--- a/cmd/harness.go
+++ b/cmd/harness.go
@@ -12,8 +12,9 @@ import (
 )
 
 const (
-	harnessModelFlag  = "--model"
-	harnessEffortFlag = "--reasoning-effort"
+	harnessProfileFlag = "--" + profileFlag
+	harnessModelFlag   = "--model"
+	harnessEffortFlag  = "--reasoning-effort"
 )
 
 // errHarnessHelp signals that the leading flags asked for help.
@@ -21,7 +22,7 @@ var errHarnessHelp = errors.New("help requested")
 
 // newHarnessCommands returns the `requesty <harness>` commands, each of which
 // starts a harness with Requesty injected for that run.
-func newHarnessCommands(env environment) []*cobra.Command {
+func newHarnessCommands(env *environment) []*cobra.Command {
 	return []*cobra.Command{
 		newHarnessCommand(env, "claude", "Claude Code", func(cfg config.Config) (harnesses.Harness, error) {
 			dir, err := harnesses.DefaultConfigDirClaudeCode()
@@ -41,15 +42,16 @@ func newHarnessCommands(env environment) []*cobra.Command {
 }
 
 // newHarnessCommand builds `requesty <binary>`. The harness is constructed
-// lazily, from the config as it stands after any onboarding, so a machine
+// lazily, from the profile as it stands after any onboarding, so a machine
 // without a resolvable home directory still gets a help page and a clear
 // error, rather than a missing command.
-func newHarnessCommand(env environment, binary, displayName string, newHarness func(config.Config) (harnesses.Harness, error)) *cobra.Command {
+func newHarnessCommand(env *environment, binary, displayName string, newHarness func(config.Config) (harnesses.Harness, error)) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   fmt.Sprintf("%s [--model <id>] [--reasoning-effort <level>] [-- ] [%s args...]", binary, binary),
+		Use:   fmt.Sprintf("%s [--profile <name>] [--model <id>] [--reasoning-effort <level>] [-- ] [%s args...]", binary, binary),
 		Short: fmt.Sprintf("Launch %s through Requesty", displayName),
 		Long: fmt.Sprintf("Launch %s with its traffic routed through Requesty for this run only.\n\n", displayName) +
 			"Flags:\n" +
+			fmt.Sprintf("  %-28s %s\n", harnessProfileFlag+" <name>", "Saved profile to run as (also "+profileEnv+")") +
 			fmt.Sprintf("  %-28s %s\n", harnessModelFlag+" <id>", "Model to use for this run (any Requesty model id)") +
 			fmt.Sprintf("  %-28s %s\n", harnessEffortFlag+" <level>", "Reasoning effort: "+strings.Join(harnesses.Efforts, ", ")) +
 			fmt.Sprintf("  %-28s %s\n\n", "-h, --help", "Show this help") +
@@ -59,7 +61,7 @@ func newHarnessCommand(env environment, binary, displayName string, newHarness f
 		DisableFlagsInUseLine: true,
 		SilenceUsage:          true,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			opts, err := parseHarnessArgs(args)
+			parsed, err := parseHarnessArgs(args)
 			if errors.Is(err, errHarnessHelp) {
 				return cmd.Help()
 			}
@@ -67,7 +69,7 @@ func newHarnessCommand(env environment, binary, displayName string, newHarness f
 				return err
 			}
 
-			cfg, err := env.ensureAPIKey(cmd, displayName)
+			cfg, err := env.ensureProfile(cmd, parsed.profile, displayName)
 			if err != nil {
 				return err
 			}
@@ -77,72 +79,81 @@ func newHarnessCommand(env environment, binary, displayName string, newHarness f
 				return fmt.Errorf("failed to set up %s: %w", displayName, err)
 			}
 
-			return harness.Launch(opts)
+			return harness.Launch(parsed.launch)
 		},
 	}
 
 	return cmd
 }
 
+// harnessArgs is a harness command line split into our profile choice and
+// what the harness is launched with.
+type harnessArgs struct {
+	profile string
+	launch  harnesses.LaunchOptions
+}
+
 // parseHarnessArgs splits our leading flags from the harness's own arguments.
 // A bare `--` ends our flags explicitly; otherwise the first token we do not
 // recognise does. That keeps `requesty claude --model x -p "hi"` and
 // `requesty claude -p "hi"` both working, and lets a harness flag that happens
 // to share a name with ours (`codex --model`) still reach the harness when it
 // appears later.
-func parseHarnessArgs(args []string) (harnesses.LaunchOptions, error) {
-	var opts harnesses.LaunchOptions
+func parseHarnessArgs(args []string) (harnessArgs, error) {
+	var parsed harnessArgs
 
 	for len(args) > 0 {
 		arg := args[0]
 
 		switch {
 		case arg == "--":
-			opts.Args = args[1:]
-			return opts, nil
+			parsed.launch.Args = args[1:]
+			return parsed, nil
 
 		case arg == "-h" || arg == "--help":
-			return opts, errHarnessHelp
+			return parsed, errHarnessHelp
 
-		case arg == harnessModelFlag || arg == harnessEffortFlag:
+		case arg == harnessProfileFlag || arg == harnessModelFlag || arg == harnessEffortFlag:
 			if len(args) < 2 {
-				return opts, fmt.Errorf("%s requires a value", arg)
+				return parsed, fmt.Errorf("%s requires a value", arg)
 			}
-			if err := setHarnessFlag(&opts, arg, args[1]); err != nil {
-				return opts, err
+			if err := parsed.set(arg, args[1]); err != nil {
+				return parsed, err
 			}
 			args = args[2:]
 
-		case strings.HasPrefix(arg, harnessModelFlag+"=") || strings.HasPrefix(arg, harnessEffortFlag+"="):
+		case strings.HasPrefix(arg, harnessProfileFlag+"=") || strings.HasPrefix(arg, harnessModelFlag+"=") || strings.HasPrefix(arg, harnessEffortFlag+"="):
 			flag, value, _ := strings.Cut(arg, "=")
-			if err := setHarnessFlag(&opts, flag, value); err != nil {
-				return opts, err
+			if err := parsed.set(flag, value); err != nil {
+				return parsed, err
 			}
 			args = args[1:]
 
 		default:
-			opts.Args = args
-			return opts, nil
+			parsed.launch.Args = args
+			return parsed, nil
 		}
 	}
 
-	return opts, nil
+	return parsed, nil
 }
 
-func setHarnessFlag(opts *harnesses.LaunchOptions, flag, value string) error {
+func (p *harnessArgs) set(flag, value string) error {
 	value = strings.TrimSpace(value)
 	if value == "" {
 		return fmt.Errorf("%s requires a value", flag)
 	}
 
 	switch flag {
+	case harnessProfileFlag:
+		p.profile = value
 	case harnessModelFlag:
-		opts.Model = value
+		p.launch.Model = value
 	case harnessEffortFlag:
 		if !slices.Contains(harnesses.Efforts, value) {
 			return fmt.Errorf("%s must be one of %s (got %q)", flag, strings.Join(harnesses.Efforts, ", "), value)
 		}
-		opts.Effort = value
+		p.launch.Effort = value
 	}
 
 	return nil
diff --git a/cmd/harness_test.go b/cmd/harness_test.go
index d73aaa8..7044995 100644
--- a/cmd/harness_test.go
+++ b/cmd/harness_test.go
@@ -4,14 +4,13 @@ import (
 	"bytes"
 	"testing"
 
-	"github.com/requestyai/cli/internal/config"
 	"github.com/requestyai/cli/internal/harnesses"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
 func TestHarnessCommandsAreRegistered(t *testing.T) {
-	command := newRootCommand(environment{})
+	command := newRootCommand(&environment{})
 
 	for _, name := range []string{"claude", "codex"} {
 		sub, _, err := command.Find([]string{name})
@@ -25,42 +24,45 @@ func TestParseHarnessArgs(t *testing.T) {
 	tests := []struct {
 		name string
 		args []string
-		want harnesses.LaunchOptions
+		want harnessArgs
 	}{
 		{
 			name: "no arguments",
 			args: nil,
-			want: harnesses.LaunchOptions{},
+			want: harnessArgs{},
 		},
 		{
 			name: "leading flags then passthrough",
-			args: []string{"--model", "anthropic/claude-fable-5", "--reasoning-effort=high", "--dangerously-skip-permissions", "-p", "hi"},
-			want: harnesses.LaunchOptions{
-				Model:  "anthropic/claude-fable-5",
-				Effort: harnesses.EffortHigh,
-				Args:   []string{"--dangerously-skip-permissions", "-p", "hi"},
+			args: []string{"--profile", "eu", "--model", "anthropic/claude-fable-5", "--reasoning-effort=high", "--dangerously-skip-permissions", "-p", "hi"},
+			want: harnessArgs{
+				profile: "eu",
+				launch: harnesses.LaunchOptions{
+					Model:  "anthropic/claude-fable-5",
+					Effort: harnesses.EffortHigh,
+					Args:   []string{"--dangerously-skip-permissions", "-p", "hi"},
+				},
 			},
 		},
 		{
-			name: "equals form for both flags",
-			args: []string{"--model=openai/gpt-5", "--reasoning-effort=low"},
-			want: harnesses.LaunchOptions{Model: "openai/gpt-5", Effort: harnesses.EffortLow},
+			name: "equals form for every flag",
+			args: []string{"--profile=eu", "--model=openai/gpt-5", "--reasoning-effort=low"},
+			want: harnessArgs{profile: "eu", launch: harnesses.LaunchOptions{Model: "openai/gpt-5", Effort: harnesses.EffortLow}},
 		},
 		{
 			// The second --model belongs to the harness because a foreign flag came first.
 			name: "stops at first foreign argument",
 			args: []string{"--full-auto", "--model", "theirs"},
-			want: harnesses.LaunchOptions{Args: []string{"--full-auto", "--model", "theirs"}},
+			want: harnessArgs{launch: harnesses.LaunchOptions{Args: []string{"--full-auto", "--model", "theirs"}}},
 		},
 		{
 			name: "double dash ends our flags",
 			args: []string{"--model", "openai/gpt-5", "--", "--model", "theirs"},
-			want: harnesses.LaunchOptions{Model: "openai/gpt-5", Args: []string{"--model", "theirs"}},
+			want: harnessArgs{launch: harnesses.LaunchOptions{Model: "openai/gpt-5", Args: []string{"--model", "theirs"}}},
 		},
 		{
 			name: "bare double dash passes nothing",
 			args: []string{"--"},
-			want: harnesses.LaunchOptions{Args: []string{}},
+			want: harnessArgs{launch: harnesses.LaunchOptions{Args: []string{}}},
 		},
 	}
 
@@ -90,6 +92,11 @@ func TestParseHarnessArgsErrors(t *testing.T) {
 			args: []string{"--model"},
 			want: "--model requires a value",
 		},
+		{
+			name: "profile without value",
+			args: []string{"--profile"},
+			want: "--profile requires a value",
+		},
 		{
 			name: "effort without value",
 			args: []string{"--reasoning-effort"},
@@ -125,17 +132,37 @@ func TestParseHarnessArgsHelp(t *testing.T) {
 	// After the harness's own flags begin, -h belongs to the harness.
 	got, err := parseHarnessArgs([]string{"-p", "hi", "--help"})
 	require.NoError(t, err)
-	assert.Equal(t, []string{"-p", "hi", "--help"}, got.Args)
+	assert.Equal(t, []string{"-p", "hi", "--help"}, got.launch.Args)
 }
 
 func TestHarnessCommandHelpShowsOurFlags(t *testing.T) {
-	command := newRootCommand(environment{config: config.Config{APIKey: "my-api-key"}})
+	command := newRootCommand(&environment{store: oneProfile})
 	var output bytes.Buffer
 	command.SetOut(&output)
 	command.SetArgs([]string{"claude", "--help"})
 
 	require.NoError(t, command.Execute())
 
+	assert.Contains(t, output.String(), "--profile")
 	assert.Contains(t, output.String(), "--reasoning-effort")
 	assert.Contains(t, output.String(), "passed to `claude`")
 }
+
+func TestHarnessProfileFlag(t *testing.T) {
+	command := newRootCommand(&environment{store: twoProfiles})
+	command.SetArgs([]string{"claude", "--profile", "sales"})
+
+	err := command.Execute()
+
+	require.ErrorContains(t, err, `profile "sales" not found`)
+}
+
+func TestHarnessProfileFromEnvironment(t *testing.T) {
+	t.Setenv(profileEnv, "sales")
+	command := newRootCommand(&environment{store: twoProfiles})
+	command.SetArgs([]string{"claude"})
+
+	err := command.Execute()
+
+	require.ErrorContains(t, err, `profile "sales" not found`)
+}
diff --git a/cmd/login.go b/cmd/login.go
index 6ec24b8..63265b9 100644
--- a/cmd/login.go
+++ b/cmd/login.go
@@ -11,58 +11,68 @@ import (
 )
 
 const (
-	loginGroupFlag  = "group"
-	loginForceFlag  = "force"
-	loginAPIKeyFlag = "api-key"
+	loginGroupFlag     = "group"
+	loginForceFlag     = "force"
+	loginAPIKeyFlag    = "api-key"
+	loginRouterURLFlag = "router-url"
 )
 
 var errUnrecognisedAPIKey = errors.New("that API key was not recognised; copy it again from " + onboarding.APIKeysURL)
 
-func newLoginCommand(env environment) *cobra.Command {
+func newLoginCommand(env *environment) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "login [--group <name>] [--api-key <key>] [--force]",
-		Short: "Sign in to Requesty and set this machine up",
-		Long: "Sign in to Requesty in your browser and set this machine up.\n\n" +
+		Use:   "login [--group <name>] [--profile <name>] [--api-key <key>] [--router-url <url>] [--force]",
+		Short: "Sign in to Requesty and save a profile on this machine",
+		Long: "Sign in to Requesty in your browser and save a profile on this machine.\n\n" +
 			"Once you approve in the browser, the CLI creates an API key in your Requesty\n" +
-			"account and saves it to " + config.DisplayPath() + ", where `requesty claude`,\n" +
-			"`requesty codex` and the terminal app pick it up. The key is named after this\n" +
-			"machine so you can recognise it on " + onboarding.APIKeysURL + ".\n\n" +
+			"account and saves it as a profile in " + config.DisplayPath() + ", where\n" +
+			"`requesty claude`, `requesty codex` and the terminal app pick it up. The key is\n" +
+			"named after this machine so you can recognise it on " + onboarding.APIKeysURL + ".\n\n" +
 			"The key goes in your group. With several groups you are asked which, or you can\n" +
-			"name one with --group. Without any group the key is a personal one.\n\n" +
+			"name one with --group. Without any group the key is a personal one. The profile\n" +
+			"is called `" + defaultProfileName + "` unless you pass --profile; the first one saved becomes current.\n\n" +
 			"The browser hands the sign-in back to this machine on 127.0.0.1, which does not\n" +
 			"work over SSH. There, pass --api-key with a key from " + onboarding.APIKeysURL + "\n" +
 			"instead; it is checked against the gateway and saved.\n\n" +
-			"When a working key is already saved nothing is created; pass --force to replace\n" +
-			"it with a new one.",
+			"An existing profile is left alone; pass --force to replace its key.",
 		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			groupID, _ := cmd.Flags().GetString(loginGroupFlag)
 			apiKey, _ := cmd.Flags().GetString(loginAPIKeyFlag)
+			routerURL, _ := cmd.Flags().GetString(loginRouterURLFlag)
 			force, _ := cmd.Flags().GetBool(loginForceFlag)
 
-			if env.config.APIKey != "" && !force {
-				err := env.apiv2Client.CheckAPIKey(cmd.Context())
-				switch {
-				case err == nil:
-					_, err := fmt.Fprintf(cmd.OutOrStdout(),
-						"Already signed in: an API key is saved in %s.\nRun `requesty login --force` to replace it with a new one.\n",
-						config.DisplayPath())
-					return err
-				case errors.Is(err, client.ErrInvalidAPIKey):
-					_, _ = fmt.Fprintln(cmd.ErrOrStderr(), "The saved API key is no longer valid; signing in again.")
-				default:
-					return fmt.Errorf("failed to check the saved API key: %w", err)
+			name := requestedProfile(cmd)
+			if name == "" {
+				name = defaultProfileName
+			}
+			if existing, ok := env.store.Profiles[name]; ok {
+				if !force {
+					return fmt.Errorf("profile %q already exists; pass --force to replace it", name)
+				}
+				if routerURL == "" {
+					routerURL = existing.RouterBaseURL
 				}
 			}
+			if routerURL == "" {
+				routerURL = config.DefaultRouterBaseURL
+			}
+			cfg := config.Config{APIKey: apiKey, RouterBaseURL: routerURL}
 
-			if apiKey != "" {
-				return env.saveAPIKey(cmd, apiKey)
+			if apiKey == "" {
+				var err error
+				cfg, err = onboarding.RunHeadless(cmd.Context(), onboarding.Options{Config: cfg, GroupID: groupID})
+				if err != nil {
+					return err
+				}
+			} else if err := checkAPIKey(cmd, cfg); err != nil {
+				return err
 			}
 
-			_, err := onboarding.RunHeadless(cmd.Context(), onboarding.Options{
-				Config:  env.config,
-				GroupID: groupID,
-			})
+			if err := env.save(name, cfg); err != nil {
+				return err
+			}
+			_, err := fmt.Fprintf(cmd.OutOrStdout(), "Saved profile %q to %s.\n", name, config.DisplayPath())
 
 			return err
 		},
@@ -70,18 +80,16 @@ func newLoginCommand(env environment) *cobra.Command {
 
 	cmd.Flags().String(loginGroupFlag, "", "group to create the API key in, by name or id")
 	cmd.Flags().String(loginAPIKeyFlag, "", "save an existing API key instead of signing in")
-	cmd.Flags().Bool(loginForceFlag, false, "create a new API key even when one is already saved")
+	cmd.Flags().String(loginRouterURLFlag, "", "router for the profile (default: the one it has, else "+config.DefaultRouterBaseURL+")")
+	cmd.Flags().Bool(loginForceFlag, false, "replace the profile's key when it already exists")
 
 	return cmd
 }
 
-// saveAPIKey stores a key the user already has, once the gateway confirms it
-// is live. This is the route for machines where the browser cannot hand the
-// sign-in back, such as over SSH.
-func (env environment) saveAPIKey(cmd *cobra.Command, apiKey string) error {
-	cfg := env.config
-	cfg.APIKey = apiKey
-
+// checkAPIKey asks the gateway whether a key the user supplied is live before
+// it is saved. This is the route for machines where the browser cannot hand
+// the sign-in back, such as over SSH.
+func checkAPIKey(cmd *cobra.Command, cfg config.Config) error {
 	err := client.New(cfg).CheckAPIKey(cmd.Context())
 	if errors.Is(err, client.ErrInvalidAPIKey) {
 		return errUnrecognisedAPIKey
@@ -90,11 +98,5 @@ func (env environment) saveAPIKey(cmd *cobra.Command, apiKey string) error {
 		return fmt.Errorf("failed to check the api key: %w", err)
 	}
 
-	if err := config.Save(cfg); err != nil {
-		return fmt.Errorf("failed to save config: %w", err)
-	}
-
-	_, err = fmt.Fprintf(cmd.OutOrStdout(), "Saved your API key to %s.\n", config.DisplayPath())
-
-	return err
+	return nil
 }
diff --git a/cmd/login_test.go b/cmd/login_test.go
index 2e7d708..70808f9 100644
--- a/cmd/login_test.go
+++ b/cmd/login_test.go
@@ -6,14 +6,13 @@ import (
 	"net/http/httptest"
 	"testing"
 
-	"github.com/requestyai/cli/internal/client"
 	"github.com/requestyai/cli/internal/config"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
 
 // checkServer answers /v1/auth/check with status, standing in for the gateway
-// when a login has to decide whether the saved key still works.
+// when a login has to decide whether a supplied key works.
 func checkServer(t *testing.T, status int) *httptest.Server {
 	t.Helper()
 
@@ -26,77 +25,84 @@ func checkServer(t *testing.T, status int) *httptest.Server {
 	return server
 }
 
-func loginEnvironment(cfg config.Config) environment {
-	return environment{config: cfg, apiv2Client: client.New(cfg)}
-}
-
-func TestLoginDoesNothingWhenKeyStillWorks(t *testing.T) {
+func TestLoginSavesValidatedKeyAsCurrentDefaultProfile(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
 	server := checkServer(t, http.StatusOK)
-	env := loginEnvironment(config.Config{APIKey: "rqsty-old", RouterBaseURL: server.URL})
 	var output bytes.Buffer
-	command := newRootCommand(env)
+	command := newRootCommand(&environment{})
 	command.SetOut(&output)
-	command.SetArgs([]string{"login"})
+	command.SetArgs([]string{"login", "--api-key", "rqsty-existing", "--router-url", server.URL})
 
 	require.NoError(t, command.Execute())
 
-	assert.Contains(t, output.String(), "Already signed in")
-	assert.Contains(t, output.String(), "requesty login --force")
+	saved, err := config.Load()
+	require.NoError(t, err)
+	assert.Equal(t, defaultProfileName, saved.Current)
+	assert.Equal(t, config.Config{APIKey: "rqsty-existing", RouterBaseURL: server.URL}, saved.Profiles[defaultProfileName])
+	assert.Contains(t, output.String(), `Saved profile "default"`)
+	assert.NotContains(t, output.String(), "rqsty-existing")
 }
 
-func TestLoginReportsCheckFailure(t *testing.T) {
-	server := checkServer(t, http.StatusBadGateway)
-	env := loginEnvironment(config.Config{APIKey: "rqsty-old", RouterBaseURL: server.URL})
-	command := newRootCommand(env)
-	command.SetArgs([]string{"login"})
+func TestLoginSavesNamedProfileWithoutChangingCurrent(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+	server := checkServer(t, http.StatusOK)
+	command := newRootCommand(&environment{store: clone(oneProfile)})
+	command.SetOut(&bytes.Buffer{})
+	command.SetArgs([]string{"login", "--api-key", "rqsty-manage", "--profile", "manage", "--router-url", server.URL})
+
+	require.NoError(t, command.Execute())
+
+	saved, err := config.Load()
+	require.NoError(t, err)
+	assert.Equal(t, "work", saved.Current)
+	assert.Equal(t, "rqsty-manage", saved.Profiles["manage"].APIKey)
+}
+
+func TestLoginRequiresForceToReplaceProfile(t *testing.T) {
+	server := checkServer(t, http.StatusOK)
+	store := config.Store{Current: "default", Profiles: map[string]config.Config{"default": {APIKey: "rqsty-old", RouterBaseURL: server.URL}}}
+	command := newRootCommand(&environment{store: store})
+	command.SetArgs([]string{"login", "--api-key", "rqsty-new"})
 
 	err := command.Execute()
 
-	require.ErrorContains(t, err, "failed to check the saved API key")
+	require.ErrorContains(t, err, "pass --force")
 }
 
-func TestLoginSavesAValidatedAPIKey(t *testing.T) {
+func TestLoginForceReplacesKeyAndKeepsRouter(t *testing.T) {
 	t.Setenv("HOME", t.TempDir())
 	server := checkServer(t, http.StatusOK)
-	env := loginEnvironment(config.Config{RouterBaseURL: server.URL})
-	var output bytes.Buffer
-	command := newRootCommand(env)
-	command.SetOut(&output)
-	command.SetArgs([]string{"login", "--api-key", "rqsty-existing"})
+	store := config.Store{Current: "default", Profiles: map[string]config.Config{"default": {APIKey: "rqsty-old", RouterBaseURL: server.URL}}}
+	command := newRootCommand(&environment{store: store})
+	command.SetOut(&bytes.Buffer{})
+	command.SetArgs([]string{"login", "--api-key", "rqsty-new", "--force"})
 
 	require.NoError(t, command.Execute())
 
 	saved, err := config.Load()
 	require.NoError(t, err)
-	assert.Equal(t, config.Config{
-		APIKey:        "rqsty-existing",
-		RouterBaseURL: server.URL,
-	}, saved, "the key is added to the loaded config, which is otherwise saved as it was")
-	assert.Contains(t, output.String(), "Saved your API key")
-	assert.NotContains(t, output.String(), "rqsty-existing")
+	assert.Equal(t, config.Config{APIKey: "rqsty-new", RouterBaseURL: server.URL}, saved.Profiles["default"])
 }
 
-func TestLoginRejectsAnUnrecognisedAPIKey(t *testing.T) {
+func TestLoginRejectsUnrecognisedKeyWithoutSaving(t *testing.T) {
 	t.Setenv("HOME", t.TempDir())
 	server := checkServer(t, http.StatusUnauthorized)
-	env := loginEnvironment(config.Config{RouterBaseURL: server.URL})
-	command := newRootCommand(env)
-	command.SetArgs([]string{"login", "--api-key", "rqsty-typo"})
+	command := newRootCommand(&environment{})
+	command.SetArgs([]string{"login", "--api-key", "rqsty-typo", "--router-url", server.URL})
 
 	require.ErrorIs(t, command.Execute(), errUnrecognisedAPIKey)
 
 	saved, err := config.Load()
 	require.NoError(t, err)
-	assert.Empty(t, saved.APIKey, "a rejected key must not be written")
+	assert.Empty(t, saved.Profiles)
 }
 
 func TestLoginFlagsAreRegistered(t *testing.T) {
-	command := newRootCommand(environment{})
-
+	command := newRootCommand(&environment{})
 	login, _, err := command.Find([]string{"login"})
 	require.NoError(t, err)
-
-	for _, name := range []string{loginGroupFlag, loginAPIKeyFlag, loginForceFlag} {
+	for _, name := range []string{loginGroupFlag, loginAPIKeyFlag, loginForceFlag, loginRouterURLFlag} {
 		assert.NotNil(t, login.Flags().Lookup(name), "missing --%s", name)
 	}
+	assert.NotNil(t, login.InheritedFlags().Lookup(profileFlag))
 }
diff --git a/cmd/profiles.go b/cmd/profiles.go
new file mode 100644
index 0000000..66c12ad
--- /dev/null
+++ b/cmd/profiles.go
@@ -0,0 +1,133 @@
+package cmd
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/requestyai/cli/internal/config"
+	"github.com/requestyai/cli/internal/onboarding"
+	"github.com/spf13/cobra"
+)
+
+func newProfilesCommand(env *environment) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "profiles",
+		Aliases: []string{"profile"},
+		Short:   "Manage the profiles saved on this machine",
+		Long: "Manage the profiles saved in " + config.DisplayPath() + ".\n\n" +
+			"A profile is one sign-in: an API key and the router it goes to. `requesty login`\n" +
+			"creates them; pick one for a run with --" + profileFlag + " or " + profileEnv + ", or make it\n" +
+			"current with `requesty profiles use`.",
+	}
+
+	cmd.PersistentFlags().Bool(jsonFlag, false, "print JSON instead of a table")
+	cmd.AddCommand(
+		newProfilesListCommand(env),
+		newProfilesUseCommand(env),
+		newProfilesRemoveCommand(env),
+	)
+
+	return cmd
+}
+
+// profileListing is one profile as `profiles list --json` prints it; the key
+// itself stays out.
+type profileListing struct {
+	Name          string `json:"name"`
+	Current       bool   `json:"current"`
+	RouterBaseURL string `json:"router_base_url"`
+}
+
+func newProfilesListCommand(env *environment) *cobra.Command {
+	return &cobra.Command{
+		Use:   "list",
+		Short: "List the saved profiles",
+		Args:  cobra.NoArgs,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			out := cmd.OutOrStdout()
+
+			listings := make([]profileListing, 0, len(env.store.Profiles))
+			for _, name := range env.store.Names() {
+				listings = append(listings, profileListing{
+					Name:          name,
+					Current:       name == env.store.Current,
+					RouterBaseURL: env.store.Profiles[name].RouterBaseURL,
+				})
+			}
+
+			if jsonOutput(cmd) {
+				return printJSON(out, listings)
+			}
+			if len(listings) == 0 {
+				_, err := fmt.Fprintln(out, "No profiles yet. Run `requesty login` to sign in.")
+				return err
+			}
+
+			rows := make([][]string, 0, len(listings))
+			for _, listing := range listings {
+				marker := ""
+				if listing.Current {
+					marker = "*"
+				}
+				rows = append(rows, []string{marker, listing.Name, listing.RouterBaseURL})
+			}
+
+			return writeTable(out, []string{"", "NAME", "ROUTER"}, rows)
+		},
+	}
+}
+
+func newProfilesUseCommand(env *environment) *cobra.Command {
+	return &cobra.Command{
+		Use:   "use <name>",
+		Short: "Make a profile the current one",
+		Long:  "Make a profile the one used when none is named with --" + profileFlag + " or " + profileEnv + ".",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			name := args[0]
+			if err := env.store.Use(name); err != nil {
+				return err
+			}
+			if err := config.Save(env.store); err != nil {
+				return err
+			}
+
+			_, err := fmt.Fprintf(cmd.OutOrStdout(), "Profile %q is now current.\n", name)
+			return err
+		},
+	}
+}
+
+func newProfilesRemoveCommand(env *environment) *cobra.Command {
+	return &cobra.Command{
+		Use:     "remove <name>",
+		Aliases: []string{"rm", "delete"},
+		Short:   "Forget a profile on this machine",
+		Long: "Forget a profile on this machine. The API key itself is not revoked; do that on\n" +
+			onboarding.APIKeysURL + " if it should stop working.",
+		Args: cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			name := args[0]
+			if err := env.store.Remove(name); err != nil {
+				return err
+			}
+			if err := config.Save(env.store); err != nil {
+				return err
+			}
+
+			_, err := fmt.Fprintf(cmd.OutOrStdout(), "Removed profile %q. Its API key still exists; revoke it at %s if needed.\n",
+				name, onboarding.APIKeysURL)
+			return err
+		},
+	}
+}
+
+// requestedProfile is the profile the user named for this run: the flag,
+// else the environment variable, else empty for whatever the config says.
+func requestedProfile(cmd *cobra.Command) string {
+	if flag := cmd.Flags().Lookup(profileFlag); flag != nil && flag.Changed {
+		return flag.Value.String()
+	}
+
+	return os.Getenv(profileEnv)
+}
diff --git a/cmd/profiles_test.go b/cmd/profiles_test.go
new file mode 100644
index 0000000..12cc69b
--- /dev/null
+++ b/cmd/profiles_test.go
@@ -0,0 +1,91 @@
+package cmd
+
+import (
+	"bytes"
+	"encoding/json"
+	"testing"
+
+	"github.com/requestyai/cli/internal/config"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// runProfiles runs `requesty profiles <args>` against a copy of store.
+func runProfiles(t *testing.T, store config.Store, args ...string) (string, error) {
+	t.Helper()
+
+	var output bytes.Buffer
+	command := newRootCommand(&environment{store: clone(store)})
+	command.SetOut(&output)
+	command.SetArgs(append([]string{"profiles"}, args...))
+	err := command.Execute()
+
+	return output.String(), err
+}
+
+func TestProfilesListTable(t *testing.T) {
+	out, err := runProfiles(t, twoProfiles, "list")
+
+	require.NoError(t, err)
+	assert.Contains(t, out, "NAME")
+	assert.Contains(t, out, "*  engineering")
+	assert.Contains(t, out, "personal")
+	assert.Contains(t, out, config.DefaultRouterBaseURL)
+	assert.NotContains(t, out, "rqsty-", "keys stay out of listings")
+}
+
+func TestProfilesListJSON(t *testing.T) {
+	out, err := runProfiles(t, twoProfiles, "list", "--json")
+
+	require.NoError(t, err)
+	var listings []profileListing
+	require.NoError(t, json.Unmarshal([]byte(out), &listings))
+	assert.Equal(t, []profileListing{
+		{Name: "engineering", Current: true, RouterBaseURL: config.DefaultRouterBaseURL},
+		{Name: "personal", RouterBaseURL: config.DefaultRouterBaseURL},
+	}, listings)
+}
+
+func TestProfilesListEmpty(t *testing.T) {
+	out, err := runProfiles(t, config.Store{}, "list")
+
+	require.NoError(t, err)
+	assert.Contains(t, out, "No profiles yet")
+}
+
+func TestProfilesUseSetsCurrent(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+
+	out, err := runProfiles(t, twoProfiles, "use", "personal")
+
+	require.NoError(t, err)
+	assert.Contains(t, out, `"personal" is now current`)
+	saved, err := config.Load()
+	require.NoError(t, err)
+	assert.Equal(t, "personal", saved.Current)
+}
+
+func TestProfilesUseUnknown(t *testing.T) {
+	_, err := runProfiles(t, twoProfiles, "use", "sales")
+
+	require.ErrorContains(t, err, `profile "sales" not found; saved profiles: engineering, personal`)
+}
+
+func TestProfilesRemoveClearsCurrent(t *testing.T) {
+	t.Setenv("HOME", t.TempDir())
+
+	out, err := runProfiles(t, twoProfiles, "remove", "engineering")
+
+	require.NoError(t, err)
+	assert.Contains(t, out, `Removed profile "engineering"`)
+	saved, err := config.Load()
+	require.NoError(t, err)
+	assert.Equal(t, []string{"personal"}, saved.Names())
+	assert.Equal(t, "personal", saved.Current)
+}
+
+func TestProfilesRemoveUnknown(t *testing.T) {
+	_, err := runProfiles(t, twoProfiles, "remove", "sales")
+
+	require.ErrorContains(t, err, `profile "sales" not found`)
+}
diff --git a/cmd/requesty.go b/cmd/requesty.go
index cf565f4..b98415c 100644
--- a/cmd/requesty.go
+++ b/cmd/requesty.go
@@ -4,9 +4,6 @@ import (
 	"fmt"
 
 	tea "charm.land/bubbletea/v2"
-	"github.com/requestyai/cli/internal/client"
-	"github.com/requestyai/cli/internal/config"
-	"github.com/requestyai/cli/internal/onboarding"
 	"github.com/requestyai/cli/internal/tui"
 	"github.com/spf13/cobra"
 )
@@ -21,50 +18,20 @@ func Run() error {
 	return newRootCommand(env).Execute()
 }
 
-// environment is the loaded config and the gateway client the commands share.
-type environment struct {
-	config      config.Config
-	apiv2Client *client.Client
-}
-
-func newEnvironment() (environment, error) {
-	cfg, err := config.Load()
-	if err != nil {
-		return environment{}, fmt.Errorf("failed to load config: %w", err)
-	}
-
-	return environment{
-		config:      cfg,
-		apiv2Client: client.New(cfg),
-	}, nil
-}
-
-// ensureAPIKey is the config to launch with, onboarding first when no key is
-// saved yet. harness is the display name of the harness about to start, or
-// empty for the dashboard.
-func (env environment) ensureAPIKey(cmd *cobra.Command, harness string) (config.Config, error) {
-	if env.config.APIKey != "" {
-		return env.config, nil
-	}
-
-	return onboarding.Run(cmd.Context(), onboarding.Options{
-		Config:  env.config,
-		Harness: harness,
-	})
-}
-
-func newRootCommand(env environment) *cobra.Command {
+func newRootCommand(env *environment) *cobra.Command {
 	root := &cobra.Command{
 		Use:   "requesty",
 		Short: "Point your AI coding harnesses at Requesty",
 		Long: "Requesty routes every AI coding harness on your machine through one gateway.\n\n" +
 			"Run with no arguments for the terminal app that configures harnesses and shows\n" +
-			"what you are spending. The subcommands manage your organization instead.",
+			"what you are spending. The subcommands manage your organization instead.\n\n" +
+			"Every command runs as one saved profile: an API key and its router. Name one\n" +
+			"with --" + profileFlag + " or " + profileEnv + "; otherwise the current profile is used.",
 		Args:          cobra.NoArgs,
 		SilenceUsage:  true,
 		SilenceErrors: true,
 		RunE: func(cmd *cobra.Command, _ []string) error {
-			cfg, err := env.ensureAPIKey(cmd, "")
+			cfg, err := env.ensureProfile(cmd, "", "")
 			if err != nil {
 				return err
 			}
@@ -76,10 +43,12 @@ func newRootCommand(env environment) *cobra.Command {
 			return nil
 		},
 	}
+	root.PersistentFlags().String(profileFlag, "", "saved profile to run as (also "+profileEnv+")")
 
 	root.AddCommand(
 		newLoginCommand(env),
 		newAuthCommand(env),
+		newProfilesCommand(env),
 		newAPIKeysCommand(env),
 		newGroupsCommand(env),
 		newAccessListsCommand(env),
diff --git a/cmd/requesty_test.go b/cmd/requesty_test.go
index 6803a00..26236f9 100644
--- a/cmd/requesty_test.go
+++ b/cmd/requesty_test.go
@@ -2,6 +2,9 @@ package cmd
 
 import (
 	"bytes"
+	"maps"
+	"net/http"
+	"net/http/httptest"
 	"testing"
 
 	"github.com/requestyai/cli/internal/config"
@@ -9,11 +12,32 @@ import (
 	"github.com/stretchr/testify/require"
 )
 
-func TestAuthTokenPrintsAPIKey(t *testing.T) {
+var (
+	oneProfile = config.Store{
+		Current: "work",
+		Profiles: map[string]config.Config{
+			"work": {APIKey: "my-api-key", RouterBaseURL: config.DefaultRouterBaseURL},
+		},
+	}
+	twoProfiles = config.Store{
+		Current: "engineering",
+		Profiles: map[string]config.Config{
+			"engineering": {APIKey: "rqsty-eng", RouterBaseURL: config.DefaultRouterBaseURL},
+			"personal":    {APIKey: "rqsty-me", RouterBaseURL: config.DefaultRouterBaseURL},
+		},
+	}
+)
+
+// clone copies a fixture so a command that writes profiles does not change
+// it for other tests.
+func clone(store config.Store) config.Store {
+	store.Profiles = maps.Clone(store.Profiles)
+	return store
+}
+
+func TestAuthTokenPrintsCurrentProfileKey(t *testing.T) {
 	var output bytes.Buffer
-	command := newRootCommand(environment{
-		config: config.Config{APIKey: "my-api-key"},
-	})
+	command := newRootCommand(&environment{store: oneProfile})
 	command.SetOut(&output)
 	command.SetArgs([]string{"auth", "token"})
 
@@ -21,17 +45,60 @@ func TestAuthTokenPrintsAPIKey(t *testing.T) {
 	assert.Equal(t, "my-api-key\n", output.String())
 }
 
-func TestAuthTokenRejectsMissingAPIKey(t *testing.T) {
-	command := newRootCommand(environment{})
+func TestAuthTokenPicksExplicitProfile(t *testing.T) {
+	var output bytes.Buffer
+	command := newRootCommand(&environment{store: twoProfiles})
+	command.SetOut(&output)
+	command.SetArgs([]string{"auth", "token", "--profile", "personal"})
+
+	require.NoError(t, command.Execute())
+	assert.Equal(t, "rqsty-me\n", output.String())
+}
+
+func TestAuthTokenUsesEnvironmentProfile(t *testing.T) {
+	t.Setenv(profileEnv, "personal")
+	var output bytes.Buffer
+	command := newRootCommand(&environment{store: twoProfiles})
+	command.SetOut(&output)
+	command.SetArgs([]string{"auth", "token"})
+
+	require.NoError(t, command.Execute())
+	assert.Equal(t, "rqsty-me\n", output.String())
+}
+
+func TestAuthTokenRejectsMissingProfile(t *testing.T) {
+	command := newRootCommand(&environment{})
 	command.SetArgs([]string{"auth", "token"})
 
 	err := command.Execute()
 
-	require.EqualError(t, err, "no Requesty API key configured")
+	require.ErrorIs(t, err, config.ErrNoProfiles)
+}
+
+func TestManagementCommandUsesSelectedProfile(t *testing.T) {
+	var authorization string
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		authorization = r.Header.Get("Authorization")
+		_, _ = w.Write([]byte(`{"keys":[]}`))
+	}))
+	t.Cleanup(server.Close)
+
+	store := config.Store{
+		Current: "work",
+		Profiles: map[string]config.Config{
+			"work":     {APIKey: "rqsty-work", RouterBaseURL: server.URL},
+			"personal": {APIKey: "rqsty-me", RouterBaseURL: server.URL},
+		},
+	}
+	command := newRootCommand(&environment{store: store})
+	command.SetArgs([]string{"api-keys", "list", "--profile", "personal"})
+
+	require.NoError(t, command.Execute())
+	assert.Equal(t, "Bearer rqsty-me", authorization)
 }
 
 func TestAuthCommandIsHidden(t *testing.T) {
-	command := newRootCommand(environment{})
+	command := newRootCommand(&environment{})
 
 	auth, _, err := command.Find([]string{"auth"})
 
diff --git a/internal/config/config.go b/internal/config/config.go
index e17f1ad..3d3fea3 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -7,6 +7,7 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
+	"sort"
 	"strings"
 )
 
@@ -18,8 +19,13 @@ const (
 	DefaultAPIBaseURL    = "https://api-v2.requesty.ai"
 )
 
-// Config is the settings file.
+// ErrNoProfiles means nobody has signed in on this machine yet.
+var ErrNoProfiles = errors.New("no Requesty profile configured; run `requesty login`")
+
+// Config is what a client or harness runs with: an API key and the router it
+// is sent to. The settings file holds one per profile.
 type Config struct {
+	Name          string `json:"-"`
 	APIKey        string `json:"api_key"`
 	RouterBaseURL string `json:"router_base_url"`
 }
@@ -31,6 +37,79 @@ func (c Config) APIBaseURL() string {
 	return apiBaseURL
 }
 
+// Store is the saved profiles and which one is current.
+type Store struct {
+	Current  string            `json:"current"`
+	Profiles map[string]Config `json:"profiles"`
+}
+
+// Names lists the saved profiles in a stable order.
+func (s Store) Names() []string {
+	names := make([]string, 0, len(s.Profiles))
+	for name := range s.Profiles {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+
+	return names
+}
+
+// Resolve returns the named profile, or the current profile when name is
+// empty.
+func (s Store) Resolve(name string) (Config, error) {
+	if len(s.Profiles) == 0 {
+		return Config{}, ErrNoProfiles
+	}
+	if name == "" {
+		name = s.Current
+	}
+
+	cfg, ok := s.Profiles[name]
+	if !ok {
+		return Config{}, fmt.Errorf("profile %q not found; saved profiles: %s", name, strings.Join(s.Names(), ", "))
+	}
+	cfg.Name = name
+
+	return cfg, nil
+}
+
+// Set stores cfg as the named profile, replacing any existing one.
+func (s *Store) Set(name string, cfg Config) {
+	if s.Profiles == nil {
+		s.Profiles = make(map[string]Config)
+	}
+	cfg.Name = ""
+	s.Profiles[name] = cfg
+	if s.Current == "" {
+		s.Current = name
+	}
+}
+
+// Use makes name the current profile.
+func (s *Store) Use(name string) error {
+	if _, ok := s.Profiles[name]; !ok {
+		return fmt.Errorf("profile %q not found; saved profiles: %s", name, strings.Join(s.Names(), ", "))
+	}
+	s.Current = name
+	return nil
+}
+
+// Remove deletes name and keeps Current valid. If the current profile is
+// removed, the first remaining profile in name order becomes current.
+func (s *Store) Remove(name string) error {
+	if _, ok := s.Profiles[name]; !ok {
+		return fmt.Errorf("profile %q not found; saved profiles: %s", name, strings.Join(s.Names(), ", "))
+	}
+	delete(s.Profiles, name)
+	if s.Current == name {
+		s.Current = ""
+		if names := s.Names(); len(names) > 0 {
+			s.Current = names[0]
+		}
+	}
+	return nil
+}
+
 // DisplayPath is where the settings file lives, for messages: the real
 // location when it can be worked out, else the conventional one.
 func DisplayPath() string {
@@ -42,37 +121,40 @@ func DisplayPath() string {
 	return path
 }
 
-// Load reads the settings and fills in the production router when the file
-// leaves it blank. A missing file is not an error: it means the user has not
-// onboarded yet, so the defaults come back with no API key.
-func Load() (Config, error) {
+// Load reads the settings and fills in the production router for profiles
+// that leave it blank. A missing file is not an error: it means the user has
+// not onboarded yet, so an empty Store comes back.
+func Load() (Store, error) {
 	path, err := configPath()
 	if err != nil {
-		return Config{}, err
+		return Store{}, err
 	}
 
-	var config Config
+	var store Store
 	data, err := os.ReadFile(path)
 	switch {
 	case errors.Is(err, fs.ErrNotExist):
-		// Not onboarded yet: defaults only.
+		// Not onboarded yet.
 	case err != nil:
-		return Config{}, fmt.Errorf("failed to read config: %w", err)
+		return Store{}, fmt.Errorf("failed to read config: %w", err)
 	default:
-		if err := json.Unmarshal(data, &config); err != nil {
-			return Config{}, fmt.Errorf("failed to parse config: %w", err)
+		if err := json.Unmarshal(data, &store); err != nil {
+			return Store{}, fmt.Errorf("failed to parse config: %w", err)
 		}
 	}
 
-	if config.RouterBaseURL == "" {
-		config.RouterBaseURL = DefaultRouterBaseURL
+	for name, cfg := range store.Profiles {
+		if cfg.RouterBaseURL == "" {
+			cfg.RouterBaseURL = DefaultRouterBaseURL
+			store.Profiles[name] = cfg
+		}
 	}
 
-	return config, nil
+	return store, nil
 }
 
 // Save writes the settings, creating ~/.requesty if it is missing.
-func Save(config Config) error {
+func Save(store Store) error {
 	path, err := configPath()
 	if err != nil {
 		return err
@@ -82,7 +164,7 @@ func Save(config Config) error {
 		return fmt.Errorf("failed to create config directory: %w", err)
 	}
 
-	data, err := json.MarshalIndent(config, "", "  ")
+	data, err := json.MarshalIndent(store, "", "  ")
 	if err != nil {
 		return fmt.Errorf("failed to encode config: %w", err)
 	}
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index 63fbcd1..6382ddc 100644
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -38,21 +38,21 @@ func TestLoad(t *testing.T) {
 	tests := []struct {
 		name string
 		file string // empty means no file on disk
-		want Config
+		want Store
 	}{
 		{
-			name: "missing file gives defaults with no key",
-			want: Config{RouterBaseURL: DefaultRouterBaseURL},
+			name: "missing file means no profiles",
+			want: Store{},
 		},
 		{
 			name: "blank router is filled in, key kept",
-			file: `{"api_key": "rqsty-old"}`,
-			want: Config{APIKey: "rqsty-old", RouterBaseURL: DefaultRouterBaseURL},
+			file: `{"current": "work", "profiles": {"work": {"api_key": "rqsty-old"}}}`,
+			want: Store{Current: "work", Profiles: map[string]Config{"work": {APIKey: "rqsty-old", RouterBaseURL: DefaultRouterBaseURL}}},
 		},
 		{
 			name: "explicit router is returned verbatim",
-			file: `{"api_key": "rqsty-old", "router_base_url": "http://localhost:40000"}`,
-			want: Config{APIKey: "rqsty-old", RouterBaseURL: "http://localhost:40000"},
+			file: `{"current": "local", "profiles": {"local": {"api_key": "rqsty-old", "router_base_url": "http://localhost:40000"}}}`,
+			want: Store{Current: "local", Profiles: map[string]Config{"local": {APIKey: "rqsty-old", RouterBaseURL: "http://localhost:40000"}}},
 		},
 	}
 
@@ -86,13 +86,97 @@ func TestLoadRejectsMalformedFile(t *testing.T) {
 	require.ErrorContains(t, err, "failed to parse config")
 }
 
+func TestLoadRejectsInvalidStore(t *testing.T) {
+	tests := []struct {
+		name string
+		file string
+		want string
+	}{
+		{
+			name: "profiles without current",
+			file: `{"profiles":{"work":{"api_key":"k"}}}`,
+			want: "current profile is required",
+		},
+		{
+			name: "unknown current",
+			file: `{"current":"gone","profiles":{"work":{"api_key":"k"}}}`,
+			want: `current profile "gone" is not saved`,
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			home := t.TempDir()
+			t.Setenv("HOME", home)
+			dir := filepath.Join(home, dirName)
+			require.NoError(t, os.MkdirAll(dir, 0o700))
+			require.NoError(t, os.WriteFile(filepath.Join(dir, fileName), []byte(tc.file), 0o600))
+
+			_, err := Load()
+
+			require.ErrorContains(t, err, tc.want)
+		})
+	}
+}
+
 func TestSaveRoundTrips(t *testing.T) {
 	t.Setenv("HOME", t.TempDir())
-	want := Config{APIKey: "rqsty-new", RouterBaseURL: "http://localhost:40000"}
+	var store Store
+	store.Set("work", Config{APIKey: "rqsty-work", RouterBaseURL: "https://router.eu.example"})
 
-	require.NoError(t, Save(want))
+	require.NoError(t, Save(store))
 	got, err := Load()
 
 	require.NoError(t, err)
-	assert.Equal(t, want, got)
+	assert.Equal(t, store, got)
+}
+
+func TestResolve(t *testing.T) {
+	work := Config{APIKey: "rqsty-work", RouterBaseURL: DefaultRouterBaseURL}
+	personal := Config{APIKey: "rqsty-me", RouterBaseURL: DefaultRouterBaseURL}
+	store := Store{Current: "work", Profiles: map[string]Config{"work": work, "personal": personal}}
+
+	tests := []struct {
+		name     string
+		store    Store
+		ask      string
+		wantName string
+		wantErr  string
+	}{
+		{name: "explicit name", store: store, ask: "personal", wantName: "personal"},
+		{name: "current when unnamed", store: store, wantName: "work"},
+		{name: "nothing saved", store: Store{}, wantErr: ErrNoProfiles.Error()},
+		{name: "unknown name", store: store, ask: "sales", wantErr: `profile "sales" not found; saved profiles: personal, work`},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			cfg, err := tc.store.Resolve(tc.ask)
+			if tc.wantErr != "" {
+				require.ErrorContains(t, err, tc.wantErr)
+				return
+			}
+			require.NoError(t, err)
+			assert.Equal(t, tc.wantName, cfg.Name)
+			assert.Equal(t, tc.store.Profiles[tc.wantName].APIKey, cfg.APIKey)
+			assert.Equal(t, tc.store.Profiles[tc.wantName].RouterBaseURL, cfg.RouterBaseURL)
+		})
+	}
+}
+
+func TestNamesAreSorted(t *testing.T) {
+	store := Store{Profiles: map[string]Config{"z": {}, "a": {}}}
+	assert.Equal(t, []string{"a", "z"}, store.Names())
+}
+
+func TestRemoveCurrentSelectsNextProfile(t *testing.T) {
+	store := Store{
+		Current:  "work",
+		Profiles: map[string]Config{"work": {}, "personal": {}, "admin": {}},
+	}
+
+	require.NoError(t, store.Remove("work"))
+
+	assert.Equal(t, "admin", store.Current)
+	assert.NotContains(t, store.Profiles, "work")
 }
diff --git a/internal/harnesses/codex.go b/internal/harnesses/codex.go
index 4999a9c..15c0451 100644
--- a/internal/harnesses/codex.go
+++ b/internal/harnesses/codex.go
@@ -140,7 +140,7 @@ func (c *CodexHarness) configureMerge(opts ConfigureOptions) error {
 				},
 				"auth": map[string]any{
 					"command": "requesty",
-					"args":    []string{"auth", "token"},
+					"args":    c.authArgs(),
 				},
 			},
 		},
@@ -169,7 +169,7 @@ func (c *CodexHarness) configureOverwrite(opts ConfigureOptions) error {
 				},
 				Auth: codexProviderAuth{
 					Command: "requesty",
-					Args:    []string{"auth", "token"},
+					Args:    c.authArgs(),
 				},
 			},
 		},
@@ -190,6 +190,10 @@ func (c *CodexHarness) configPath() string {
 	return filepath.Join(c.configDir, "config.toml")
 }
 
+func (c *CodexHarness) authArgs() []string {
+	return []string{"auth", "token", "--profile", c.config.Name}
+}
+
 // codexEfforts maps Launch effort levels onto Codex's model_reasoning_effort.
 var codexEfforts = map[string]string{
 	EffortMinimal: "minimal",
@@ -225,7 +229,7 @@ func (c *CodexHarness) Launch(opts LaunchOptions) error {
 		"-c", provider + ".base_url=" + tomlString(c.config.RouterBaseURL+"/v1"),
 		"-c", provider + ".http_headers.X-Title=" + tomlString("OpenAI Codex"),
 		"-c", provider + ".auth.command=" + tomlString(requestyExecutable()),
-		"-c", provider + ".auth.args=[" + tomlString("auth") + "," + tomlString("token") + "]",
+		"-c", provider + ".auth.args=[" + tomlString("auth") + "," + tomlString("token") + "," + tomlString("--profile") + "," + tomlString(c.config.Name) + "]",
 		"-c", "model_supports_reasoning_summaries=false",
 	}
 	if opts.Model != "" {
diff --git a/internal/harnesses/codex_test.go b/internal/harnesses/codex_test.go
index 1984fa1..a8ea69b 100644
--- a/internal/harnesses/codex_test.go
+++ b/internal/harnesses/codex_test.go
@@ -13,7 +13,8 @@ import (
 )
 
 func TestCodexIntegrationRoundTrip(t *testing.T) {
-	config := config.Config{
+	cfg := config.Config{
+		Name:          "work",
 		RouterBaseURL: "https://router.requesty.ai",
 		APIKey:        "my-api-key",
 	}
@@ -23,7 +24,7 @@ func TestCodexIntegrationRoundTrip(t *testing.T) {
 	configPath := filepath.Join(configDir, "config.toml")
 	require.NoError(t, os.WriteFile(configPath, []byte("model = \"gpt-5.5\"\n"), 0o600))
 
-	harness := NewCodexHarness(config, configDir)
+	harness := NewCodexHarness(cfg, configDir)
 
 	status, err := harness.Status()
 	require.NoError(t, err)
@@ -43,13 +44,14 @@ func TestCodexIntegrationRoundTrip(t *testing.T) {
 }
 
 func TestCodexHarnessConfigureCreatesMissingConfig(t *testing.T) {
-	config := config.Config{
+	cfg := config.Config{
+		Name:          "work",
 		RouterBaseURL: "https://router.requesty.ai",
 		APIKey:        "my-api-key",
 	}
 	configDir := t.TempDir()
 	configPath := filepath.Join(configDir, "config.toml")
-	harness := NewCodexHarness(config, configDir)
+	harness := NewCodexHarness(cfg, configDir)
 
 	require.NoError(t, harness.Configure(ConfigureOptions{
 		Model: "openai-responses/gpt-5.5",
@@ -64,7 +66,7 @@ func TestCodexHarnessConfigureCreatesMissingConfig(t *testing.T) {
 	assert.Equal(t, "https://router.requesty.ai/v1", parsedConfig.ModelProviders[codexModelProvider].BaseURL)
 	assert.Equal(t, codexProviderAuth{
 		Command: "requesty",
-		Args:    []string{"auth", "token"},
+		Args:    []string{"auth", "token", "--profile", "work"},
 	}, parsedConfig.ModelProviders[codexModelProvider].Auth)
 	_, err = os.Stat(filepath.Join(configDir, "auth.json"))
 	assert.ErrorIs(t, err, os.ErrNotExist)
@@ -72,6 +74,7 @@ func TestCodexHarnessConfigureCreatesMissingConfig(t *testing.T) {
 
 func TestCodexHarnessConfigureOverwriteUsesProviderAuth(t *testing.T) {
 	cfg := config.Config{
+		Name:          "work",
 		RouterBaseURL: "https://router.requesty.ai",
 		APIKey:        "my-api-key",
 	}
@@ -89,7 +92,7 @@ func TestCodexHarnessConfigureOverwriteUsesProviderAuth(t *testing.T) {
 	require.NoError(t, toml.Unmarshal(configBytes, &parsedConfig))
 	assert.Equal(t, codexProviderAuth{
 		Command: "requesty",
-		Args:    []string{"auth", "token"},
+		Args:    []string{"auth", "token", "--profile", "work"},
 	}, parsedConfig.ModelProviders[codexModelProvider].Auth)
 	_, err = os.Stat(filepath.Join(configDir, "auth.json"))
 	assert.ErrorIs(t, err, os.ErrNotExist)
@@ -122,7 +125,7 @@ func codexOverrides(t *testing.T, args []string) map[string]any {
 func TestCodexHarnessLaunchInjectsRequestyOverrides(t *testing.T) {
 	binaryPath := fakeBinary(t, "codex")
 	captured := captureExec(t)
-	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
+	cfg := config.Config{Name: "work", RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
 	harness := NewCodexHarness(cfg, t.TempDir())
 
 	err := harness.Launch(LaunchOptions{
@@ -142,7 +145,7 @@ func TestCodexHarnessLaunchInjectsRequestyOverrides(t *testing.T) {
 	assert.Equal(t, "Requesty", overrides["model_providers.requesty.name"])
 	assert.Equal(t, "https://router.requesty.ai/v1", overrides["model_providers.requesty.base_url"])
 	assert.Equal(t, "OpenAI Codex", overrides["model_providers.requesty.http_headers.X-Title"])
-	assert.Equal(t, []any{"auth", "token"}, overrides["model_providers.requesty.auth.args"])
+	assert.Equal(t, []any{"auth", "token", "--profile", "work"}, overrides["model_providers.requesty.auth.args"])
 	assert.Equal(t, false, overrides["model_supports_reasoning_summaries"])
 	assert.Equal(t, "xhigh", overrides["model_reasoning_effort"])
 
@@ -160,7 +163,7 @@ func TestCodexHarnessLaunchInjectsRequestyOverrides(t *testing.T) {
 func TestCodexHarnessLaunchWithoutOverridesOmitsModelAndEffort(t *testing.T) {
 	fakeBinary(t, "codex")
 	captured := captureExec(t)
-	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
+	cfg := config.Config{Name: "work", RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
 	harness := NewCodexHarness(cfg, t.TempDir())
 
 	require.NoError(t, harness.Launch(LaunchOptions{Env: []string{}}))
@@ -173,7 +176,7 @@ func TestCodexHarnessLaunchWithoutOverridesOmitsModelAndEffort(t *testing.T) {
 func TestCodexHarnessLaunchRejectsUnsupportedEffort(t *testing.T) {
 	fakeBinary(t, "codex")
 	captured := captureExec(t)
-	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
+	cfg := config.Config{Name: "work", RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
 	harness := NewCodexHarness(cfg, t.TempDir())
 
 	err := harness.Launch(LaunchOptions{Effort: EffortMax, Env: []string{}})
@@ -185,7 +188,7 @@ func TestCodexHarnessLaunchRejectsUnsupportedEffort(t *testing.T) {
 func TestCodexHarnessLaunchRequiresBinary(t *testing.T) {
 	t.Setenv("PATH", t.TempDir())
 	captured := captureExec(t)
-	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
+	cfg := config.Config{Name: "work", RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
 	harness := NewCodexHarness(cfg, t.TempDir())
 
 	err := harness.Launch(LaunchOptions{Env: []string{}})
diff --git a/internal/onboarding/flow.go b/internal/onboarding/flow.go
index 86e9af3..f07753f 100644
--- a/internal/onboarding/flow.go
+++ b/internal/onboarding/flow.go
@@ -111,9 +111,6 @@ func (s *session) createKey(ctx context.Context, group *client.Group) (result, e
 
 	cfg := s.opts.Config
 	cfg.APIKey = created.Secret
-	if err := config.Save(cfg); err != nil {
-		return result{}, fmt.Errorf("failed to save config: %w", err)
-	}
 
 	return result{Config: cfg, KeyName: name, Group: group}, nil
 }
diff --git a/internal/onboarding/flow_test.go b/internal/onboarding/flow_test.go
index 036cd0b..aefe18d 100644
--- a/internal/onboarding/flow_test.go
+++ b/internal/onboarding/flow_test.go
@@ -41,8 +41,8 @@ func (s *manageServer) handler() http.Handler {
 
 // signedIn is a session as signIn would leave it, minus the browser: an
 // OAuth token in the client and the caller's groups listed. The router points
-// at the fake, which the management API address follows. Config is written
-// under a throwaway HOME.
+// at the fake, which the management API address follows. HOME is a throwaway
+// so a test can check that nothing is written there.
 func signedIn(t *testing.T, groups ...client.Group) (*session, *manageServer) {
 	t.Helper()
 	t.Setenv("HOME", t.TempDir())
@@ -122,7 +122,7 @@ func TestCreateKeyPersonal(t *testing.T) {
 
 	saved, err := config.Load()
 	require.NoError(t, err)
-	assert.Equal(t, r.Config, saved)
+	assert.Empty(t, saved.Profiles, "the command layer owns persistence")
 }
 
 func TestCreateKeyInGroup(t *testing.T) {
@@ -144,9 +144,6 @@ func TestCreateKeyReportsGatewayFailure(t *testing.T) {
 	_, err := s.createKey(context.Background(), nil)
 
 	require.ErrorContains(t, err, "group_id is required")
-	saved, loadErr := config.Load()
-	require.NoError(t, loadErr)
-	assert.Empty(t, saved.APIKey, "nothing is written when the gateway refuses")
 }
 
 func TestFindGroup(t *testing.T) {
diff --git a/internal/onboarding/run.go b/internal/onboarding/run.go
index d09dbee..9ac2160 100644
--- a/internal/onboarding/run.go
+++ b/internal/onboarding/run.go
@@ -16,8 +16,8 @@ var (
 	ErrCancelled = errors.New("sign-in cancelled")
 )
 
-// Run signs a user in with their browser and takes them through to a saved
-// config in the full-screen UI.
+// Run signs a user in with their browser and takes them through to a new key
+// in the full-screen UI. The caller saves the config it returns.
 func Run(ctx context.Context, opts Options) (config.Config, error) {
 	final, err := tea.NewProgram(newModel(ctx, opts), tea.WithContext(ctx), tea.WithOutput(os.Stderr)).Run()
 	if err != nil {
@@ -31,8 +31,8 @@ func Run(ctx context.Context, opts Options) (config.Config, error) {
 	return *finished.done, nil
 }
 
-// RunHeadless signs a user in with their browser and saves the resulting
-// config using plain-text prompts and status output.
+// RunHeadless signs a user in with their browser using plain-text prompts and
+// status output. The caller saves the config it returns.
 func RunHeadless(ctx context.Context, opts Options) (config.Config, error) {
 	_, _ = fmt.Fprintf(os.Stderr,
 		"Signing in with your browser will create an API key named %q in your Requesty\naccount and save it to %s.\n\n",
@@ -44,13 +44,9 @@ func RunHeadless(ctx context.Context, opts Options) (config.Config, error) {
 	}
 
 	if r.Group != nil {
-		_, _ = fmt.Fprintf(os.Stderr,
-			"Created API key %q in group %q and saved it to %s.\nManage it at %s.\n",
-			r.KeyName, r.Group.Name, config.DisplayPath(), APIKeysURL)
+		_, _ = fmt.Fprintf(os.Stderr, "Created API key %q in group %q.\nManage it at %s.\n", r.KeyName, r.Group.Name, APIKeysURL)
 	} else {
-		_, _ = fmt.Fprintf(os.Stderr,
-			"Created API key %q in your personal API keys and saved it to %s.\nManage it at %s.\n",
-			r.KeyName, config.DisplayPath(), APIKeysURL)
+		_, _ = fmt.Fprintf(os.Stderr, "Created API key %q in your personal API keys.\nManage it at %s.\n", r.KeyName, APIKeysURL)
 	}
 
 	return r.Config, nil

From 2ece232cbb1f15b8aa44e2e60ee6e0a7a5ccc2f2 Mon Sep 17 00:00:00 2001
From: fayzan <fayzan@requesty.ai>
Date: Wed, 23 Sep 2026 14:46:45 +0100
Subject: [PATCH 5/9] Implement model picker used when --model is not provided

---
 README.md                           |  15 +-
 cmd/environment.go                  |  50 +++++
 cmd/harness.go                      |  97 +++++---
 cmd/harness_test.go                 |  68 ++++++
 internal/client/models.go           |  12 +-
 internal/client/models_test.go      |  40 ++++
 internal/config/config.go           |  15 +-
 internal/config/config_test.go      |  13 +-
 internal/harnesses/harnesses.go     |   7 +-
 internal/modelpicker/picker.go      | 334 ++++++++++++++++++++++++++++
 internal/modelpicker/picker_test.go | 206 +++++++++++++++++
 11 files changed, 818 insertions(+), 39 deletions(-)
 create mode 100644 internal/modelpicker/picker.go
 create mode 100644 internal/modelpicker/picker_test.go

diff --git a/README.md b/README.md
index 89d8e94..3e69c9e 100644
--- a/README.md
+++ b/README.md
@@ -96,12 +96,21 @@ unless you pass `--profile`.
 
 `requesty claude` and `requesty codex` start the harness with its traffic routed through Requesty
 for that run only; nothing on disk is changed. The current profile is used unless you select
-another. A model flag applies only to that run; without it, the harness uses its configured model.
+another.
+
+The first time you launch a harness from a profile, a picker asks which model it should use and
+remembers the answer in the profile. The Policies tab lists Requesty's managed policies, which name
+a model once (`claude-sonnet-4-6`) and route it across providers; `tab` switches to every model
+the key can route to. The cursor starts on the harness's recommended default, so enter is usually
+all it takes. `--model` overrides the remembered model for one run without changing it;
+`--choose-model` opens the picker again to change it. In a script or CI with no terminal to ask
+in, pass `--model`, or pick once interactively first.
 
 ```sh
-requesty claude                                    # current profile, harness's configured model
-requesty claude --profile eu                       # a named profile
+requesty claude                                    # current profile, remembered model (asks the first time)
+requesty claude --profile eu                       # a named profile, with its own remembered model
 requesty claude --model anthropic/claude-opus-4-1  # this model, just for this run
+requesty claude --choose-model                     # pick again and remember the new answer
 requesty codex --reasoning-effort high -- --full-auto
 ```
 
diff --git a/cmd/environment.go b/cmd/environment.go
index 530ee86..d8404e1 100644
--- a/cmd/environment.go
+++ b/cmd/environment.go
@@ -6,6 +6,7 @@ import (
 
 	"github.com/requestyai/cli/internal/client"
 	"github.com/requestyai/cli/internal/config"
+	"github.com/requestyai/cli/internal/modelpicker"
 	"github.com/requestyai/cli/internal/onboarding"
 	"github.com/spf13/cobra"
 )
@@ -90,6 +91,55 @@ func (env *environment) ensureProfile(cmd *cobra.Command, name, harness string)
 	return cfg, nil
 }
 
+// ensureModel returns the model the harness launches with, running the
+// picker when the profile has none for it yet and saving the answer.
+func (env *environment) ensureModel(cmd *cobra.Command, cfg config.Config, spec harnessSpec, parsed harnessArgs) (string, error) {
+	model, ask := modelToLaunch(cfg, spec, parsed)
+	if !ask {
+		return model, nil
+	}
+
+	picked, err := modelpicker.Run(cmd.Context(), modelpicker.Options{
+		Client:    client.New(cfg),
+		Harness:   spec.displayName,
+		Preselect: model,
+	})
+	if errors.Is(err, modelpicker.ErrCancelled) {
+		return "", err
+	}
+	if err != nil {
+		// Most often there is no terminal to ask in, such as a script or CI.
+		return "", fmt.Errorf("no model picked for %s in profile %q; pass %s <id> or run in a terminal once (%w)", spec.displayName, cfg.Name, harnessModelFlag, err)
+	}
+
+	cfg.SetHarnessModel(spec.binary, picked)
+	if err := env.save(cfg.Name, cfg); err != nil {
+		return "", err
+	}
+
+	return picked, nil
+}
+
+// modelToLaunch applies the rules for which model a harness launches with:
+// --model for this run only, else the model picked for this harness in the
+// profile, else ask. When asking, model is what the picker should suggest:
+// the saved model that --choose-model is replacing, or the harness default.
+func modelToLaunch(cfg config.Config, spec harnessSpec, parsed harnessArgs) (model string, ask bool) {
+	if parsed.launch.Model != "" {
+		return parsed.launch.Model, false
+	}
+
+	saved := cfg.HarnessModels[spec.binary]
+	if saved != "" && !parsed.chooseModel {
+		return saved, false
+	}
+	if saved != "" {
+		return saved, true
+	}
+
+	return spec.defaultModel, true
+}
+
 // save stores cfg as the named profile and writes the file. The first profile
 // saved becomes current.
 func (env *environment) save(name string, cfg config.Config) error {
diff --git a/cmd/harness.go b/cmd/harness.go
index 02d1a0b..dd40594 100644
--- a/cmd/harness.go
+++ b/cmd/harness.go
@@ -12,31 +12,54 @@ import (
 )
 
 const (
-	harnessProfileFlag = "--" + profileFlag
-	harnessModelFlag   = "--model"
-	harnessEffortFlag  = "--reasoning-effort"
+	harnessProfileFlag     = "--" + profileFlag
+	harnessModelFlag       = "--model"
+	harnessChooseModelFlag = "--choose-model"
+	harnessEffortFlag      = "--reasoning-effort"
 )
 
 // errHarnessHelp signals that the leading flags asked for help.
 var errHarnessHelp = errors.New("help requested")
 
+// harnessSpec is one `requesty <binary>` command.
+type harnessSpec struct {
+	// binary is the command name and the executable it launches.
+	binary string
+	// displayName is how the harness is referred to in messages.
+	displayName string
+	// defaultModel is the managed policy the picker suggests when nothing
+	// has been picked yet.
+	defaultModel string
+	newHarness   func(config.Config) (harnesses.Harness, error)
+}
+
 // newHarnessCommands returns the `requesty <harness>` commands, each of which
 // starts a harness with Requesty injected for that run.
 func newHarnessCommands(env *environment) []*cobra.Command {
 	return []*cobra.Command{
-		newHarnessCommand(env, "claude", "Claude Code", func(cfg config.Config) (harnesses.Harness, error) {
-			dir, err := harnesses.DefaultConfigDirClaudeCode()
-			if err != nil {
-				return nil, err
-			}
-			return harnesses.NewClaudeHarness(cfg, dir), nil
+		newHarnessCommand(env, harnessSpec{
+			binary:       "claude",
+			displayName:  "Claude Code",
+			defaultModel: "claude-sonnet-4-6",
+			newHarness: func(cfg config.Config) (harnesses.Harness, error) {
+				dir, err := harnesses.DefaultConfigDirClaudeCode()
+				if err != nil {
+					return nil, err
+				}
+				return harnesses.NewClaudeHarness(cfg, dir), nil
+			},
 		}),
-		newHarnessCommand(env, "codex", "Codex", func(cfg config.Config) (harnesses.Harness, error) {
-			dir, err := harnesses.DefaultConfigDirCodex()
-			if err != nil {
-				return nil, err
-			}
-			return harnesses.NewCodexHarness(cfg, dir), nil
+		newHarnessCommand(env, harnessSpec{
+			binary:       "codex",
+			displayName:  "Codex",
+			defaultModel: "gpt-5.5",
+			newHarness: func(cfg config.Config) (harnesses.Harness, error) {
+				dir, err := harnesses.DefaultConfigDirCodex()
+				if err != nil {
+					return nil, err
+				}
+				return harnesses.NewCodexHarness(cfg, dir), nil
+			},
 		}),
 	}
 }
@@ -45,17 +68,20 @@ func newHarnessCommands(env *environment) []*cobra.Command {
 // lazily, from the profile as it stands after any onboarding, so a machine
 // without a resolvable home directory still gets a help page and a clear
 // error, rather than a missing command.
-func newHarnessCommand(env *environment, binary, displayName string, newHarness func(config.Config) (harnesses.Harness, error)) *cobra.Command {
+func newHarnessCommand(env *environment, spec harnessSpec) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   fmt.Sprintf("%s [--profile <name>] [--model <id>] [--reasoning-effort <level>] [-- ] [%s args...]", binary, binary),
-		Short: fmt.Sprintf("Launch %s through Requesty", displayName),
-		Long: fmt.Sprintf("Launch %s with its traffic routed through Requesty for this run only.\n\n", displayName) +
+		Use:   fmt.Sprintf("%s [--profile <name>] [--model <id> | --choose-model] [--reasoning-effort <level>] [-- ] [%s args...]", spec.binary, spec.binary),
+		Short: fmt.Sprintf("Launch %s through Requesty", spec.displayName),
+		Long: fmt.Sprintf("Launch %s with its traffic routed through Requesty for this run only.\n\n", spec.displayName) +
 			"Flags:\n" +
 			fmt.Sprintf("  %-28s %s\n", harnessProfileFlag+" <name>", "Saved profile to run as (also "+profileEnv+")") +
-			fmt.Sprintf("  %-28s %s\n", harnessModelFlag+" <id>", "Model to use for this run (any Requesty model id)") +
+			fmt.Sprintf("  %-28s %s\n", harnessModelFlag+" <id>", "Model for this run only (a managed policy or any Requesty model id)") +
+			fmt.Sprintf("  %-28s %s\n", harnessChooseModelFlag, "Pick the model to launch with from now on") +
 			fmt.Sprintf("  %-28s %s\n", harnessEffortFlag+" <level>", "Reasoning effort: "+strings.Join(harnesses.Efforts, ", ")) +
 			fmt.Sprintf("  %-28s %s\n\n", "-h, --help", "Show this help") +
-			fmt.Sprintf("Anything else, or everything after `--`, is passed to `%s` untouched.\n\n", binary),
+			fmt.Sprintf("Anything else, or everything after `--`, is passed to `%s` untouched.\n\n", spec.binary) +
+			"Without --model, the model picked for this harness in the profile is used. The first\n" +
+			fmt.Sprintf("time, a picker asks (suggesting %s) and remembers the answer.\n\n", spec.defaultModel),
 		// We take over parsing so harness flags are never interpreted as ours.
 		DisableFlagParsing:    true,
 		DisableFlagsInUseLine: true,
@@ -69,14 +95,19 @@ func newHarnessCommand(env *environment, binary, displayName string, newHarness
 				return err
 			}
 
-			cfg, err := env.ensureProfile(cmd, parsed.profile, displayName)
+			cfg, err := env.ensureProfile(cmd, parsed.profile, spec.displayName)
 			if err != nil {
 				return err
 			}
 
-			harness, err := newHarness(cfg)
+			harness, err := spec.newHarness(cfg)
+			if err != nil {
+				return fmt.Errorf("failed to set up %s: %w", spec.displayName, err)
+			}
+
+			parsed.launch.Model, err = env.ensureModel(cmd, cfg, spec, parsed)
 			if err != nil {
-				return fmt.Errorf("failed to set up %s: %w", displayName, err)
+				return err
 			}
 
 			return harness.Launch(parsed.launch)
@@ -89,8 +120,9 @@ func newHarnessCommand(env *environment, binary, displayName string, newHarness
 // harnessArgs is a harness command line split into our profile choice and
 // what the harness is launched with.
 type harnessArgs struct {
-	profile string
-	launch  harnesses.LaunchOptions
+	profile     string
+	chooseModel bool
+	launch      harnesses.LaunchOptions
 }
 
 // parseHarnessArgs splits our leading flags from the harness's own arguments.
@@ -102,17 +134,22 @@ type harnessArgs struct {
 func parseHarnessArgs(args []string) (harnessArgs, error) {
 	var parsed harnessArgs
 
+flags:
 	for len(args) > 0 {
 		arg := args[0]
 
 		switch {
 		case arg == "--":
 			parsed.launch.Args = args[1:]
-			return parsed, nil
+			break flags
 
 		case arg == "-h" || arg == "--help":
 			return parsed, errHarnessHelp
 
+		case arg == harnessChooseModelFlag:
+			parsed.chooseModel = true
+			args = args[1:]
+
 		case arg == harnessProfileFlag || arg == harnessModelFlag || arg == harnessEffortFlag:
 			if len(args) < 2 {
 				return parsed, fmt.Errorf("%s requires a value", arg)
@@ -131,10 +168,14 @@ func parseHarnessArgs(args []string) (harnessArgs, error) {
 
 		default:
 			parsed.launch.Args = args
-			return parsed, nil
+			break flags
 		}
 	}
 
+	if parsed.chooseModel && parsed.launch.Model != "" {
+		return parsed, fmt.Errorf("%s and %s cannot be combined", harnessModelFlag, harnessChooseModelFlag)
+	}
+
 	return parsed, nil
 }
 
diff --git a/cmd/harness_test.go b/cmd/harness_test.go
index 7044995..26aaa8c 100644
--- a/cmd/harness_test.go
+++ b/cmd/harness_test.go
@@ -4,6 +4,7 @@ import (
 	"bytes"
 	"testing"
 
+	"github.com/requestyai/cli/internal/config"
 	"github.com/requestyai/cli/internal/harnesses"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -64,6 +65,11 @@ func TestParseHarnessArgs(t *testing.T) {
 			args: []string{"--"},
 			want: harnessArgs{launch: harnesses.LaunchOptions{Args: []string{}}},
 		},
+		{
+			name: "choose model takes no value",
+			args: []string{"--choose-model", "--profile", "eu", "-p", "hi"},
+			want: harnessArgs{profile: "eu", chooseModel: true, launch: harnesses.LaunchOptions{Args: []string{"-p", "hi"}}},
+		},
 	}
 
 	for _, tt := range tests {
@@ -112,6 +118,11 @@ func TestParseHarnessArgsErrors(t *testing.T) {
 			args: []string{"--model", "  "},
 			want: "--model requires a value",
 		},
+		{
+			name: "model and choose model together",
+			args: []string{"--model", "x", "--choose-model", "--", "-p", "hi"},
+			want: "--model and --choose-model cannot be combined",
+		},
 	}
 
 	for _, tt := range tests {
@@ -144,8 +155,65 @@ func TestHarnessCommandHelpShowsOurFlags(t *testing.T) {
 	require.NoError(t, command.Execute())
 
 	assert.Contains(t, output.String(), "--profile")
+	assert.Contains(t, output.String(), "--choose-model")
 	assert.Contains(t, output.String(), "--reasoning-effort")
 	assert.Contains(t, output.String(), "passed to `claude`")
+	assert.Contains(t, output.String(), "suggesting claude-sonnet-4-6")
+}
+
+func TestModelToLaunch(t *testing.T) {
+	spec := harnessSpec{binary: "claude", displayName: "Claude Code", defaultModel: "claude-sonnet-4-6"}
+	var fresh config.Config
+	var picked config.Config
+	picked.SetHarnessModel("claude", "claude-fable-5")
+
+	tests := []struct {
+		name      string
+		cfg       config.Config
+		parsed    harnessArgs
+		wantModel string
+		wantAsk   bool
+	}{
+		{
+			name:      "flag wins over the saved model",
+			cfg:       picked,
+			parsed:    harnessArgs{launch: harnesses.LaunchOptions{Model: "anthropic/claude-opus-4-1"}},
+			wantModel: "anthropic/claude-opus-4-1",
+		},
+		{
+			name:      "saved model is used without asking",
+			cfg:       picked,
+			wantModel: "claude-fable-5",
+		},
+		{
+			name:      "nothing saved asks, suggesting the harness default",
+			cfg:       fresh,
+			wantModel: "claude-sonnet-4-6",
+			wantAsk:   true,
+		},
+		{
+			name:      "choose model asks again, suggesting the saved model",
+			cfg:       picked,
+			parsed:    harnessArgs{chooseModel: true},
+			wantModel: "claude-fable-5",
+			wantAsk:   true,
+		},
+		{
+			name:      "another harness's choice does not count",
+			cfg:       func() config.Config { var c config.Config; c.SetHarnessModel("codex", "gpt-5.5"); return c }(),
+			wantModel: "claude-sonnet-4-6",
+			wantAsk:   true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			model, ask := modelToLaunch(tt.cfg, spec, tt.parsed)
+
+			assert.Equal(t, tt.wantModel, model)
+			assert.Equal(t, tt.wantAsk, ask)
+		})
+	}
 }
 
 func TestHarnessProfileFlag(t *testing.T) {
diff --git a/internal/client/models.go b/internal/client/models.go
index d5b3991..64fa24b 100644
--- a/internal/client/models.go
+++ b/internal/client/models.go
@@ -7,6 +7,8 @@ import (
 	"net/http"
 )
 
+// Model is one entry of a model list. Managed policies are listed in the
+// same shape, so they are Models too.
 type Model struct {
 	ID string `json:"id"`
 
@@ -23,7 +25,15 @@ type Model struct {
 }
 
 func (c *Client) Models(ctx context.Context) ([]Model, error) {
-	endpoint := fmt.Sprintf("%s/v1/models", c.config.RouterBaseURL)
+	return c.listModels(ctx, "/v1/models")
+}
+
+func (c *Client) ManagedPolicies(ctx context.Context) ([]Model, error) {
+	return c.listModels(ctx, "/v1/models/managed")
+}
+
+func (c *Client) listModels(ctx context.Context, path string) ([]Model, error) {
+	endpoint := c.config.RouterBaseURL + path
 	req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
 	if err != nil {
 		return nil, fmt.Errorf("failed to create request: %w", err)
diff --git a/internal/client/models_test.go b/internal/client/models_test.go
index f7a62ce..231bafc 100644
--- a/internal/client/models_test.go
+++ b/internal/client/models_test.go
@@ -2,6 +2,9 @@ package client
 
 import (
 	"context"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
 	"testing"
 
 	"github.com/requestyai/cli/internal/config"
@@ -16,3 +19,40 @@ func TestClient_Models(t *testing.T) {
 	require.NoError(t, err)
 	assert.GreaterOrEqual(t, len(models), 100)
 }
+
+func TestClient_ManagedPolicies(t *testing.T) {
+	var seen struct{ path, auth string }
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		seen.path = r.URL.Path
+		seen.auth = r.Header.Get("Authorization")
+		_, err := fmt.Fprint(w, `{"object":"list","data":[
+			{"id":"claude-sonnet-4-6","context_window":1000000,"max_output_tokens":128000,"input_price":0.000003,"output_price":0.000015},
+			{"id":"gpt-5.5","context_window":400000,"input_price":0.0000055,"output_price":0.000033}
+		]}`)
+		require.NoError(t, err)
+	}))
+	defer server.Close()
+
+	client := New(config.Config{RouterBaseURL: server.URL, APIKey: "test-key"})
+
+	policies, err := client.ManagedPolicies(context.Background())
+
+	require.NoError(t, err)
+	assert.Equal(t, "/v1/models/managed", seen.path)
+	assert.Equal(t, "Bearer test-key", seen.auth)
+	assert.Equal(t, []Model{
+		{ID: "claude-sonnet-4-6", ContextWindow: 1_000_000, MaxOutputTokens: 128_000, InputPrice: 0.000003, OutputPrice: 0.000015},
+		{ID: "gpt-5.5", ContextWindow: 400_000, InputPrice: 0.0000055, OutputPrice: 0.000033},
+	}, policies)
+}
+
+func TestClient_ManagedPoliciesRejectsErrorStatus(t *testing.T) {
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusUnauthorized)
+	}))
+	defer server.Close()
+
+	_, err := New(config.Config{RouterBaseURL: server.URL, APIKey: "bad"}).ManagedPolicies(context.Background())
+
+	require.EqualError(t, err, "status code not ok: 401")
+}
diff --git a/internal/config/config.go b/internal/config/config.go
index 3d3fea3..a37b0b9 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -25,9 +25,18 @@ var ErrNoProfiles = errors.New("no Requesty profile configured; run `requesty lo
 // Config is what a client or harness runs with: an API key and the router it
 // is sent to. The settings file holds one per profile.
 type Config struct {
-	Name          string `json:"-"`
-	APIKey        string `json:"api_key"`
-	RouterBaseURL string `json:"router_base_url"`
+	Name          string            `json:"-"`
+	APIKey        string            `json:"api_key"`
+	RouterBaseURL string            `json:"router_base_url"`
+	HarnessModels map[string]string `json:"harness_models,omitempty"`
+}
+
+// SetHarnessModel remembers model as the one to launch harness with.
+func (c *Config) SetHarnessModel(harness, model string) {
+	if c.HarnessModels == nil {
+		c.HarnessModels = make(map[string]string)
+	}
+	c.HarnessModels[harness] = model
 }
 
 func (c Config) APIBaseURL() string {
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index 6382ddc..64f4dec 100644
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -1,6 +1,7 @@
 package config
 
 import (
+	"encoding/json"
 	"os"
 	"path/filepath"
 	"testing"
@@ -122,13 +123,23 @@ func TestLoadRejectsInvalidStore(t *testing.T) {
 func TestSaveRoundTrips(t *testing.T) {
 	t.Setenv("HOME", t.TempDir())
 	var store Store
-	store.Set("work", Config{APIKey: "rqsty-work", RouterBaseURL: "https://router.eu.example"})
+	work := Config{APIKey: "rqsty-work", RouterBaseURL: "https://router.eu.example"}
+	work.SetHarnessModel("claude", "claude-sonnet-4-6")
+	store.Set("work", work)
 
 	require.NoError(t, Save(store))
 	got, err := Load()
 
 	require.NoError(t, err)
 	assert.Equal(t, store, got)
+	assert.Equal(t, "claude-sonnet-4-6", got.Profiles["work"].HarnessModels["claude"])
+}
+
+func TestHarnessModelsAreOmittedUntilSet(t *testing.T) {
+	data, err := json.Marshal(Config{APIKey: "k", RouterBaseURL: DefaultRouterBaseURL})
+
+	require.NoError(t, err)
+	assert.NotContains(t, string(data), "harness_models")
 }
 
 func TestResolve(t *testing.T) {
diff --git a/internal/harnesses/harnesses.go b/internal/harnesses/harnesses.go
index d533de0..5452f3b 100644
--- a/internal/harnesses/harnesses.go
+++ b/internal/harnesses/harnesses.go
@@ -20,9 +20,10 @@ type ConfigureOptions struct {
 }
 
 type LaunchOptions struct {
-	// Model overrides the harness's default model for this run. Empty leaves
-	// whatever the harness would pick on its own (including a model our
-	// Configure wrote into its settings file earlier).
+	// Model is what the harness is told to use: a managed policy or any
+	// Requesty model id. Empty leaves whatever the harness would pick on its
+	// own (including a model our Configure wrote into its settings file
+	// earlier), which a gateway with an access list may well reject.
 	Model string
 	// Effort is one of Efforts, or empty for the harness default.
 	Effort string
diff --git a/internal/modelpicker/picker.go b/internal/modelpicker/picker.go
new file mode 100644
index 0000000..fa8270a
--- /dev/null
+++ b/internal/modelpicker/picker.go
@@ -0,0 +1,334 @@
+// Package modelpicker is the full-screen dialog that asks which model a
+// harness should launch with. It lists the managed policies the profile can
+// route to on one tab and every model on another.
+package modelpicker
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"os"
+	"slices"
+	"strings"
+
+	"charm.land/bubbles/v2/textinput"
+	tea "charm.land/bubbletea/v2"
+	"charm.land/lipgloss/v2"
+	"github.com/requestyai/cli/internal/client"
+	"github.com/requestyai/cli/internal/tui/theme"
+	"github.com/requestyai/cli/internal/tui/ui/table"
+	"github.com/requestyai/cli/internal/tui/ui/text"
+	"github.com/requestyai/cli/internal/util"
+)
+
+// ErrCancelled reports that the dialog was closed without choosing.
+var ErrCancelled = errors.New("no model chosen")
+
+// Options says what to pick for and what to suggest.
+type Options struct {
+	// Client fetches the two lists the picker shows, as the profile the
+	// harness will run with.
+	Client *client.Client
+	// Harness is the display name shown in the title.
+	Harness string
+	// Preselect is the model the cursor starts on when it is listed: the
+	// harness's recommended default, or what was picked last time.
+	Preselect string
+}
+
+// Run shows the picker and returns the chosen model id. It draws on stderr so
+// the harness's own stdout is untouched.
+func Run(ctx context.Context, opts Options) (string, error) {
+	final, err := tea.NewProgram(newModel(ctx, opts), tea.WithContext(ctx), tea.WithOutput(os.Stderr)).Run()
+	if err != nil {
+		return "", fmt.Errorf("failed to run model picker: %w", err)
+	}
+
+	finished, ok := final.(model)
+	if !ok || finished.chosen == "" {
+		return "", ErrCancelled
+	}
+
+	return finished.chosen, nil
+}
+
+const (
+	minWidth     = 40
+	maxWidth     = 96
+	contextWidth = 9
+	priceWidth   = 9
+	minRows      = 3
+	maxRows      = 15
+	// chromeRows is how many lines the dialog spends around the table.
+	chromeRows = 12
+
+	framePadX     = 2
+	framePadY     = 1
+	defaultWidth  = 80 - 2*framePadX
+	defaultHeight = 24 - 2*framePadY
+)
+
+var frame = lipgloss.NewStyle().Padding(framePadY, framePadX)
+
+type tab uint8
+
+const (
+	tabPolicies tab = iota
+	tabModels
+	tabCount
+)
+
+func (t tab) title() string {
+	if t == tabPolicies {
+		return "Policies"
+	}
+
+	return "Models"
+}
+
+func (t tab) description() string {
+	if t == tabPolicies {
+		return "Managed policies: one name per model, routed across providers."
+	}
+
+	return "Every model and organization policy this profile can route to."
+}
+
+// list is one tab's contents. loaded distinguishes an empty list from one
+// still on its way.
+type list struct {
+	models []client.Model
+	loaded bool
+	err    error
+}
+
+type loadedMsg struct {
+	tab    tab
+	models []client.Model
+	err    error
+}
+
+type model struct {
+	ctx    context.Context
+	opts   Options
+	lists  [tabCount]list
+	tab    tab
+	cursor int
+	search textinput.Model
+	width  int
+	height int
+	chosen string
+}
+
+func newModel(ctx context.Context, opts Options) model {
+	search := textinput.New()
+	search.Prompt = "Search: "
+	search.Placeholder = "type to filter"
+	search.CharLimit = 200
+	// The blink command Focus returns is issued from Init, so it is safe to
+	// discard here; what matters is that the box is ready to type into.
+	search.Focus()
+
+	return model{
+		ctx:    ctx,
+		opts:   opts,
+		search: search,
+		width:  defaultWidth,
+		height: defaultHeight,
+	}
+}
+
+func (m model) Init() tea.Cmd {
+	return tea.Batch(m.load(tabPolicies), m.load(tabModels), textinput.Blink)
+}
+
+func (m model) load(t tab) tea.Cmd {
+	ctx, apiClient := m.ctx, m.opts.Client
+	return func() tea.Msg {
+		var models []client.Model
+		var err error
+		if t == tabPolicies {
+			models, err = apiClient.ManagedPolicies(ctx)
+		} else {
+			models, err = apiClient.Models(ctx)
+		}
+		slices.SortFunc(models, func(a, b client.Model) int {
+			return strings.Compare(a.ID, b.ID)
+		})
+		return loadedMsg{tab: t, models: models, err: err}
+	}
+}
+
+func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
+	switch typedMsg := msg.(type) {
+	case tea.WindowSizeMsg:
+		m.width = max(typedMsg.Width-2*framePadX, 0)
+		m.height = max(typedMsg.Height-2*framePadY, 0)
+
+	case loadedMsg:
+		m.lists[typedMsg.tab] = list{models: typedMsg.models, loaded: true, err: typedMsg.err}
+		// Someone with no managed policies, or whose list failed to load,
+		// should not land on an empty tab.
+		if typedMsg.tab == tabPolicies && m.tab == tabPolicies && len(typedMsg.models) == 0 {
+			m.tab = tabModels
+		}
+		if typedMsg.tab == m.tab {
+			m.cursor = m.preselectedCursor()
+		}
+
+	case tea.KeyPressMsg:
+		return m.updateKey(typedMsg)
+	}
+
+	return m, nil
+}
+
+func (m model) updateKey(msg tea.KeyPressMsg) (model, tea.Cmd) {
+	switch msg.String() {
+	case "ctrl+c", "esc":
+		return m, tea.Quit
+	case "tab", "shift+tab":
+		m.tab = (m.tab + 1) % tabCount
+		m.cursor = m.preselectedCursor()
+	case "up":
+		if m.cursor > 0 {
+			m.cursor--
+		}
+	case "down":
+		if m.cursor < len(m.filtered())-1 {
+			m.cursor++
+		}
+	case "enter":
+		if filtered := m.filtered(); len(filtered) > 0 {
+			m.chosen = filtered[m.cursor].ID
+			return m, tea.Quit
+		}
+	default:
+		previous := m.search.Value()
+		var cmd tea.Cmd
+		m.search, cmd = m.search.Update(msg)
+		if m.search.Value() != previous {
+			m.cursor = 0
+		}
+		return m, cmd
+	}
+
+	return m, nil
+}
+
+// filtered is the current tab's list narrowed by the search box.
+func (m model) filtered() []client.Model {
+	models := m.lists[m.tab].models
+	query := strings.ToLower(strings.TrimSpace(m.search.Value()))
+	if query == "" {
+		return models
+	}
+
+	matches := make([]client.Model, 0, len(models))
+	for _, model := range models {
+		if strings.Contains(strings.ToLower(model.ID), query) {
+			matches = append(matches, model)
+		}
+	}
+
+	return matches
+}
+
+// preselectedCursor is where the cursor goes on a fresh list: on Preselect
+// when it is there, else the top.
+func (m model) preselectedCursor() int {
+	if m.opts.Preselect == "" {
+		return 0
+	}
+	for i, model := range m.filtered() {
+		if model.ID == m.opts.Preselect {
+			return i
+		}
+	}
+
+	return 0
+}
+
+func (m model) View() tea.View {
+	inner := max(min(m.width-8, maxWidth), minWidth)
+	m.search.SetWidth(inner - lipgloss.Width(m.search.Prompt))
+
+	lines := []string{
+		text.RenderSplitHeaderSection("Choose a model", m.opts.Harness, inner),
+		text.LineSeparator,
+		m.tabs(),
+		lipgloss.NewStyle().Width(inner).Render(theme.Muted.Render(m.tab.description())),
+		text.LineSeparator,
+		m.search.View(),
+		text.LineSeparator,
+		m.body(inner),
+		text.LineSeparator,
+		text.RenderFooterHintList(inner,
+			[2]string{"tab", "switch list"},
+			[2]string{"↑/↓", "move"},
+			[2]string{"enter", "launch"},
+			[2]string{"esc", "cancel"},
+		),
+	}
+
+	panel := theme.Panel.Render(lipgloss.JoinVertical(lipgloss.Left, lines...))
+	view := tea.NewView(frame.Render(lipgloss.Place(m.width, m.height, lipgloss.Center, lipgloss.Center, panel)))
+	view.AltScreen = true
+
+	return view
+}
+
+func (m model) tabs() string {
+	pills := make([]string, 0, tabCount)
+	for t := tabPolicies; t < tabCount; t++ {
+		label := t.title()
+		if l := m.lists[t]; l.loaded && l.err == nil {
+			label = fmt.Sprintf("%s (%d)", label, len(l.models))
+		}
+		style := theme.PillOff
+		if t == m.tab {
+			style = theme.Pill
+		}
+		pills = append(pills, style.Render(label))
+	}
+
+	return lipgloss.JoinHorizontal(lipgloss.Top, pills...)
+}
+
+func (m model) body(inner int) string {
+	current := m.lists[m.tab]
+	filtered := m.filtered()
+	switch {
+	case current.err != nil:
+		return theme.Bad.Render(fmt.Sprintf("Could not load %s: %s", strings.ToLower(m.tab.title()), current.err))
+	case !current.loaded:
+		return theme.Muted.Render(fmt.Sprintf("Loading %s…", strings.ToLower(m.tab.title())))
+	case len(current.models) == 0:
+		return theme.Muted.Render(fmt.Sprintf("No %s available to this profile", strings.ToLower(m.tab.title())))
+	case len(filtered) == 0:
+		return theme.Muted.Render(fmt.Sprintf("No %s match your search", strings.ToLower(m.tab.title())))
+	}
+
+	rows := make([][]string, 0, len(filtered))
+	for _, model := range filtered {
+		rows = append(rows, []string{
+			model.ID,
+			util.FormatTokens(model.ContextWindow),
+			util.FormatPrice(model.InputPrice),
+			util.FormatPrice(model.OutputPrice),
+		})
+	}
+
+	return table.Table{
+		Cols: []table.Column{
+			{Title: "MODEL", Width: inner - 2 - contextWidth - 2*priceWidth, Align: table.Left},
+			{Title: "CONTEXT", Width: contextWidth, Align: table.Right},
+			{Title: "IN /1M", Width: priceWidth, Align: table.Right},
+			{Title: "OUT /1M", Width: priceWidth, Align: table.Right},
+		},
+		Rows:   rows,
+		Cursor: m.cursor,
+		Height: max(min(m.height-chromeRows, maxRows), minRows),
+		Style:  table.CellStyle(m.cursor),
+	}.Render()
+}
diff --git a/internal/modelpicker/picker_test.go b/internal/modelpicker/picker_test.go
new file mode 100644
index 0000000..4da3363
--- /dev/null
+++ b/internal/modelpicker/picker_test.go
@@ -0,0 +1,206 @@
+package modelpicker
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	tea "charm.land/bubbletea/v2"
+	"github.com/charmbracelet/x/ansi"
+	"github.com/requestyai/cli/internal/client"
+	"github.com/requestyai/cli/internal/config"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// lists is what a fake router serves for the two endpoints the picker reads.
+// A nil list answers with an error status rather than an empty list.
+type lists struct {
+	policies []client.Model
+	models   []client.Model
+}
+
+// newClient returns a client pointed at a router that serves l.
+func newClient(t *testing.T, l lists) *client.Client {
+	t.Helper()
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var models []client.Model
+		switch r.URL.Path {
+		case "/v1/models/managed":
+			models = l.policies
+		case "/v1/models":
+			models = l.models
+		}
+		if models == nil {
+			w.WriteHeader(http.StatusUnauthorized)
+			return
+		}
+		require.NoError(t, json.NewEncoder(w).Encode(map[string]any{"object": "list", "data": models}))
+	}))
+	t.Cleanup(server.Close)
+
+	return client.New(config.Config{RouterBaseURL: server.URL, APIKey: "test-key"})
+}
+
+var (
+	policies = []client.Model{
+		{ID: "gpt-5.5", ContextWindow: 400_000, InputPrice: 0.0000055, OutputPrice: 0.000033},
+		{ID: "claude-sonnet-4-6", ContextWindow: 1_000_000, InputPrice: 0.000003, OutputPrice: 0.000015},
+		{ID: "claude-fable-5", ContextWindow: 1_000_000, InputPrice: 0.00001, OutputPrice: 0.00005},
+	}
+	models = []client.Model{
+		{ID: "anthropic/claude-sonnet-4-6", ContextWindow: 1_000_000},
+		{ID: "openai/gpt-5.5", ContextWindow: 400_000},
+	}
+)
+
+func key(name string) tea.KeyPressMsg {
+	switch name {
+	case "enter":
+		return tea.KeyPressMsg{Code: tea.KeyEnter}
+	case "esc":
+		return tea.KeyPressMsg{Code: tea.KeyEscape}
+	case "tab":
+		return tea.KeyPressMsg{Code: tea.KeyTab}
+	case "up":
+		return tea.KeyPressMsg{Code: tea.KeyUp}
+	case "down":
+		return tea.KeyPressMsg{Code: tea.KeyDown}
+	default:
+		return tea.KeyPressMsg{Code: rune(name[0]), Text: name}
+	}
+}
+
+func update(m model, msg tea.Msg) (model, tea.Cmd) {
+	next, cmd := m.Update(msg)
+	return next.(model), cmd
+}
+
+func view(m model) string {
+	return ansi.Strip(m.View().Content)
+}
+
+// loaded runs the picker's own load commands so both tabs are filled in.
+func loaded(t *testing.T, l lists, preselect string) model {
+	t.Helper()
+
+	m := newModel(context.Background(), Options{Client: newClient(t, l), Harness: "Claude Code", Preselect: preselect})
+	for _, tab := range []tab{tabPolicies, tabModels} {
+		msg := m.load(tab)()
+		require.IsType(t, loadedMsg{}, msg)
+		m, _ = update(m, msg)
+	}
+
+	return m
+}
+
+func TestShowsPoliciesFirstSortedWithPreselectUnderCursor(t *testing.T) {
+	m := loaded(t, lists{policies: policies, models: models}, "claude-sonnet-4-6")
+
+	assert.Equal(t, tabPolicies, m.tab)
+	assert.Equal(t, 1, m.cursor, "sorted: claude-fable-5, claude-sonnet-4-6, gpt-5.5")
+	out := view(m)
+	assert.Contains(t, out, "Choose a model")
+	assert.Contains(t, out, "Claude Code")
+	assert.Contains(t, out, "Policies (3)")
+	assert.Contains(t, out, "Models (2)")
+	assert.Contains(t, out, "❯ claude-sonnet-4-6")
+	assert.Contains(t, out, "1000K")
+	assert.Contains(t, out, "$3.00")
+	assert.Contains(t, out, "$15.00")
+}
+
+func TestEnterChoosesTheModelUnderTheCursor(t *testing.T) {
+	m := loaded(t, lists{policies: policies, models: models}, "")
+
+	m, _ = update(m, key("down"))
+	m, cmd := update(m, key("enter"))
+
+	assert.Equal(t, "claude-sonnet-4-6", m.chosen)
+	assert.NotNil(t, cmd, "enter quits the program")
+}
+
+func TestTabSwitchesToModelsAndBack(t *testing.T) {
+	m := loaded(t, lists{policies: policies, models: models}, "openai/gpt-5.5")
+
+	m, _ = update(m, key("tab"))
+
+	assert.Equal(t, tabModels, m.tab)
+	assert.Equal(t, 1, m.cursor, "preselect applies on whichever tab lists it")
+	assert.Contains(t, view(m), "❯ openai/gpt-5.5")
+
+	m, _ = update(m, key("tab"))
+
+	assert.Equal(t, tabPolicies, m.tab)
+	assert.Equal(t, 0, m.cursor)
+}
+
+func TestSearchFiltersTheCurrentTabAndResetsCursor(t *testing.T) {
+	m := loaded(t, lists{policies: policies, models: models}, "gpt-5.5")
+	require.Equal(t, 2, m.cursor)
+
+	m, _ = update(m, key("s"))
+	m, _ = update(m, key("o"))
+
+	assert.Equal(t, 0, m.cursor)
+	out := view(m)
+	assert.Contains(t, out, "❯ claude-sonnet-4-6")
+	assert.NotContains(t, out, "gpt-5.5")
+
+	m, _ = update(m, key("x"))
+
+	assert.Contains(t, view(m), "No policies match your search")
+}
+
+func TestNoPoliciesLandsOnModelsTab(t *testing.T) {
+	m := loaded(t, lists{policies: []client.Model{}, models: models}, "")
+
+	assert.Equal(t, tabModels, m.tab)
+	assert.Contains(t, view(m), "❯ anthropic/claude-sonnet-4-6")
+}
+
+func TestLoadErrorMovesToModelsAndIsShownOnItsTab(t *testing.T) {
+	m := loaded(t, lists{models: models}, "")
+
+	assert.Equal(t, tabModels, m.tab)
+
+	m, _ = update(m, key("tab"))
+
+	assert.Equal(t, tabPolicies, m.tab)
+	assert.Contains(t, view(m), "Could not load policies: status code not ok: 401")
+}
+
+func TestLoadingStateBeforeListsArrive(t *testing.T) {
+	m := newModel(context.Background(), Options{Client: newClient(t, lists{}), Harness: "Codex"})
+
+	assert.Contains(t, view(m), "Loading policies…")
+
+	_, cmd := update(m, key("enter"))
+	assert.Nil(t, cmd, "enter on an empty list does nothing")
+}
+
+func TestEscapeLeavesNothingChosen(t *testing.T) {
+	m := loaded(t, lists{policies: policies, models: models}, "")
+
+	m, cmd := update(m, key("esc"))
+
+	assert.Empty(t, m.chosen)
+	assert.NotNil(t, cmd)
+}
+
+func TestCursorStaysWithinTheList(t *testing.T) {
+	m := loaded(t, lists{policies: policies, models: models}, "")
+
+	for range 10 {
+		m, _ = update(m, key("down"))
+	}
+	assert.Equal(t, 2, m.cursor)
+
+	for range 10 {
+		m, _ = update(m, key("up"))
+	}
+	assert.Equal(t, 0, m.cursor)
+}

From eb5aa8714f43bd58169faeb150587a7788709cf2 Mon Sep 17 00:00:00 2001
From: fayzan <fayzan@requesty.ai>
Date: Wed, 23 Sep 2026 17:36:09 +0100
Subject: [PATCH 6/9] Implement support for specifying/choosing a fast model
 alongside the main model

---
 README.md                           |  24 ++-
 cmd/environment.go                  | 128 ++++++++++----
 cmd/harness.go                      | 153 ++++++++++++----
 cmd/harness_test.go                 | 265 ++++++++++++++++++++++------
 internal/config/config.go           |  25 ++-
 internal/config/config_test.go      |  15 ++
 internal/harnesses/claude.go        |   7 +
 internal/harnesses/claude_test.go   |  10 +-
 internal/harnesses/harnesses.go     |   5 +
 internal/modelpicker/picker.go      |  65 +++++--
 internal/modelpicker/picker_test.go |  62 ++++++-
 11 files changed, 596 insertions(+), 163 deletions(-)

diff --git a/README.md b/README.md
index 3e69c9e..6dc3ce7 100644
--- a/README.md
+++ b/README.md
@@ -98,19 +98,27 @@ unless you pass `--profile`.
 for that run only; nothing on disk is changed. The current profile is used unless you select
 another.
 
-The first time you launch a harness from a profile, a picker asks which model it should use and
-remembers the answer in the profile. The Policies tab lists Requesty's managed policies, which name
-a model once (`claude-sonnet-4-6`) and route it across providers; `tab` switches to every model
-the key can route to. The cursor starts on the harness's recommended default, so enter is usually
-all it takes. `--model` overrides the remembered model for one run without changing it;
-`--choose-model` opens the picker again to change it. In a script or CI with no terminal to ask
-in, pass `--model`, or pick once interactively first.
+The first time you launch a harness from a profile, the CLI settles which model it should use and
+remembers the answer in the profile. When the key can route to the harness's recommended default
+(`claude-sonnet-4-6` for Claude Code), that is used and printed, without asking. Otherwise a
+picker asks: the Policies tab lists Requesty's managed policies, which name a model once and
+route it across providers, and `tab` switches to every model the key can route to. `--model`
+overrides the remembered model for one run without changing it; `--choose-model` opens the picker
+to change it. In a script or CI with no terminal to ask in, the default is still used when it can
+be; otherwise pass `--model`, or pick once interactively first.
+
+Claude Code hands background work (session titles, summaries, subagents marked `haiku`) to a
+smaller model, which it would otherwise ask for by an Anthropic model id the gateway does not
+know. The CLI settles this the same way: `claude-haiku-4-5` when the key can route to it, else the
+main model itself, so an access list without Haiku still works. `--choose-fast-model` opens the
+picker to change it and `--fast-model` overrides it for one run.
 
 ```sh
-requesty claude                                    # current profile, remembered model (asks the first time)
+requesty claude                                    # current profile, remembered model (settled the first time)
 requesty claude --profile eu                       # a named profile, with its own remembered model
 requesty claude --model anthropic/claude-opus-4-1  # this model, just for this run
 requesty claude --choose-model                     # pick again and remember the new answer
+requesty claude --choose-fast-model                # pick what background work runs on
 requesty codex --reasoning-effort high -- --full-auto
 ```
 
diff --git a/cmd/environment.go b/cmd/environment.go
index d8404e1..a796742 100644
--- a/cmd/environment.go
+++ b/cmd/environment.go
@@ -3,6 +3,7 @@ package cmd
 import (
 	"errors"
 	"fmt"
+	"slices"
 
 	"github.com/requestyai/cli/internal/client"
 	"github.com/requestyai/cli/internal/config"
@@ -91,53 +92,112 @@ func (env *environment) ensureProfile(cmd *cobra.Command, name, harness string)
 	return cfg, nil
 }
 
-// ensureModel returns the model the harness launches with, running the
-// picker when the profile has none for it yet and saving the answer.
-func (env *environment) ensureModel(cmd *cobra.Command, cfg config.Config, spec harnessSpec, parsed harnessArgs) (string, error) {
-	model, ask := modelToLaunch(cfg, spec, parsed)
-	if !ask {
-		return model, nil
-	}
-
-	picked, err := modelpicker.Run(cmd.Context(), modelpicker.Options{
-		Client:    client.New(cfg),
-		Harness:   spec.displayName,
-		Preselect: model,
+// ensureModels returns the model the harness launches with and, for
+// harnesses that have one, the model its background work goes to. Whatever
+// the picker decides is saved in the profile.
+func (env *environment) ensureModels(cmd *cobra.Command, cfg config.Config, spec harnessSpec, parsed harnessArgs) (model, fast string, err error) {
+	model, pickedModel, err := env.ensureModel(cmd, cfg, modelRequest{
+		what:       spec.displayName,
+		flag:       harnessModelFlag,
+		chooseFlag: harnessChooseModelFlag,
+		flagged:    parsed.launch.Model,
+		choose:     parsed.chooseModel,
+		saved:      cfg.HarnessModels[spec.binary],
+		defaults:   spec.defaultModels,
 	})
-	if errors.Is(err, modelpicker.ErrCancelled) {
-		return "", err
-	}
 	if err != nil {
-		// Most often there is no terminal to ask in, such as a script or CI.
-		return "", fmt.Errorf("no model picked for %s in profile %q; pass %s <id> or run in a terminal once (%w)", spec.displayName, cfg.Name, harnessModelFlag, err)
+		return "", "", err
+	}
+	if pickedModel {
+		// This also forgets the fast model, so it is picked again below to
+		// go with the new main model.
+		cfg.SetHarnessModel(spec.binary, model)
+	}
+
+	pickedFast := false
+	if spec.hasFastModel() {
+		// The main model is the last resort: it is known to be permitted,
+		// so an access list without any smaller model still works.
+		fast, pickedFast, err = env.ensureModel(cmd, cfg, modelRequest{
+			what:       spec.displayName + " background work",
+			flag:       harnessFastModelFlag,
+			chooseFlag: harnessChooseFastModelFlag,
+			flagged:    parsed.launch.FastModel,
+			choose:     parsed.chooseFastModel,
+			saved:      cfg.HarnessFastModels[spec.binary],
+			defaults:   slices.Concat(spec.defaultFastModels, []string{model}),
+		})
+		if err != nil {
+			return "", "", err
+		}
+		if pickedFast {
+			cfg.SetHarnessFastModel(spec.binary, fast)
+		}
 	}
 
-	cfg.SetHarnessModel(spec.binary, picked)
-	if err := env.save(cfg.Name, cfg); err != nil {
-		return "", err
+	if pickedModel || pickedFast {
+		if err := env.save(cfg.Name, cfg); err != nil {
+			return "", "", err
+		}
 	}
 
-	return picked, nil
+	return model, fast, nil
 }
 
-// modelToLaunch applies the rules for which model a harness launches with:
-// --model for this run only, else the model picked for this harness in the
-// profile, else ask. When asking, model is what the picker should suggest:
-// the saved model that --choose-model is replacing, or the harness default.
-func modelToLaunch(cfg config.Config, spec harnessSpec, parsed harnessArgs) (model string, ask bool) {
-	if parsed.launch.Model != "" {
-		return parsed.launch.Model, false
+// modelRequest is how one of a harness's models was asked for on this run.
+type modelRequest struct {
+	// what is shown in the picker title and in messages: "Claude Code",
+	// "Claude Code background work".
+	what string
+	// flag is the one to pass instead when there is no terminal to ask in;
+	// chooseFlag is the one that opens the picker again later.
+	flag, chooseFlag string
+	// flagged is the value of flag, for this run only.
+	flagged string
+	// choose says chooseFlag was passed: open the picker even if saved.
+	choose bool
+	// saved is what the profile remembers, if anything.
+	saved string
+	// defaults are tried in order when nothing is saved; the first one the
+	// profile can route to is used without asking.
+	defaults []string
+}
+
+// ensureModel returns the model for one request: the flag for this run
+// only, else the saved one, else whatever the picker decides, which it
+// reports through picked so the caller knows to save it.
+func (env *environment) ensureModel(cmd *cobra.Command, cfg config.Config, req modelRequest) (model string, picked bool, err error) {
+	switch {
+	case req.flagged != "":
+		return req.flagged, false, nil
+	case req.saved != "" && !req.choose:
+		return req.saved, false, nil
 	}
 
-	saved := cfg.HarnessModels[spec.binary]
-	if saved != "" && !parsed.chooseModel {
-		return saved, false
+	preferred := req.defaults
+	if req.saved != "" {
+		preferred = slices.Concat([]string{req.saved}, req.defaults)
+	}
+	model, asked, err := modelpicker.Run(cmd.Context(), modelpicker.Options{
+		Client:    client.New(cfg),
+		Harness:   req.what,
+		Preferred: preferred,
+		Confirm:   req.choose,
+	})
+	if errors.Is(err, modelpicker.ErrCancelled) {
+		return "", false, err
+	}
+	if err != nil {
+		// Most often there is no terminal to ask in, such as a script or CI.
+		return "", false, fmt.Errorf("no model picked for %s in profile %q; pass %s <id> or run in a terminal once (%w)", req.what, cfg.Name, req.flag, err)
 	}
-	if saved != "" {
-		return saved, true
+	if !asked {
+		if _, err := fmt.Fprintf(cmd.ErrOrStderr(), "Using %s for %s; change with %s.\n", model, req.what, req.chooseFlag); err != nil {
+			return "", false, err
+		}
 	}
 
-	return spec.defaultModel, true
+	return model, true, nil
 }
 
 // save stores cfg as the named profile and writes the file. The first profile
diff --git a/cmd/harness.go b/cmd/harness.go
index dd40594..0ac0f19 100644
--- a/cmd/harness.go
+++ b/cmd/harness.go
@@ -12,12 +12,18 @@ import (
 )
 
 const (
-	harnessProfileFlag     = "--" + profileFlag
-	harnessModelFlag       = "--model"
-	harnessChooseModelFlag = "--choose-model"
-	harnessEffortFlag      = "--reasoning-effort"
+	harnessProfileFlag         = "--" + profileFlag
+	harnessModelFlag           = "--model"
+	harnessChooseModelFlag     = "--choose-model"
+	harnessFastModelFlag       = "--fast-model"
+	harnessChooseFastModelFlag = "--choose-fast-model"
+	harnessEffortFlag          = "--reasoning-effort"
 )
 
+// harnessValueFlags are our flags that take a value, as `--flag v` or
+// `--flag=v`.
+var harnessValueFlags = []string{harnessProfileFlag, harnessModelFlag, harnessFastModelFlag, harnessEffortFlag}
+
 // errHarnessHelp signals that the leading flags asked for help.
 var errHarnessHelp = errors.New("help requested")
 
@@ -27,10 +33,20 @@ type harnessSpec struct {
 	binary string
 	// displayName is how the harness is referred to in messages.
 	displayName string
-	// defaultModel is the managed policy the picker suggests when nothing
-	// has been picked yet.
-	defaultModel string
-	newHarness   func(config.Config) (harnesses.Harness, error)
+	// defaultModels are the model ids to launch with when nothing has been
+	// picked yet, most preferred first; the first one the profile can
+	// route to is used without asking.
+	defaultModels []string
+	// defaultFastModels is the same for the model background work goes
+	// to. Empty for harnesses without such a slot.
+	defaultFastModels []string
+	newHarness        func(config.Config) (harnesses.Harness, error)
+}
+
+// hasFastModel reports whether the harness hands background work to a
+// second, smaller model.
+func (s harnessSpec) hasFastModel() bool {
+	return len(s.defaultFastModels) > 0
 }
 
 // newHarnessCommands returns the `requesty <harness>` commands, each of which
@@ -38,9 +54,10 @@ type harnessSpec struct {
 func newHarnessCommands(env *environment) []*cobra.Command {
 	return []*cobra.Command{
 		newHarnessCommand(env, harnessSpec{
-			binary:       "claude",
-			displayName:  "Claude Code",
-			defaultModel: "claude-sonnet-4-6",
+			binary:            "claude",
+			displayName:       "Claude Code",
+			defaultModels:     []string{"claude-sonnet-4-6"},
+			defaultFastModels: []string{"claude-haiku-4-5"},
 			newHarness: func(cfg config.Config) (harnesses.Harness, error) {
 				dir, err := harnesses.DefaultConfigDirClaudeCode()
 				if err != nil {
@@ -50,9 +67,9 @@ func newHarnessCommands(env *environment) []*cobra.Command {
 			},
 		}),
 		newHarnessCommand(env, harnessSpec{
-			binary:       "codex",
-			displayName:  "Codex",
-			defaultModel: "gpt-5.5",
+			binary:        "codex",
+			displayName:   "Codex",
+			defaultModels: []string{"gpt-5.5"},
 			newHarness: func(cfg config.Config) (harnesses.Harness, error) {
 				dir, err := harnesses.DefaultConfigDirCodex()
 				if err != nil {
@@ -70,24 +87,15 @@ func newHarnessCommands(env *environment) []*cobra.Command {
 // error, rather than a missing command.
 func newHarnessCommand(env *environment, spec harnessSpec) *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   fmt.Sprintf("%s [--profile <name>] [--model <id> | --choose-model] [--reasoning-effort <level>] [-- ] [%s args...]", spec.binary, spec.binary),
+		Use:   harnessUse(spec),
 		Short: fmt.Sprintf("Launch %s through Requesty", spec.displayName),
-		Long: fmt.Sprintf("Launch %s with its traffic routed through Requesty for this run only.\n\n", spec.displayName) +
-			"Flags:\n" +
-			fmt.Sprintf("  %-28s %s\n", harnessProfileFlag+" <name>", "Saved profile to run as (also "+profileEnv+")") +
-			fmt.Sprintf("  %-28s %s\n", harnessModelFlag+" <id>", "Model for this run only (a managed policy or any Requesty model id)") +
-			fmt.Sprintf("  %-28s %s\n", harnessChooseModelFlag, "Pick the model to launch with from now on") +
-			fmt.Sprintf("  %-28s %s\n", harnessEffortFlag+" <level>", "Reasoning effort: "+strings.Join(harnesses.Efforts, ", ")) +
-			fmt.Sprintf("  %-28s %s\n\n", "-h, --help", "Show this help") +
-			fmt.Sprintf("Anything else, or everything after `--`, is passed to `%s` untouched.\n\n", spec.binary) +
-			"Without --model, the model picked for this harness in the profile is used. The first\n" +
-			fmt.Sprintf("time, a picker asks (suggesting %s) and remembers the answer.\n\n", spec.defaultModel),
+		Long:  harnessLong(spec),
 		// We take over parsing so harness flags are never interpreted as ours.
 		DisableFlagParsing:    true,
 		DisableFlagsInUseLine: true,
 		SilenceUsage:          true,
 		RunE: func(cmd *cobra.Command, args []string) error {
-			parsed, err := parseHarnessArgs(args)
+			parsed, err := parseHarnessArgs(args, spec)
 			if errors.Is(err, errHarnessHelp) {
 				return cmd.Help()
 			}
@@ -105,7 +113,7 @@ func newHarnessCommand(env *environment, spec harnessSpec) *cobra.Command {
 				return fmt.Errorf("failed to set up %s: %w", spec.displayName, err)
 			}
 
-			parsed.launch.Model, err = env.ensureModel(cmd, cfg, spec, parsed)
+			parsed.launch.Model, parsed.launch.FastModel, err = env.ensureModels(cmd, cfg, spec, parsed)
 			if err != nil {
 				return err
 			}
@@ -117,12 +125,60 @@ func newHarnessCommand(env *environment, spec harnessSpec) *cobra.Command {
 	return cmd
 }
 
+// harnessUse is the one-line synopsis of `requesty <binary>`.
+func harnessUse(spec harnessSpec) string {
+	use := fmt.Sprintf("%s [%s <name>] [%s <id> | %s]", spec.binary, harnessProfileFlag, harnessModelFlag, harnessChooseModelFlag)
+	if spec.hasFastModel() {
+		use += fmt.Sprintf(" [%s <id> | %s]", harnessFastModelFlag, harnessChooseFastModelFlag)
+	}
+
+	return use + fmt.Sprintf(" [%s <level>] [-- ] [%s args...]", harnessEffortFlag, spec.binary)
+}
+
+// harnessLong is the help page of `requesty <binary>`.
+func harnessLong(spec harnessSpec) string {
+	flags := [][2]string{
+		{harnessProfileFlag + " <name>", "Saved profile to run as (also " + profileEnv + ")"},
+		{harnessModelFlag + " <id>", "Model for this run only (a managed policy or any Requesty model id)"},
+		{harnessChooseModelFlag, "Pick the model to launch with from now on"},
+	}
+	if spec.hasFastModel() {
+		flags = append(flags,
+			[2]string{harnessFastModelFlag + " <id>", "Model for background work, this run only"},
+			[2]string{harnessChooseFastModelFlag, "Pick the model for background work from now on"},
+		)
+	}
+	flags = append(flags,
+		[2]string{harnessEffortFlag + " <level>", "Reasoning effort: " + strings.Join(harnesses.Efforts, ", ")},
+		[2]string{"-h, --help", "Show this help"},
+	)
+
+	var b strings.Builder
+	fmt.Fprintf(&b, "Launch %s with its traffic routed through Requesty for this run only.\n\n", spec.displayName)
+	b.WriteString("Flags:\n")
+	for _, flag := range flags {
+		fmt.Fprintf(&b, "  %-28s %s\n", flag[0], flag[1])
+	}
+	fmt.Fprintf(&b, "\nAnything else, or everything after `--`, is passed to `%s` untouched.\n\n", spec.binary)
+	fmt.Fprintf(&b, "Without %s, the model remembered for this harness in the profile is used. The first\n", harnessModelFlag)
+	fmt.Fprintf(&b, "time, %s is used when the profile can route to it, else a picker asks; either way\n", spec.defaultModels[0])
+	fmt.Fprintf(&b, "the answer is remembered and %s picks again.\n\n", harnessChooseModelFlag)
+	if spec.hasFastModel() {
+		fmt.Fprintf(&b, "%s hands background work (titles, summaries, subagents marked haiku) to a smaller\n", spec.displayName)
+		fmt.Fprintf(&b, "model. That is settled the same way, preferring %s and falling back to the main\n", spec.defaultFastModels[0])
+		fmt.Fprintf(&b, "model itself; %s picks again.\n\n", harnessChooseFastModelFlag)
+	}
+
+	return b.String()
+}
+
 // harnessArgs is a harness command line split into our profile choice and
 // what the harness is launched with.
 type harnessArgs struct {
-	profile     string
-	chooseModel bool
-	launch      harnesses.LaunchOptions
+	profile         string
+	chooseModel     bool
+	chooseFastModel bool
+	launch          harnesses.LaunchOptions
 }
 
 // parseHarnessArgs splits our leading flags from the harness's own arguments.
@@ -130,8 +186,8 @@ type harnessArgs struct {
 // recognise does. That keeps `requesty claude --model x -p "hi"` and
 // `requesty claude -p "hi"` both working, and lets a harness flag that happens
 // to share a name with ours (`codex --model`) still reach the harness when it
-// appears later.
-func parseHarnessArgs(args []string) (harnessArgs, error) {
+// appears later. spec says which of our flags apply to this harness.
+func parseHarnessArgs(args []string, spec harnessSpec) (harnessArgs, error) {
 	var parsed harnessArgs
 
 flags:
@@ -150,7 +206,11 @@ flags:
 			parsed.chooseModel = true
 			args = args[1:]
 
-		case arg == harnessProfileFlag || arg == harnessModelFlag || arg == harnessEffortFlag:
+		case arg == harnessChooseFastModelFlag:
+			parsed.chooseFastModel = true
+			args = args[1:]
+
+		case slices.Contains(harnessValueFlags, arg):
 			if len(args) < 2 {
 				return parsed, fmt.Errorf("%s requires a value", arg)
 			}
@@ -159,7 +219,7 @@ flags:
 			}
 			args = args[2:]
 
-		case strings.HasPrefix(arg, harnessProfileFlag+"=") || strings.HasPrefix(arg, harnessModelFlag+"=") || strings.HasPrefix(arg, harnessEffortFlag+"="):
+		case isValueFlagWithEquals(arg):
 			flag, value, _ := strings.Cut(arg, "=")
 			if err := parsed.set(flag, value); err != nil {
 				return parsed, err
@@ -175,10 +235,33 @@ flags:
 	if parsed.chooseModel && parsed.launch.Model != "" {
 		return parsed, fmt.Errorf("%s and %s cannot be combined", harnessModelFlag, harnessChooseModelFlag)
 	}
+	if parsed.chooseFastModel && parsed.launch.FastModel != "" {
+		return parsed, fmt.Errorf("%s and %s cannot be combined", harnessFastModelFlag, harnessChooseFastModelFlag)
+	}
+	if !spec.hasFastModel() {
+		if parsed.launch.FastModel != "" {
+			return parsed, fmt.Errorf("%s has no separate model for background work; %s does not apply", spec.displayName, harnessFastModelFlag)
+		}
+		if parsed.chooseFastModel {
+			return parsed, fmt.Errorf("%s has no separate model for background work; %s does not apply", spec.displayName, harnessChooseFastModelFlag)
+		}
+	}
 
 	return parsed, nil
 }
 
+// isValueFlagWithEquals reports whether arg is one of ours in `--flag=value`
+// form.
+func isValueFlagWithEquals(arg string) bool {
+	for _, flag := range harnessValueFlags {
+		if strings.HasPrefix(arg, flag+"=") {
+			return true
+		}
+	}
+
+	return false
+}
+
 func (p *harnessArgs) set(flag, value string) error {
 	value = strings.TrimSpace(value)
 	if value == "" {
@@ -190,6 +273,8 @@ func (p *harnessArgs) set(flag, value string) error {
 		p.profile = value
 	case harnessModelFlag:
 		p.launch.Model = value
+	case harnessFastModelFlag:
+		p.launch.FastModel = value
 	case harnessEffortFlag:
 		if !slices.Contains(harnesses.Efforts, value) {
 			return fmt.Errorf("%s must be one of %s (got %q)", flag, strings.Join(harnesses.Efforts, ", "), value)
diff --git a/cmd/harness_test.go b/cmd/harness_test.go
index 26aaa8c..5370246 100644
--- a/cmd/harness_test.go
+++ b/cmd/harness_test.go
@@ -2,10 +2,15 @@ package cmd
 
 import (
 	"bytes"
+	"context"
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
 	"testing"
 
 	"github.com/requestyai/cli/internal/config"
 	"github.com/requestyai/cli/internal/harnesses"
+	"github.com/spf13/cobra"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 )
@@ -70,11 +75,21 @@ func TestParseHarnessArgs(t *testing.T) {
 			args: []string{"--choose-model", "--profile", "eu", "-p", "hi"},
 			want: harnessArgs{profile: "eu", chooseModel: true, launch: harnesses.LaunchOptions{Args: []string{"-p", "hi"}}},
 		},
+		{
+			name: "fast model in both forms",
+			args: []string{"--fast-model", "claude-haiku-4-5", "--model=claude-opus-4-8"},
+			want: harnessArgs{launch: harnesses.LaunchOptions{Model: "claude-opus-4-8", FastModel: "claude-haiku-4-5"}},
+		},
+		{
+			name: "choose fast model alongside a one-run model",
+			args: []string{"--model", "claude-opus-4-8", "--choose-fast-model", "-p", "hi"},
+			want: harnessArgs{chooseFastModel: true, launch: harnesses.LaunchOptions{Model: "claude-opus-4-8", Args: []string{"-p", "hi"}}},
+		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			got, err := parseHarnessArgs(tt.args)
+			got, err := parseHarnessArgs(tt.args, claudeSpec)
 
 			require.NoError(t, err)
 			assert.Equal(t, tt.want, got)
@@ -86,6 +101,7 @@ func TestParseHarnessArgsErrors(t *testing.T) {
 	tests := []struct {
 		name string
 		args []string
+		spec harnessSpec
 		want string
 	}{
 		{
@@ -123,11 +139,38 @@ func TestParseHarnessArgsErrors(t *testing.T) {
 			args: []string{"--model", "x", "--choose-model", "--", "-p", "hi"},
 			want: "--model and --choose-model cannot be combined",
 		},
+		{
+			name: "fast model without value",
+			args: []string{"--fast-model="},
+			want: "--fast-model requires a value",
+		},
+		{
+			name: "fast model and choose fast model together",
+			args: []string{"--choose-fast-model", "--fast-model", "x"},
+			want: "--fast-model and --choose-fast-model cannot be combined",
+		},
+		{
+			name: "fast model for a harness without one",
+			args: []string{"--fast-model", "x"},
+			spec: codexSpec,
+			want: "Codex has no separate model for background work; --fast-model does not apply",
+		},
+		{
+			name: "choose fast model for a harness without one",
+			args: []string{"--choose-fast-model"},
+			spec: codexSpec,
+			want: "Codex has no separate model for background work; --choose-fast-model does not apply",
+		},
 	}
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			_, err := parseHarnessArgs(tt.args)
+			spec := tt.spec
+			if spec.binary == "" {
+				spec = claudeSpec
+			}
+
+			_, err := parseHarnessArgs(tt.args, spec)
 
 			require.EqualError(t, err, tt.want)
 		})
@@ -136,12 +179,12 @@ func TestParseHarnessArgsErrors(t *testing.T) {
 
 func TestParseHarnessArgsHelp(t *testing.T) {
 	for _, args := range [][]string{{"-h"}, {"--help"}, {"--model", "x", "--help"}} {
-		_, err := parseHarnessArgs(args)
+		_, err := parseHarnessArgs(args, claudeSpec)
 		assert.ErrorIs(t, err, errHarnessHelp, "%v", args)
 	}
 
 	// After the harness's own flags begin, -h belongs to the harness.
-	got, err := parseHarnessArgs([]string{"-p", "hi", "--help"})
+	got, err := parseHarnessArgs([]string{"-p", "hi", "--help"}, claudeSpec)
 	require.NoError(t, err)
 	assert.Equal(t, []string{"-p", "hi", "--help"}, got.launch.Args)
 }
@@ -156,66 +199,180 @@ func TestHarnessCommandHelpShowsOurFlags(t *testing.T) {
 
 	assert.Contains(t, output.String(), "--profile")
 	assert.Contains(t, output.String(), "--choose-model")
+	assert.Contains(t, output.String(), "--fast-model")
+	assert.Contains(t, output.String(), "--choose-fast-model")
 	assert.Contains(t, output.String(), "--reasoning-effort")
 	assert.Contains(t, output.String(), "passed to `claude`")
-	assert.Contains(t, output.String(), "suggesting claude-sonnet-4-6")
+	assert.Contains(t, output.String(), "claude-sonnet-4-6 is used when the profile can route to it")
+	assert.Contains(t, output.String(), "claude-haiku-4-5")
 }
 
-func TestModelToLaunch(t *testing.T) {
-	spec := harnessSpec{binary: "claude", displayName: "Claude Code", defaultModel: "claude-sonnet-4-6"}
-	var fresh config.Config
-	var picked config.Config
-	picked.SetHarnessModel("claude", "claude-fable-5")
+func TestHarnessWithoutFastModelHidesItsFlags(t *testing.T) {
+	command := newRootCommand(&environment{store: oneProfile})
+	var output bytes.Buffer
+	command.SetOut(&output)
+	command.SetArgs([]string{"codex", "--help"})
 
-	tests := []struct {
-		name      string
-		cfg       config.Config
-		parsed    harnessArgs
-		wantModel string
-		wantAsk   bool
-	}{
-		{
-			name:      "flag wins over the saved model",
-			cfg:       picked,
-			parsed:    harnessArgs{launch: harnesses.LaunchOptions{Model: "anthropic/claude-opus-4-1"}},
-			wantModel: "anthropic/claude-opus-4-1",
-		},
-		{
-			name:      "saved model is used without asking",
-			cfg:       picked,
-			wantModel: "claude-fable-5",
-		},
-		{
-			name:      "nothing saved asks, suggesting the harness default",
-			cfg:       fresh,
-			wantModel: "claude-sonnet-4-6",
-			wantAsk:   true,
-		},
-		{
-			name:      "choose model asks again, suggesting the saved model",
-			cfg:       picked,
-			parsed:    harnessArgs{chooseModel: true},
-			wantModel: "claude-fable-5",
-			wantAsk:   true,
-		},
-		{
-			name:      "another harness's choice does not count",
-			cfg:       func() config.Config { var c config.Config; c.SetHarnessModel("codex", "gpt-5.5"); return c }(),
-			wantModel: "claude-sonnet-4-6",
-			wantAsk:   true,
-		},
-	}
+	require.NoError(t, command.Execute())
 
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			model, ask := modelToLaunch(tt.cfg, spec, tt.parsed)
+	assert.Contains(t, output.String(), "--choose-model")
+	assert.NotContains(t, output.String(), "fast-model")
+}
 
-			assert.Equal(t, tt.wantModel, model)
-			assert.Equal(t, tt.wantAsk, ask)
-		})
+func TestHarnessWithoutFastModelRejectsItsFlags(t *testing.T) {
+	for _, args := range [][]string{{"--fast-model", "x"}, {"--choose-fast-model"}} {
+		command := newRootCommand(&environment{store: oneProfile})
+		command.SetArgs(append([]string{"codex"}, args...))
+
+		err := command.Execute()
+
+		require.ErrorContains(t, err, "Codex has no separate model for background work", "%v", args)
+		require.ErrorContains(t, err, args[0]+" does not apply", "%v", args)
 	}
 }
 
+var (
+	claudeSpec = harnessSpec{binary: "claude", displayName: "Claude Code", defaultModels: []string{"claude-sonnet-4-6"}, defaultFastModels: []string{"claude-haiku-4-5"}}
+	codexSpec  = harnessSpec{binary: "codex", displayName: "Codex", defaultModels: []string{"gpt-5.5"}}
+)
+
+// routerServing is a router whose two model lists both hold ids. With none,
+// hitting it fails the test: the caller expects no lookup.
+func routerServing(t *testing.T, ids ...string) string {
+	t.Helper()
+
+	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if len(ids) == 0 {
+			t.Errorf("unexpected request to %s", r.URL.Path)
+			w.WriteHeader(http.StatusInternalServerError)
+			return
+		}
+		data := make([]map[string]string, 0, len(ids))
+		for _, id := range ids {
+			data = append(data, map[string]string{"id": id})
+		}
+		require.NoError(t, json.NewEncoder(w).Encode(map[string]any{"data": data}))
+	}))
+	t.Cleanup(server.Close)
+
+	return server.URL
+}
+
+// modelsEnvironment is an environment with one profile on router, saving to
+// a scratch home, plus a command to run against it and its stderr.
+func modelsEnvironment(t *testing.T, router string, profile config.Config) (*environment, config.Config, *cobra.Command, *bytes.Buffer) {
+	t.Helper()
+	t.Setenv("HOME", t.TempDir())
+
+	profile.APIKey, profile.RouterBaseURL = "k", router
+	env := &environment{store: config.Store{Current: "work", Profiles: map[string]config.Config{"work": profile}}}
+	cfg, err := env.store.Resolve("")
+	require.NoError(t, err)
+
+	var stderr bytes.Buffer
+	cmd := &cobra.Command{}
+	cmd.SetContext(context.Background())
+	cmd.SetErr(&stderr)
+
+	return env, cfg, cmd, &stderr
+}
+
+func TestEnsureModelsUsesRoutableDefaultsAndRemembersThem(t *testing.T) {
+	env, cfg, cmd, stderr := modelsEnvironment(t, routerServing(t, "claude-sonnet-4-6", "claude-haiku-4-5"), config.Config{})
+
+	model, fast, err := env.ensureModels(cmd, cfg, claudeSpec, harnessArgs{})
+
+	require.NoError(t, err)
+	assert.Equal(t, "claude-sonnet-4-6", model)
+	assert.Equal(t, "claude-haiku-4-5", fast)
+	assert.Contains(t, stderr.String(), "Using claude-sonnet-4-6 for Claude Code; change with --choose-model.")
+	assert.Contains(t, stderr.String(), "Using claude-haiku-4-5 for Claude Code background work; change with --choose-fast-model.")
+	saved, err := config.Load()
+	require.NoError(t, err)
+	assert.Equal(t, "claude-sonnet-4-6", saved.Profiles["work"].HarnessModels["claude"])
+	assert.Equal(t, "claude-haiku-4-5", saved.Profiles["work"].HarnessFastModels["claude"])
+}
+
+func TestEnsureModelsTriesDefaultsInOrder(t *testing.T) {
+	env, cfg, cmd, _ := modelsEnvironment(t, routerServing(t, "claude-sonnet-4-5", "claude-haiku-3-5"), config.Config{})
+	spec := claudeSpec
+	spec.defaultModels = []string{"claude-sonnet-4-6", "claude-sonnet-4-5"}
+	spec.defaultFastModels = []string{"claude-haiku-4-5", "claude-haiku-3-5"}
+
+	model, fast, err := env.ensureModels(cmd, cfg, spec, harnessArgs{})
+
+	require.NoError(t, err)
+	assert.Equal(t, "claude-sonnet-4-5", model)
+	assert.Equal(t, "claude-haiku-3-5", fast)
+}
+
+func TestEnsureModelsFallsBackToTheMainModelForBackgroundWork(t *testing.T) {
+	env, cfg, cmd, stderr := modelsEnvironment(t, routerServing(t, "claude-sonnet-4-6"), config.Config{})
+
+	model, fast, err := env.ensureModels(cmd, cfg, claudeSpec, harnessArgs{})
+
+	require.NoError(t, err)
+	assert.Equal(t, "claude-sonnet-4-6", model)
+	assert.Equal(t, "claude-sonnet-4-6", fast)
+	assert.Contains(t, stderr.String(), "Using claude-sonnet-4-6 for Claude Code background work")
+}
+
+func TestEnsureModelsUsesWhatIsRememberedWithoutLookingUp(t *testing.T) {
+	env, cfg, cmd, stderr := modelsEnvironment(t, routerServing(t), config.Config{
+		HarnessModels:     map[string]string{"claude": "claude-fable-5"},
+		HarnessFastModels: map[string]string{"claude": "claude-haiku-4-5@eu"},
+	})
+
+	model, fast, err := env.ensureModels(cmd, cfg, claudeSpec, harnessArgs{})
+
+	require.NoError(t, err)
+	assert.Equal(t, "claude-fable-5", model)
+	assert.Equal(t, "claude-haiku-4-5@eu", fast)
+	assert.Empty(t, stderr.String())
+	assert.NoFileExists(t, config.DisplayPath(), "nothing changed, so nothing is written")
+}
+
+func TestEnsureModelsFlagsAreForThisRunOnly(t *testing.T) {
+	env, cfg, cmd, _ := modelsEnvironment(t, routerServing(t), config.Config{
+		HarnessModels:     map[string]string{"claude": "claude-fable-5"},
+		HarnessFastModels: map[string]string{"claude": "claude-haiku-4-5"},
+	})
+	parsed := harnessArgs{launch: harnesses.LaunchOptions{Model: "anthropic/claude-opus-4-1", FastModel: "anthropic/claude-haiku-4-5"}}
+
+	model, fast, err := env.ensureModels(cmd, cfg, claudeSpec, parsed)
+
+	require.NoError(t, err)
+	assert.Equal(t, "anthropic/claude-opus-4-1", model)
+	assert.Equal(t, "anthropic/claude-haiku-4-5", fast)
+	assert.Equal(t, "claude-fable-5", env.store.Profiles["work"].HarnessModels["claude"])
+	assert.NoFileExists(t, config.DisplayPath())
+}
+
+func TestEnsureModelsSettlesBackgroundWorkNextToAOneRunModel(t *testing.T) {
+	env, cfg, cmd, _ := modelsEnvironment(t, routerServing(t, "claude-haiku-4-5"), config.Config{})
+	parsed := harnessArgs{launch: harnesses.LaunchOptions{Model: "anthropic/claude-opus-4-1"}}
+
+	model, fast, err := env.ensureModels(cmd, cfg, claudeSpec, parsed)
+
+	require.NoError(t, err)
+	assert.Equal(t, "anthropic/claude-opus-4-1", model)
+	assert.Equal(t, "claude-haiku-4-5", fast)
+	assert.Empty(t, env.store.Profiles["work"].HarnessModels, "a one-run model is not remembered")
+	assert.Equal(t, "claude-haiku-4-5", env.store.Profiles["work"].HarnessFastModels["claude"])
+}
+
+func TestEnsureModelsWithoutAFastModel(t *testing.T) {
+	env, cfg, cmd, stderr := modelsEnvironment(t, routerServing(t, "gpt-5.5"), config.Config{})
+
+	model, fast, err := env.ensureModels(cmd, cfg, codexSpec, harnessArgs{})
+
+	require.NoError(t, err)
+	assert.Equal(t, "gpt-5.5", model)
+	assert.Empty(t, fast)
+	assert.NotContains(t, stderr.String(), "background work")
+	assert.Empty(t, env.store.Profiles["work"].HarnessFastModels)
+}
+
 func TestHarnessProfileFlag(t *testing.T) {
 	command := newRootCommand(&environment{store: twoProfiles})
 	command.SetArgs([]string{"claude", "--profile", "sales"})
diff --git a/internal/config/config.go b/internal/config/config.go
index a37b0b9..8d429c6 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -25,18 +25,35 @@ var ErrNoProfiles = errors.New("no Requesty profile configured; run `requesty lo
 // Config is what a client or harness runs with: an API key and the router it
 // is sent to. The settings file holds one per profile.
 type Config struct {
-	Name          string            `json:"-"`
-	APIKey        string            `json:"api_key"`
-	RouterBaseURL string            `json:"router_base_url"`
+	Name          string `json:"-"`
+	APIKey        string `json:"api_key"`
+	RouterBaseURL string `json:"router_base_url"`
+	// HarnessModels is the model each harness was picked to launch with.
 	HarnessModels map[string]string `json:"harness_models,omitempty"`
+	// HarnessFastModels is the model each harness hands background work to,
+	// for harnesses that have such a slot. Kept apart from HarnessModels so
+	// a settings file stays readable by versions before it existed.
+	HarnessFastModels map[string]string `json:"harness_fast_models,omitempty"`
 }
 
-// SetHarnessModel remembers model as the one to launch harness with.
+// SetHarnessModel remembers model as the one to launch harness with. It also
+// forgets the fast model: a new main model may sit in another region, so
+// what goes alongside it is settled afresh.
 func (c *Config) SetHarnessModel(harness, model string) {
 	if c.HarnessModels == nil {
 		c.HarnessModels = make(map[string]string)
 	}
 	c.HarnessModels[harness] = model
+	delete(c.HarnessFastModels, harness)
+}
+
+// SetHarnessFastModel remembers model as the one harness hands background
+// work to.
+func (c *Config) SetHarnessFastModel(harness, model string) {
+	if c.HarnessFastModels == nil {
+		c.HarnessFastModels = make(map[string]string)
+	}
+	c.HarnessFastModels[harness] = model
 }
 
 func (c Config) APIBaseURL() string {
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index 64f4dec..819bb9e 100644
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -125,6 +125,7 @@ func TestSaveRoundTrips(t *testing.T) {
 	var store Store
 	work := Config{APIKey: "rqsty-work", RouterBaseURL: "https://router.eu.example"}
 	work.SetHarnessModel("claude", "claude-sonnet-4-6")
+	work.SetHarnessFastModel("claude", "claude-haiku-4-5")
 	store.Set("work", work)
 
 	require.NoError(t, Save(store))
@@ -133,6 +134,19 @@ func TestSaveRoundTrips(t *testing.T) {
 	require.NoError(t, err)
 	assert.Equal(t, store, got)
 	assert.Equal(t, "claude-sonnet-4-6", got.Profiles["work"].HarnessModels["claude"])
+	assert.Equal(t, "claude-haiku-4-5", got.Profiles["work"].HarnessFastModels["claude"])
+}
+
+func TestSetHarnessModelForgetsFastModel(t *testing.T) {
+	var cfg Config
+	cfg.SetHarnessModel("claude", "claude-sonnet-4-6")
+	cfg.SetHarnessFastModel("claude", "claude-haiku-4-5")
+	cfg.SetHarnessFastModel("other", "kept")
+
+	cfg.SetHarnessModel("claude", "claude-sonnet-4-6@eu")
+
+	assert.NotContains(t, cfg.HarnessFastModels, "claude")
+	assert.Equal(t, "kept", cfg.HarnessFastModels["other"])
 }
 
 func TestHarnessModelsAreOmittedUntilSet(t *testing.T) {
@@ -140,6 +154,7 @@ func TestHarnessModelsAreOmittedUntilSet(t *testing.T) {
 
 	require.NoError(t, err)
 	assert.NotContains(t, string(data), "harness_models")
+	assert.NotContains(t, string(data), "harness_fast_models")
 }
 
 func TestResolve(t *testing.T) {
diff --git a/internal/harnesses/claude.go b/internal/harnesses/claude.go
index 496aa96..44c9f26 100644
--- a/internal/harnesses/claude.go
+++ b/internal/harnesses/claude.go
@@ -205,6 +205,13 @@ func (c *ClaudeHarness) Launch(opts LaunchOptions) error {
 	if opts.Model != "" {
 		env["ANTHROPIC_MODEL"] = opts.Model
 	}
+	if opts.FastModel != "" {
+		// The haiku alias covers background work (titles, summaries,
+		// subagents declared as haiku). ANTHROPIC_SMALL_FAST_MODEL is the
+		// name versions before 2.1.2 read; both get the same value.
+		env["ANTHROPIC_DEFAULT_HAIKU_MODEL"] = opts.FastModel
+		env["ANTHROPIC_SMALL_FAST_MODEL"] = opts.FastModel
+	}
 
 	argv := []string{"claude"}
 	if !hasAnyFlag(opts.Args, claudeSettingsFlags) {
diff --git a/internal/harnesses/claude_test.go b/internal/harnesses/claude_test.go
index 5765fdf..1c09e2c 100644
--- a/internal/harnesses/claude_test.go
+++ b/internal/harnesses/claude_test.go
@@ -74,9 +74,10 @@ func TestClaudeHarnessLaunchInjectsRequesty(t *testing.T) {
 	harness := NewClaudeHarness(cfg, t.TempDir())
 
 	err := harness.Launch(LaunchOptions{
-		Model:  "anthropic/claude-fable-5",
-		Effort: EffortHigh,
-		Args:   []string{"--dangerously-skip-permissions", "-p", "hello"},
+		Model:     "anthropic/claude-fable-5",
+		FastModel: "claude-haiku-4-5",
+		Effort:    EffortHigh,
+		Args:      []string{"--dangerously-skip-permissions", "-p", "hello"},
 		Env: []string{
 			"HOME=/home/me",
 			"ANTHROPIC_AUTH_TOKEN=stale-token",
@@ -93,6 +94,8 @@ func TestClaudeHarnessLaunchInjectsRequesty(t *testing.T) {
 	assert.Contains(t, captured.env, "ANTHROPIC_API_KEY=my-api-key")
 	assert.Contains(t, captured.env, "REQUESTY_API_KEY=my-api-key")
 	assert.Contains(t, captured.env, "ANTHROPIC_MODEL=anthropic/claude-fable-5")
+	assert.Contains(t, captured.env, "ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5")
+	assert.Contains(t, captured.env, "ANTHROPIC_SMALL_FAST_MODEL=claude-haiku-4-5")
 	assert.Contains(t, captured.env, "CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1")
 	for _, entry := range captured.env {
 		assert.NotContains(t, entry, "ANTHROPIC_AUTH_TOKEN=", "the bearer token path must be cleared")
@@ -133,6 +136,7 @@ func TestClaudeHarnessLaunchWithoutOverridesIsMinimal(t *testing.T) {
 	assert.Equal(t, "--settings", captured.argv[1])
 	for _, entry := range captured.env {
 		assert.NotContains(t, entry, "ANTHROPIC_MODEL=", "no model means the harness keeps its default")
+		assert.NotContains(t, entry, "ANTHROPIC_DEFAULT_HAIKU_MODEL=", "no fast model means the harness keeps its default")
 	}
 }
 
diff --git a/internal/harnesses/harnesses.go b/internal/harnesses/harnesses.go
index 5452f3b..f625678 100644
--- a/internal/harnesses/harnesses.go
+++ b/internal/harnesses/harnesses.go
@@ -25,6 +25,11 @@ type LaunchOptions struct {
 	// own (including a model our Configure wrote into its settings file
 	// earlier), which a gateway with an access list may well reject.
 	Model string
+	// FastModel is what the harness hands background work to, such as
+	// Claude Code's haiku alias. Empty leaves the harness's own default,
+	// which is an Anthropic model id a gateway does not know. Harnesses
+	// without such a slot ignore it.
+	FastModel string
 	// Effort is one of Efforts, or empty for the harness default.
 	Effort string
 	// Args is passed to the harness binary untouched, after our own flags.
diff --git a/internal/modelpicker/picker.go b/internal/modelpicker/picker.go
index fa8270a..4123fa6 100644
--- a/internal/modelpicker/picker.go
+++ b/internal/modelpicker/picker.go
@@ -24,32 +24,65 @@ import (
 // ErrCancelled reports that the dialog was closed without choosing.
 var ErrCancelled = errors.New("no model chosen")
 
-// Options says what to pick for and what to suggest.
+// Options says what to pick for and what to prefer.
 type Options struct {
 	// Client fetches the two lists the picker shows, as the profile the
 	// harness will run with.
 	Client *client.Client
 	// Harness is the display name shown in the title.
 	Harness string
-	// Preselect is the model the cursor starts on when it is listed: the
-	// harness's recommended default, or what was picked last time.
-	Preselect string
+	// Preferred lists models in order of preference: what was picked last
+	// time, or the harness's defaults. The first one the profile can route
+	// to is returned without asking, or with Confirm set, is where the
+	// cursor starts.
+	Preferred []string
+	// Confirm always shows the dialog, for when the user asked to choose.
+	Confirm bool
 }
 
-// Run shows the picker and returns the chosen model id. It draws on stderr so
-// the harness's own stdout is untouched.
-func Run(ctx context.Context, opts Options) (string, error) {
+// Run returns the model to launch with. Unless Confirm is set, the first of
+// Preferred that the profile can route to is returned without asking, and
+// asked reports false. Otherwise the dialog is shown, drawn on stderr so the
+// harness's own stdout is untouched.
+func Run(ctx context.Context, opts Options) (chosen string, asked bool, err error) {
+	if !opts.Confirm {
+		if preferred := routablePreferred(ctx, opts); preferred != "" {
+			return preferred, false, nil
+		}
+	}
+
 	final, err := tea.NewProgram(newModel(ctx, opts), tea.WithContext(ctx), tea.WithOutput(os.Stderr)).Run()
 	if err != nil {
-		return "", fmt.Errorf("failed to run model picker: %w", err)
+		return "", true, fmt.Errorf("failed to run model picker: %w", err)
 	}
 
 	finished, ok := final.(model)
 	if !ok || finished.chosen == "" {
-		return "", ErrCancelled
+		return "", true, ErrCancelled
+	}
+
+	return finished.chosen, true, nil
+}
+
+// routablePreferred is the first of Preferred that the profile can route to,
+// or empty. Both lists come back filtered by the key's access list, so
+// anything found is known to be permitted. A list that cannot be fetched
+// counts as empty here; the dialog will show the error.
+func routablePreferred(ctx context.Context, opts Options) string {
+	if len(opts.Preferred) == 0 {
+		return ""
+	}
+
+	policies, _ := opts.Client.ManagedPolicies(ctx)
+	models, _ := opts.Client.Models(ctx)
+	listed := slices.Concat(policies, models)
+	for _, id := range opts.Preferred {
+		if slices.ContainsFunc(listed, func(m client.Model) bool { return m.ID == id }) {
+			return id
+		}
 	}
 
-	return finished.chosen, nil
+	return ""
 }
 
 const (
@@ -234,14 +267,12 @@ func (m model) filtered() []client.Model {
 	return matches
 }
 
-// preselectedCursor is where the cursor goes on a fresh list: on Preselect
-// when it is there, else the top.
+// preselectedCursor is where the cursor goes on a fresh list: on the first of
+// Preferred that is there, else the top.
 func (m model) preselectedCursor() int {
-	if m.opts.Preselect == "" {
-		return 0
-	}
-	for i, model := range m.filtered() {
-		if model.ID == m.opts.Preselect {
+	filtered := m.filtered()
+	for _, id := range m.opts.Preferred {
+		if i := slices.IndexFunc(filtered, func(m client.Model) bool { return m.ID == id }); i >= 0 {
 			return i
 		}
 	}
diff --git a/internal/modelpicker/picker_test.go b/internal/modelpicker/picker_test.go
index 4da3363..4b28336 100644
--- a/internal/modelpicker/picker_test.go
+++ b/internal/modelpicker/picker_test.go
@@ -84,10 +84,10 @@ func view(m model) string {
 }
 
 // loaded runs the picker's own load commands so both tabs are filled in.
-func loaded(t *testing.T, l lists, preselect string) model {
+func loaded(t *testing.T, l lists, preferred ...string) model {
 	t.Helper()
 
-	m := newModel(context.Background(), Options{Client: newClient(t, l), Harness: "Claude Code", Preselect: preselect})
+	m := newModel(context.Background(), Options{Client: newClient(t, l), Harness: "Claude Code", Preferred: preferred})
 	for _, tab := range []tab{tabPolicies, tabModels} {
 		msg := m.load(tab)()
 		require.IsType(t, loadedMsg{}, msg)
@@ -97,8 +97,52 @@ func loaded(t *testing.T, l lists, preselect string) model {
 	return m
 }
 
-func TestShowsPoliciesFirstSortedWithPreselectUnderCursor(t *testing.T) {
-	m := loaded(t, lists{policies: policies, models: models}, "claude-sonnet-4-6")
+func TestRunReturnsTheFirstRoutablePreferredWithoutAsking(t *testing.T) {
+	opts := Options{Client: newClient(t, lists{policies: policies, models: models}), Harness: "Claude Code"}
+
+	tests := []struct {
+		name      string
+		preferred []string
+		want      string
+	}{
+		{name: "a managed policy", preferred: []string{"claude-sonnet-4-6"}, want: "claude-sonnet-4-6"},
+		{name: "a model", preferred: []string{"openai/gpt-5.5"}, want: "openai/gpt-5.5"},
+		{name: "the first that is listed", preferred: []string{"claude-haiku-4-5", "claude-fable-5", "gpt-5.5"}, want: "claude-fable-5"},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			opts.Preferred = tt.preferred
+
+			got, asked, err := Run(context.Background(), opts)
+
+			require.NoError(t, err)
+			assert.Equal(t, tt.want, got)
+			assert.False(t, asked)
+		})
+	}
+}
+
+func TestRoutablePreferredIsEmptyWhenNothingMatches(t *testing.T) {
+	tests := []struct {
+		name string
+		l    lists
+	}{
+		{name: "not listed", l: lists{policies: policies, models: models}},
+		{name: "lists cannot be fetched", l: lists{}},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			opts := Options{Client: newClient(t, tt.l), Preferred: []string{"claude-haiku-4-5"}}
+
+			assert.Empty(t, routablePreferred(context.Background(), opts))
+		})
+	}
+}
+
+func TestShowsPoliciesFirstSortedWithPreferredUnderCursor(t *testing.T) {
+	m := loaded(t, lists{policies: policies, models: models}, "claude-haiku-4-5", "claude-sonnet-4-6")
 
 	assert.Equal(t, tabPolicies, m.tab)
 	assert.Equal(t, 1, m.cursor, "sorted: claude-fable-5, claude-sonnet-4-6, gpt-5.5")
@@ -114,7 +158,7 @@ func TestShowsPoliciesFirstSortedWithPreselectUnderCursor(t *testing.T) {
 }
 
 func TestEnterChoosesTheModelUnderTheCursor(t *testing.T) {
-	m := loaded(t, lists{policies: policies, models: models}, "")
+	m := loaded(t, lists{policies: policies, models: models})
 
 	m, _ = update(m, key("down"))
 	m, cmd := update(m, key("enter"))
@@ -156,14 +200,14 @@ func TestSearchFiltersTheCurrentTabAndResetsCursor(t *testing.T) {
 }
 
 func TestNoPoliciesLandsOnModelsTab(t *testing.T) {
-	m := loaded(t, lists{policies: []client.Model{}, models: models}, "")
+	m := loaded(t, lists{policies: []client.Model{}, models: models})
 
 	assert.Equal(t, tabModels, m.tab)
 	assert.Contains(t, view(m), "❯ anthropic/claude-sonnet-4-6")
 }
 
 func TestLoadErrorMovesToModelsAndIsShownOnItsTab(t *testing.T) {
-	m := loaded(t, lists{models: models}, "")
+	m := loaded(t, lists{models: models})
 
 	assert.Equal(t, tabModels, m.tab)
 
@@ -183,7 +227,7 @@ func TestLoadingStateBeforeListsArrive(t *testing.T) {
 }
 
 func TestEscapeLeavesNothingChosen(t *testing.T) {
-	m := loaded(t, lists{policies: policies, models: models}, "")
+	m := loaded(t, lists{policies: policies, models: models})
 
 	m, cmd := update(m, key("esc"))
 
@@ -192,7 +236,7 @@ func TestEscapeLeavesNothingChosen(t *testing.T) {
 }
 
 func TestCursorStaysWithinTheList(t *testing.T) {
-	m := loaded(t, lists{policies: policies, models: models}, "")
+	m := loaded(t, lists{policies: policies, models: models})
 
 	for range 10 {
 		m, _ = update(m, key("down"))

From a8d183e8782b909868010460a24381d55a915680 Mon Sep 17 00:00:00 2001
From: fayzan <fayzan@requesty.ai>
Date: Thu, 24 Sep 2026 11:20:15 +0100
Subject: [PATCH 7/9] Implement launching opencode/pi/hermes harnesses

---
 README.md                         |  43 ++++-
 cmd/harness.go                    |  36 ++++
 cmd/harness_test.go               |   2 +-
 internal/harnesses/claude_test.go | 127 --------------
 internal/harnesses/codex_test.go  |  75 --------
 internal/harnesses/hermes.go      | 136 ++++++++++++++-
 internal/harnesses/home.go        |   7 +
 internal/harnesses/launch_test.go |  93 ----------
 internal/harnesses/opencode.go    | 157 ++++++++++++++++-
 internal/harnesses/pi.go          | 277 +++++++++++++++++++++++++++++-
 internal/harnesses/pi/requesty.ts |  53 ++++++
 11 files changed, 694 insertions(+), 312 deletions(-)
 delete mode 100644 internal/harnesses/launch_test.go
 create mode 100644 internal/harnesses/pi/requesty.ts

diff --git a/README.md b/README.md
index 6dc3ce7..afa4cc8 100644
--- a/README.md
+++ b/README.md
@@ -45,7 +45,7 @@ a new terminal, or run the `source` command it prints, then run `requesty`.
 
 **Sign in with your browser**
 
-The first time you run `requesty`, `requesty claude` or `requesty codex` on a machine without a profile,
+The first time you run `requesty` or a harness command such as `requesty claude` on a machine without a profile,
 the CLI opens with a welcome page that says what is about to happen. Press enter and it signs you in
 to Requesty in your browser; once you approve, it creates an API key in your account, named after
 this machine (`Requesty CLI (my-laptop)`), and saves it as a [profile](#profiles) in
@@ -94,9 +94,9 @@ unless you pass `--profile`.
 
 ## Launching a harness
 
-`requesty claude` and `requesty codex` start the harness with its traffic routed through Requesty
-for that run only; nothing on disk is changed. The current profile is used unless you select
-another.
+`requesty claude`, `requesty codex`, `requesty opencode`, `requesty pi` and `requesty hermes`
+start the harness with its traffic routed through Requesty for that run only; the harness's own
+configuration is not changed. The current profile is used unless you select another.
 
 The first time you launch a harness from a profile, the CLI settles which model it should use and
 remembers the answer in the profile. When the key can route to the harness's recommended default
@@ -120,12 +120,37 @@ requesty claude --model anthropic/claude-opus-4-1  # this model, just for this r
 requesty claude --choose-model                     # pick again and remember the new answer
 requesty claude --choose-fast-model                # pick what background work runs on
 requesty codex --reasoning-effort high -- --full-auto
+requesty opencode --model gpt-5.5 -- run "explain this repo"
+requesty pi --reasoning-effort medium
+requesty hermes -- chat -q "hello"
 ```
 
 Profile precedence is `--profile <name>`, then `REQUESTY_PROFILE`, then the current profile set
 with `requesty profiles use`. For a harness command, put `--profile` after the harness name and
 before the first argument that is passed through to the harness.
 
+Each harness is pointed at Requesty in the way it allows without touching its files:
+
+- **Claude Code** gets `ANTHROPIC_BASE_URL` and the key through the environment plus a
+  `--settings` document for this run.
+- **Codex** gets a `requesty` model provider through `-c` overrides.
+- **OpenCode** knows Requesty as a built-in provider that switches on when `REQUESTY_API_KEY` is
+  set; an `OPENCODE_CONFIG_CONTENT` document, merged into any you already export, pins it to this
+  profile, and the model is passed as `-m requesty/<model>`. A Requesty key stored earlier with
+  `opencode auth login` can take precedence over the profile's; the CLI warns when the two differ.
+- **Pi** has no flag for a custom provider, so the CLI writes a small extension and a catalog of
+  the models your key can route to under `~/.requesty/pi/` and starts Pi with `--extension`. The
+  catalog is refreshed from your account on each launch and kept from last time when that fails.
+  Other vendors' API key variables are dropped from Pi's environment so every model it offers
+  goes through Requesty.
+- **Hermes** is started as `--provider custom` with `CUSTOM_BASE_URL` pointing at the router.
+  Hermes loads `~/.hermes/.env` over the environment, so the CLI warns when a value there would
+  replace one of its own.
+
+Reasoning effort (`--reasoning-effort minimal|low|medium|high|xhigh|max`) maps onto each harness's
+own flag; levels a harness does not support are rejected before it starts. Flags you pass through
+for the model, provider or effort take precedence over the CLI's.
+
 ## Profiles
 
 A profile is one sign-in: an API key and the router it is sent to. Most people have one. You want
@@ -367,8 +392,14 @@ automatically ran without a saved profile. Run `requesty login` or
 per group, and you are not in one yet. Ask an organization admin to add you to a group, then sign
 in again.
 
-**Claude Code or Codex gets a `401`.** The key was revoked or has expired. Replace that profile
-with `requesty login --profile <name> --force`.
+**A harness gets a `401`.** The key was revoked or has expired. Replace that profile
+with `requesty login --profile <name> --force`. With OpenCode, also check for a Requesty key stored
+by `opencode auth login`, which wins over the profile's; `opencode auth logout` removes it. With
+Hermes, check `~/.hermes/.env` for a `REQUESTY_API_KEY` or `CUSTOM_BASE_URL` entry, which Hermes
+loads over the environment.
+
+**`Requesty needs pi 0.84.0 or newer`.** `requesty pi` registers Requesty through Pi's provider
+extension API, which arrived in Pi 0.84.0. Upgrade Pi and try again.
 
 **`Could not load usage`.** The usage panel asks the management API about your own key, which any
 key may do. A `401` means the key was revoked or has expired: run `requesty login` to get a new
diff --git a/cmd/harness.go b/cmd/harness.go
index 0ac0f19..25ef251 100644
--- a/cmd/harness.go
+++ b/cmd/harness.go
@@ -78,6 +78,42 @@ func newHarnessCommands(env *environment) []*cobra.Command {
 				return harnesses.NewCodexHarness(cfg, dir), nil
 			},
 		}),
+		newHarnessCommand(env, harnessSpec{
+			binary:        "opencode",
+			displayName:   "OpenCode",
+			defaultModels: []string{"claude-sonnet-4-6"},
+			newHarness: func(cfg config.Config) (harnesses.Harness, error) {
+				dir, err := harnesses.DefaultConfigDirOpenCode()
+				if err != nil {
+					return nil, err
+				}
+				return harnesses.NewOpenCodeHarness(cfg, dir), nil
+			},
+		}),
+		newHarnessCommand(env, harnessSpec{
+			binary:        "pi",
+			displayName:   "Pi",
+			defaultModels: []string{"claude-sonnet-4-6"},
+			newHarness: func(cfg config.Config) (harnesses.Harness, error) {
+				dir, err := harnesses.DefaultConfigDirPi()
+				if err != nil {
+					return nil, err
+				}
+				return harnesses.NewPiHarness(cfg, dir), nil
+			},
+		}),
+		newHarnessCommand(env, harnessSpec{
+			binary:        "hermes",
+			displayName:   "Hermes",
+			defaultModels: []string{"claude-sonnet-4-6"},
+			newHarness: func(cfg config.Config) (harnesses.Harness, error) {
+				dir, err := harnesses.DefaultConfigDirHermes()
+				if err != nil {
+					return nil, err
+				}
+				return harnesses.NewHermesHarness(cfg, dir), nil
+			},
+		}),
 	}
 }
 
diff --git a/cmd/harness_test.go b/cmd/harness_test.go
index 5370246..6787257 100644
--- a/cmd/harness_test.go
+++ b/cmd/harness_test.go
@@ -18,7 +18,7 @@ import (
 func TestHarnessCommandsAreRegistered(t *testing.T) {
 	command := newRootCommand(&environment{})
 
-	for _, name := range []string{"claude", "codex"} {
+	for _, name := range []string{"claude", "codex", "opencode", "pi", "hermes"} {
 		sub, _, err := command.Find([]string{name})
 		require.NoError(t, err)
 		assert.Equal(t, name, sub.Name())
diff --git a/internal/harnesses/claude_test.go b/internal/harnesses/claude_test.go
index 1c09e2c..75b3aa3 100644
--- a/internal/harnesses/claude_test.go
+++ b/internal/harnesses/claude_test.go
@@ -1,11 +1,8 @@
 package harnesses
 
 import (
-	"encoding/json"
-	"errors"
 	"os"
 	"path/filepath"
-	"runtime"
 	"testing"
 
 	"github.com/requestyai/cli/internal/config"
@@ -67,130 +64,6 @@ func TestClaudeHarnessConfigureCreatesMissingConfig(t *testing.T) {
 	}`, string(settings))
 }
 
-func TestClaudeHarnessLaunchInjectsRequesty(t *testing.T) {
-	binaryPath := fakeBinary(t, "claude")
-	captured := captureExec(t)
-	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
-	harness := NewClaudeHarness(cfg, t.TempDir())
-
-	err := harness.Launch(LaunchOptions{
-		Model:     "anthropic/claude-fable-5",
-		FastModel: "claude-haiku-4-5",
-		Effort:    EffortHigh,
-		Args:      []string{"--dangerously-skip-permissions", "-p", "hello"},
-		Env: []string{
-			"HOME=/home/me",
-			"ANTHROPIC_AUTH_TOKEN=stale-token",
-			"ANTHROPIC_API_KEY=someone-elses-key",
-		},
-	})
-	require.NoError(t, err)
-
-	assert.Equal(t, binaryPath, captured.path)
-
-	// Environment: Requesty replaces any Anthropic credential already present.
-	assert.Contains(t, captured.env, "HOME=/home/me")
-	assert.Contains(t, captured.env, "ANTHROPIC_BASE_URL=https://router.requesty.ai")
-	assert.Contains(t, captured.env, "ANTHROPIC_API_KEY=my-api-key")
-	assert.Contains(t, captured.env, "REQUESTY_API_KEY=my-api-key")
-	assert.Contains(t, captured.env, "ANTHROPIC_MODEL=anthropic/claude-fable-5")
-	assert.Contains(t, captured.env, "ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-4-5")
-	assert.Contains(t, captured.env, "ANTHROPIC_SMALL_FAST_MODEL=claude-haiku-4-5")
-	assert.Contains(t, captured.env, "CLAUDE_CODE_SKIP_FAST_MODE_ORG_CHECK=1")
-	for _, entry := range captured.env {
-		assert.NotContains(t, entry, "ANTHROPIC_AUTH_TOKEN=", "the bearer token path must be cleared")
-	}
-
-	// Arguments: argv[0], then our --settings and --effort, then the user's flags verbatim.
-	require.Len(t, captured.argv, 8)
-	assert.Equal(t, "claude", captured.argv[0])
-	assert.Equal(t, "--settings", captured.argv[1])
-	assert.Equal(t, []string{"--effort", "high", "--dangerously-skip-permissions", "-p", "hello"}, captured.argv[3:])
-
-	var settings struct {
-		APIKeyHelper string            `json:"apiKeyHelper"`
-		Env          map[string]string `json:"env"`
-	}
-	require.NoError(t, json.Unmarshal([]byte(captured.argv[2]), &settings))
-	assert.Equal(t, "https://router.requesty.ai", settings.Env["ANTHROPIC_BASE_URL"])
-	assert.Equal(t, "", settings.Env["CLAUDE_CODE_USE_BEDROCK"])
-	assert.Equal(t, "", settings.Env["CLAUDE_CODE_USE_VERTEX"])
-	assert.Equal(t, "", settings.Env["ANTHROPIC_AUTH_TOKEN"])
-	assert.NotContains(t, captured.argv[2], "my-api-key", "the key stays out of argv")
-	if runtime.GOOS == "windows" {
-		assert.Empty(t, settings.APIKeyHelper)
-	} else {
-		assert.Equal(t, `printf %s "$REQUESTY_API_KEY"`, settings.APIKeyHelper)
-	}
-}
-
-func TestClaudeHarnessLaunchWithoutOverridesIsMinimal(t *testing.T) {
-	fakeBinary(t, "claude")
-	captured := captureExec(t)
-	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
-	harness := NewClaudeHarness(cfg, t.TempDir())
-
-	require.NoError(t, harness.Launch(LaunchOptions{Env: []string{}}))
-
-	require.Len(t, captured.argv, 3, "only claude --settings <json>")
-	assert.Equal(t, "--settings", captured.argv[1])
-	for _, entry := range captured.env {
-		assert.NotContains(t, entry, "ANTHROPIC_MODEL=", "no model means the harness keeps its default")
-		assert.NotContains(t, entry, "ANTHROPIC_DEFAULT_HAIKU_MODEL=", "no fast model means the harness keeps its default")
-	}
-}
-
-func TestClaudeHarnessLaunchRespectsUserSettingsFlag(t *testing.T) {
-	fakeBinary(t, "claude")
-	captured := captureExec(t)
-	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
-	harness := NewClaudeHarness(cfg, t.TempDir())
-
-	for _, userArgs := range [][]string{
-		{"--settings", "/tmp/mine.json"},
-		{"--settings=/tmp/mine.json"},
-		{"--setting-sources", "user"},
-	} {
-		require.NoError(t, harness.Launch(LaunchOptions{Args: userArgs, Env: []string{}}))
-		assert.Equal(t, userArgs, captured.argv[1:], "user-managed settings must pass through untouched")
-	}
-}
-
-func TestClaudeHarnessLaunchRejectsUnsupportedEffort(t *testing.T) {
-	fakeBinary(t, "claude")
-	captured := captureExec(t)
-	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
-	harness := NewClaudeHarness(cfg, t.TempDir())
-
-	err := harness.Launch(LaunchOptions{Effort: EffortMinimal, Env: []string{}})
-
-	require.EqualError(t, err, `Claude Code does not support reasoning effort "minimal" (accepted: low, medium, high, xhigh, max)`)
-	assert.Empty(t, captured.path, "nothing should be launched")
-}
-
-func TestClaudeHarnessLaunchRequiresBinary(t *testing.T) {
-	t.Setenv("PATH", t.TempDir())
-	captured := captureExec(t)
-	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
-	harness := NewClaudeHarness(cfg, t.TempDir())
-
-	err := harness.Launch(LaunchOptions{Env: []string{}})
-
-	require.EqualError(t, err, "`claude` is not on PATH; install Claude Code (https://code.claude.com/docs/en/setup) and try again")
-	assert.Empty(t, captured.path)
-}
-
-func TestClaudeHarnessLaunchWrapsExecFailure(t *testing.T) {
-	fakeBinary(t, "claude")
-	previous := execProcess
-	execProcess = func(string, []string, []string) error { return errors.New("boom") }
-	t.Cleanup(func() { execProcess = previous })
-	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
-	harness := NewClaudeHarness(cfg, t.TempDir())
-
-	require.EqualError(t, harness.Launch(LaunchOptions{Env: []string{}}), "failed to launch claude: boom")
-}
-
 func TestClaudeHarnessDefaultConfigDir(t *testing.T) {
 	homePath, err := os.UserHomeDir()
 	require.NoError(t, err)
diff --git a/internal/harnesses/codex_test.go b/internal/harnesses/codex_test.go
index a8ea69b..750527a 100644
--- a/internal/harnesses/codex_test.go
+++ b/internal/harnesses/codex_test.go
@@ -122,81 +122,6 @@ func codexOverrides(t *testing.T, args []string) map[string]any {
 	return overrides
 }
 
-func TestCodexHarnessLaunchInjectsRequestyOverrides(t *testing.T) {
-	binaryPath := fakeBinary(t, "codex")
-	captured := captureExec(t)
-	cfg := config.Config{Name: "work", RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
-	harness := NewCodexHarness(cfg, t.TempDir())
-
-	err := harness.Launch(LaunchOptions{
-		Model:  "openai/gpt-5",
-		Effort: EffortXHigh,
-		Args:   []string{"--full-auto", "fix the tests"},
-		Env:    []string{"HOME=/home/me"},
-	})
-	require.NoError(t, err)
-
-	assert.Equal(t, binaryPath, captured.path)
-	assert.Equal(t, "codex", captured.argv[0])
-	assert.Equal(t, []string{"HOME=/home/me"}, captured.env, "the key travels through auth.command, not the environment")
-
-	overrides := codexOverrides(t, captured.argv)
-	assert.Equal(t, "requesty", overrides["model_provider"])
-	assert.Equal(t, "Requesty", overrides["model_providers.requesty.name"])
-	assert.Equal(t, "https://router.requesty.ai/v1", overrides["model_providers.requesty.base_url"])
-	assert.Equal(t, "OpenAI Codex", overrides["model_providers.requesty.http_headers.X-Title"])
-	assert.Equal(t, []any{"auth", "token", "--profile", "work"}, overrides["model_providers.requesty.auth.args"])
-	assert.Equal(t, false, overrides["model_supports_reasoning_summaries"])
-	assert.Equal(t, "xhigh", overrides["model_reasoning_effort"])
-
-	authCommand, _ := overrides["model_providers.requesty.auth.command"].(string)
-	executable, err := os.Executable()
-	require.NoError(t, err)
-	assert.Equal(t, executable, authCommand, "auth.command points at this very binary")
-
-	// Model, effort and then the user's own arguments come after the overrides, in order.
-	tail := captured.argv[len(captured.argv)-6:]
-	assert.Equal(t, []string{"-m", "openai/gpt-5", "-c", "model_reasoning_effort='xhigh'", "--full-auto", "fix the tests"}, tail)
-	assert.NotContains(t, strings.Join(captured.argv, " "), "my-api-key")
-}
-
-func TestCodexHarnessLaunchWithoutOverridesOmitsModelAndEffort(t *testing.T) {
-	fakeBinary(t, "codex")
-	captured := captureExec(t)
-	cfg := config.Config{Name: "work", RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
-	harness := NewCodexHarness(cfg, t.TempDir())
-
-	require.NoError(t, harness.Launch(LaunchOptions{Env: []string{}}))
-
-	assert.NotContains(t, captured.argv, "-m")
-	_, hasEffort := codexOverrides(t, captured.argv)["model_reasoning_effort"]
-	assert.False(t, hasEffort)
-}
-
-func TestCodexHarnessLaunchRejectsUnsupportedEffort(t *testing.T) {
-	fakeBinary(t, "codex")
-	captured := captureExec(t)
-	cfg := config.Config{Name: "work", RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
-	harness := NewCodexHarness(cfg, t.TempDir())
-
-	err := harness.Launch(LaunchOptions{Effort: EffortMax, Env: []string{}})
-
-	require.EqualError(t, err, `Codex does not support reasoning effort "max" (accepted: minimal, low, medium, high, xhigh)`)
-	assert.Empty(t, captured.path, "nothing should be launched")
-}
-
-func TestCodexHarnessLaunchRequiresBinary(t *testing.T) {
-	t.Setenv("PATH", t.TempDir())
-	captured := captureExec(t)
-	cfg := config.Config{Name: "work", RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
-	harness := NewCodexHarness(cfg, t.TempDir())
-
-	err := harness.Launch(LaunchOptions{Env: []string{}})
-
-	require.EqualError(t, err, "`codex` is not on PATH; install Codex (https://developers.openai.com/codex/cli) and try again")
-	assert.Empty(t, captured.path)
-}
-
 func TestTomlStringQuotesForCodexOverrides(t *testing.T) {
 	assert.Equal(t, `'plain'`, tomlString("plain"))
 	assert.Equal(t, `'/Users/me/My Tools/requesty'`, tomlString("/Users/me/My Tools/requesty"))
diff --git a/internal/harnesses/hermes.go b/internal/harnesses/hermes.go
index c57cada..8068fae 100644
--- a/internal/harnesses/hermes.go
+++ b/internal/harnesses/hermes.go
@@ -6,6 +6,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strings"
 
 	"github.com/requestyai/cli/internal/config"
 	"gopkg.in/yaml.v3"
@@ -42,8 +43,13 @@ type HermesHarness struct {
 	configDir string
 }
 
-// DefaultConfigDirHermes is where Hermes keeps its configuration.
+// DefaultConfigDirHermes is where Hermes keeps its configuration. Hermes
+// reads HERMES_HOME first, so an explicit home wins over the default one.
 func DefaultConfigDirHermes() (string, error) {
+	if home := os.Getenv("HERMES_HOME"); home != "" {
+		return home, nil
+	}
+
 	return configDirInHome(".hermes")
 }
 
@@ -68,8 +74,9 @@ func (h *HermesHarness) Description() []string {
 func (h *HermesHarness) Status() (Status, error) {
 	status := Status{}
 
-	if _, err := exec.LookPath("hermes"); err == nil {
+	if path, err := exec.LookPath("hermes"); err == nil {
 		status.Executable = true
+		status.ExecutablePath = path
 	} else if !errors.Is(err, exec.ErrNotFound) {
 		return status, fmt.Errorf("failed to find executable: %w", err)
 	}
@@ -112,8 +119,129 @@ func (h *HermesHarness) Status() (Status, error) {
 	return status, nil
 }
 
-func (h *HermesHarness) Launch(LaunchOptions) error {
-	return launchNotImplemented(h.Name())
+// hermesEfforts maps Launch effort levels onto Hermes's --reasoning values,
+// which take the level name as is.
+var hermesEfforts = map[string]string{
+	EffortMinimal: "minimal",
+	EffortLow:     "low",
+	EffortMedium:  "medium",
+	EffortHigh:    "high",
+	EffortXHigh:   "xhigh",
+	EffortMax:     "max",
+}
+
+// hermesProviderFlags, hermesModelFlags and hermesReasoningFlags are the
+// Hermes flags that, when the user passes them, mean we leave the
+// corresponding choice alone.
+var (
+	hermesProviderFlags  = []string{"--provider"}
+	hermesModelFlags     = []string{"-m", "--model"}
+	hermesReasoningFlags = []string{"--reasoning"}
+)
+
+// hermesLaunchEnv are the variables the launch sets; a ~/.hermes/.env that
+// redefines one of them wins over us, so they are what we check for.
+var hermesLaunchEnv = []string{"CUSTOM_BASE_URL", "REQUESTY_API_KEY"}
+
+// Launch replaces this process with Hermes pointed at Requesty. Hermes's
+// `custom` provider takes its endpoint from CUSTOM_BASE_URL and derives the
+// key variable from the endpoint's host, which for router.requesty.ai is
+// REQUESTY_API_KEY. The custom provider speaks OpenAI chat completions, so
+// the base URL keeps its /v1 suffix. Nothing is written to disk.
+func (h *HermesHarness) Launch(opts LaunchOptions) error {
+	status, err := h.Status()
+	if err != nil {
+		return fmt.Errorf("failed to check %s: %w", h.Name(), err)
+	}
+	if !status.Executable {
+		return fmt.Errorf("`hermes` is not on PATH; install Hermes (https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) and try again")
+	}
+
+	effort, err := mapEffort(h.Name(), hermesEfforts, opts.Effort)
+	if err != nil {
+		return err
+	}
+
+	env := parseEnvironmentVariables(opts.Env)
+	env["CUSTOM_BASE_URL"] = h.config.RouterBaseURL + "/v1"
+	env["REQUESTY_API_KEY"] = h.config.APIKey
+
+	if warning, conflict := h.credentialConflict(env); conflict {
+		_, _ = fmt.Fprintln(os.Stderr, warning)
+	}
+
+	argv := []string{"hermes"}
+	if !hasAnyFlag(opts.Args, hermesProviderFlags) {
+		argv = append(argv, "--provider", "custom")
+	}
+	if opts.Model != "" && !hasAnyFlag(opts.Args, hermesModelFlags) {
+		argv = append(argv, "-m", opts.Model)
+	}
+	if effort != "" && !hasAnyFlag(opts.Args, hermesReasoningFlags) {
+		argv = append(argv, "--reasoning", effort)
+	}
+	argv = append(argv, opts.Args...)
+
+	if err := execProcess(status.ExecutablePath, argv, formatEnvironmentVariables(env)); err != nil {
+		return fmt.Errorf("failed to launch hermes: %w", err)
+	}
+
+	return nil
+}
+
+// credentialConflict reports a value in Hermes's .env file that would
+// replace one of ours: Hermes loads that file over the process environment,
+// so a stale entry there sends requests elsewhere or with another key.
+func (h *HermesHarness) credentialConflict(env map[string]string) (string, bool) {
+	envPath := h.envPath()
+
+	data, err := os.ReadFile(envPath)
+	if err != nil {
+		return "", false
+	}
+
+	stored := parseDotEnv(string(data))
+	conflicting := make([]string, 0, len(hermesLaunchEnv))
+	for _, key := range hermesLaunchEnv {
+		if value, ok := stored[key]; ok && value != env[key] {
+			conflicting = append(conflicting, key)
+		}
+	}
+	if len(conflicting) == 0 {
+		return "", false
+	}
+
+	return fmt.Sprintf("Warning: %s in %s takes precedence over the values Requesty sets for this run. Remove or update it there if Hermes does not reach Requesty.", strings.Join(conflicting, " and "), envPath), true
+}
+
+// parseDotEnv reads KEY=value lines the way Hermes's dotenv loader does for
+// the cases that matter here: comments and blanks are skipped, `export` is
+// allowed, and matching quotes around the value are removed.
+func parseDotEnv(content string) map[string]string {
+	values := make(map[string]string)
+	for _, line := range strings.Split(content, "\n") {
+		line = strings.TrimSpace(line)
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		line = strings.TrimPrefix(line, "export ")
+
+		key, value, found := strings.Cut(line, "=")
+		if !found {
+			continue
+		}
+		key, value = strings.TrimSpace(key), strings.TrimSpace(value)
+		if len(value) >= 2 && (value[0] == '"' || value[0] == '\'') && value[len(value)-1] == value[0] {
+			value = value[1 : len(value)-1]
+		}
+		values[key] = value
+	}
+
+	return values
+}
+
+func (h *HermesHarness) envPath() string {
+	return filepath.Join(h.configDir, ".env")
 }
 
 func (h *HermesHarness) Configure(opts ConfigureOptions) error {
diff --git a/internal/harnesses/home.go b/internal/harnesses/home.go
index 5703b11..a026332 100644
--- a/internal/harnesses/home.go
+++ b/internal/harnesses/home.go
@@ -15,3 +15,10 @@ func configDirInHome(elements ...string) (string, error) {
 
 	return filepath.Join(append([]string{homePath}, elements...)...), nil
 }
+
+// requestyDirInHome joins elements onto our own ~/.requesty directory, where
+// a harness may keep files it needs at launch without touching the
+// harness's own configuration.
+func requestyDirInHome(elements ...string) (string, error) {
+	return configDirInHome(append([]string{".requesty"}, elements...)...)
+}
diff --git a/internal/harnesses/launch_test.go b/internal/harnesses/launch_test.go
deleted file mode 100644
index be802c2..0000000
--- a/internal/harnesses/launch_test.go
+++ /dev/null
@@ -1,93 +0,0 @@
-package harnesses
-
-import (
-	"os"
-	"path/filepath"
-	"runtime"
-	"testing"
-
-	"github.com/requestyai/cli/internal/config"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-// capturedLaunch is what a harness's Launch handed to execProcess.
-type capturedLaunch struct {
-	path string
-	argv []string
-	env  []string
-}
-
-// captureExec swaps the process replacement for a recorder for one test.
-func captureExec(t *testing.T) *capturedLaunch {
-	t.Helper()
-
-	captured := &capturedLaunch{}
-	previous := execProcess
-	execProcess = func(path string, argv []string, env []string) error {
-		captured.path, captured.argv, captured.env = path, argv, env
-		return nil
-	}
-	t.Cleanup(func() { execProcess = previous })
-
-	return captured
-}
-
-// fakeBinary drops an executable named name into a temp dir that leads PATH
-// and returns its path.
-func fakeBinary(t *testing.T, name string) string {
-	t.Helper()
-
-	dir := t.TempDir()
-	if runtime.GOOS == "windows" {
-		name += ".exe"
-	}
-	path := filepath.Join(dir, name)
-	require.NoError(t, os.WriteFile(path, []byte("#!/bin/sh\n"), 0o755))
-	t.Setenv("PATH", dir+string(os.PathListSeparator)+os.Getenv("PATH"))
-
-	return path
-}
-
-func TestUnsupportedHarnessesLaunchAsNoOp(t *testing.T) {
-	captured := captureExec(t)
-	cfg := config.Config{RouterBaseURL: "https://router.requesty.ai", APIKey: "my-api-key"}
-
-	for _, harness := range []Harness{
-		NewOpenCodeHarness(cfg, t.TempDir()),
-		NewPiHarness(cfg, t.TempDir()),
-		NewHermesHarness(cfg, t.TempDir()),
-		NewDeepSeekHarness(cfg, t.TempDir()),
-	} {
-		require.NoError(t, harness.Launch(LaunchOptions{}), harness.Name())
-	}
-	assert.Empty(t, captured.path, "nothing should be launched")
-}
-
-func TestMapEffortListsAcceptedLevelsInOrder(t *testing.T) {
-	_, err := mapEffort("Codex", codexEfforts, EffortMax)
-
-	require.EqualError(t, err, `Codex does not support reasoning effort "max" (accepted: minimal, low, medium, high, xhigh)`)
-}
-
-func TestMapEffortEmptyMeansHarnessDefault(t *testing.T) {
-	native, err := mapEffort("Codex", codexEfforts, "")
-
-	require.NoError(t, err)
-	assert.Empty(t, native)
-}
-
-func TestEnvironRoundTripsAndSorts(t *testing.T) {
-	env := parseEnvironmentVariables([]string{"C=3", "A=1", "B=2", "EQUALS=a=b"})
-	env["B"] = "two"
-	delete(env, "A")
-	env["D"] = "4"
-
-	assert.Equal(t, []string{"B=two", "C=3", "D=4", "EQUALS=a=b"}, formatEnvironmentVariables(env))
-}
-
-func TestParseEnvironNilMeansProcessEnvironment(t *testing.T) {
-	t.Setenv("REQUESTY_TEST_MARKER", "present")
-
-	assert.Equal(t, "present", parseEnvironmentVariables(nil)["REQUESTY_TEST_MARKER"])
-}
diff --git a/internal/harnesses/opencode.go b/internal/harnesses/opencode.go
index c48ecee..4e4acdb 100644
--- a/internal/harnesses/opencode.go
+++ b/internal/harnesses/opencode.go
@@ -1,12 +1,14 @@
 package harnesses
 
 import (
+	"bytes"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strings"
 
 	"github.com/requestyai/cli/internal/config"
 )
@@ -63,8 +65,9 @@ func (o *OpenCodeHarness) Description() []string {
 func (o *OpenCodeHarness) Status() (Status, error) {
 	status := Status{}
 
-	if _, err := exec.LookPath("opencode"); err == nil {
+	if path, err := exec.LookPath("opencode"); err == nil {
 		status.Executable = true
+		status.ExecutablePath = path
 	} else if !errors.Is(err, exec.ErrNotFound) {
 		return status, fmt.Errorf("failed to find executable: %w", err)
 	}
@@ -97,8 +100,156 @@ func (o *OpenCodeHarness) Status() (Status, error) {
 	return status, nil
 }
 
-func (o *OpenCodeHarness) Launch(LaunchOptions) error {
-	return launchNotImplemented(o.Name())
+// openCodeEfforts maps Launch effort levels onto OpenCode's --variant values,
+// which take the level name as is.
+var openCodeEfforts = map[string]string{
+	EffortMinimal: "minimal",
+	EffortLow:     "low",
+	EffortMedium:  "medium",
+	EffortHigh:    "high",
+	EffortXHigh:   "xhigh",
+	EffortMax:     "max",
+}
+
+// openCodeModelFlags and openCodeVariantFlags are the OpenCode flags that,
+// when the user passes them, mean we leave the corresponding choice alone.
+var (
+	openCodeModelFlags   = []string{"-m", "--model"}
+	openCodeVariantFlags = []string{"--variant"}
+)
+
+// Launch replaces this process with OpenCode pointed at Requesty. OpenCode
+// knows Requesty as a built-in provider that switches on when
+// REQUESTY_API_KEY is set; an inline OPENCODE_CONFIG_CONTENT document, which
+// outranks opencode.json for this run only, pins the base URL and key to
+// this profile. Nothing is written to disk.
+func (o *OpenCodeHarness) Launch(opts LaunchOptions) error {
+	status, err := o.Status()
+	if err != nil {
+		return fmt.Errorf("failed to check %s: %w", o.Name(), err)
+	}
+	if !status.Executable {
+		return fmt.Errorf("`opencode` is not on PATH; install OpenCode (https://opencode.ai/docs) and try again")
+	}
+
+	effort, err := mapEffort(o.Name(), openCodeEfforts, opts.Effort)
+	if err != nil {
+		return err
+	}
+
+	env := parseEnvironmentVariables(opts.Env)
+	env["REQUESTY_API_KEY"] = o.config.APIKey
+	content, err := o.inlineConfig(env["OPENCODE_CONFIG_CONTENT"], opts.Model)
+	if err != nil {
+		return err
+	}
+	env["OPENCODE_CONFIG_CONTENT"] = content
+
+	if warning, conflict := o.credentialConflict(env); conflict {
+		_, _ = fmt.Fprintln(os.Stderr, warning)
+	}
+
+	argv := []string{"opencode"}
+	if opts.Model != "" && !hasAnyFlag(opts.Args, openCodeModelFlags) {
+		argv = append(argv, "-m", o.modelID(opts.Model))
+	}
+	if effort != "" && !hasAnyFlag(opts.Args, openCodeVariantFlags) {
+		argv = append(argv, "--variant", effort)
+	}
+	argv = append(argv, opts.Args...)
+
+	if err := execProcess(status.ExecutablePath, argv, formatEnvironmentVariables(env)); err != nil {
+		return fmt.Errorf("failed to launch opencode: %w", err)
+	}
+
+	return nil
+}
+
+// inlineConfig is the OPENCODE_CONFIG_CONTENT document for this run: the
+// user's own, if they set one, with our provider merged in. The key is
+// referenced by environment variable so it stays out of the document itself.
+// The launched model is declared under the provider so ids OpenCode's
+// catalog does not list, such as managed policies, still resolve.
+func (o *OpenCodeHarness) inlineConfig(existing, model string) (string, error) {
+	settings := make(map[string]any)
+	if strings.TrimSpace(existing) != "" {
+		decoder := json.NewDecoder(bytes.NewReader([]byte(existing)))
+		decoder.UseNumber()
+		if err := decoder.Decode(&settings); err != nil {
+			return "", fmt.Errorf("OPENCODE_CONFIG_CONTENT is not valid JSON, so Requesty cannot add its provider to it; fix or unset it and try again: %w", err)
+		}
+	}
+
+	provider := map[string]any{
+		"options": map[string]any{
+			"baseURL": o.baseURL(),
+			"apiKey":  "{env:REQUESTY_API_KEY}",
+			"headers": map[string]any{
+				"X-Title": "OpenCode",
+			},
+		},
+	}
+	if model != "" {
+		provider["models"] = map[string]any{model: map[string]any{}}
+	}
+
+	if err := mergePatch(settings, map[string]any{"provider": map[string]any{openCodeProvider: provider}}, ""); err != nil {
+		return "", fmt.Errorf("OPENCODE_CONFIG_CONTENT cannot take a Requesty provider: %w", err)
+	}
+
+	data, err := json.Marshal(settings)
+	if err != nil {
+		return "", fmt.Errorf("failed to encode inline config: %w", err)
+	}
+
+	return string(data), nil
+}
+
+// credentialConflict reports a Requesty key stored by `opencode auth login`
+// that differs from this profile's, since a stored credential can win over
+// the one we inject and then fail authentication.
+func (o *OpenCodeHarness) credentialConflict(env map[string]string) (string, bool) {
+	authPath := openCodeAuthPath(env)
+	if authPath == "" {
+		return "", false
+	}
+
+	data, err := os.ReadFile(authPath)
+	if err != nil {
+		return "", false
+	}
+
+	var auth map[string]struct {
+		Key string `json:"key"`
+	}
+	if err := json.Unmarshal(data, &auth); err != nil {
+		return "", false
+	}
+
+	stored, ok := auth[openCodeProvider]
+	if !ok || stored.Key == "" || stored.Key == o.config.APIKey {
+		return "", false
+	}
+
+	return fmt.Sprintf("Warning: OpenCode has a Requesty credential stored at %s that differs from this profile's key. If requests fail to authenticate, remove it with `opencode auth logout` and try again.", authPath), true
+}
+
+// openCodeAuthPath is where `opencode auth login` keeps credentials:
+// $XDG_DATA_HOME/opencode/auth.json, defaulting to ~/.local/share.
+func openCodeAuthPath(env map[string]string) string {
+	dataHome := strings.TrimSpace(env["XDG_DATA_HOME"])
+	if dataHome == "" {
+		home := env["HOME"]
+		if home == "" {
+			var err error
+			if home, err = os.UserHomeDir(); err != nil {
+				return ""
+			}
+		}
+		dataHome = filepath.Join(home, ".local", "share")
+	}
+
+	return filepath.Join(dataHome, "opencode", "auth.json")
 }
 
 func (o *OpenCodeHarness) Configure(opts ConfigureOptions) error {
diff --git a/internal/harnesses/pi.go b/internal/harnesses/pi.go
index 8fa67f9..c0874e7 100644
--- a/internal/harnesses/pi.go
+++ b/internal/harnesses/pi.go
@@ -1,13 +1,19 @@
 package harnesses
 
 import (
+	"context"
+	_ "embed"
 	"encoding/json"
 	"errors"
 	"fmt"
 	"os"
 	"os/exec"
 	"path/filepath"
+	"slices"
+	"strings"
+	"time"
 
+	"github.com/requestyai/cli/internal/client"
 	"github.com/requestyai/cli/internal/config"
 )
 
@@ -74,8 +80,9 @@ func (p *PiHarness) Description() []string {
 func (p *PiHarness) Status() (Status, error) {
 	status := Status{}
 
-	if _, err := exec.LookPath("pi"); err == nil {
+	if path, err := exec.LookPath("pi"); err == nil {
 		status.Executable = true
+		status.ExecutablePath = path
 	} else if !errors.Is(err, exec.ErrNotFound) {
 		return status, fmt.Errorf("failed to find executable: %w", err)
 	}
@@ -125,8 +132,272 @@ func (p *PiHarness) Status() (Status, error) {
 	return status, nil
 }
 
-func (p *PiHarness) Launch(LaunchOptions) error {
-	return launchNotImplemented(p.Name())
+// piExtension registers Requesty as a Pi provider for one run. It is written
+// out before every launch so an upgraded CLI always ships its current copy.
+//
+//go:embed pi/requesty.ts
+var piExtension []byte
+
+const (
+	piExtensionFile = "requesty.ts"
+	piCatalogFile   = "catalog.json"
+
+	// piCatalogTimeout bounds the model list refresh so a slow network
+	// cannot hold up the launch for long.
+	piCatalogTimeout = 5 * time.Second
+
+	// piCatalogContextWindow and piCatalogMaxTokens stand in when the model
+	// list does not say.
+	piCatalogContextWindow = 200_000
+	piCatalogMaxTokens     = 8_192
+)
+
+// piCatalog is what the extension reads: the models the profile can route
+// to, in the shape of Pi's ProviderModelConfig.
+type piCatalog struct {
+	Models []piCatalogModel `json:"models"`
+}
+
+type piCatalogModel struct {
+	ID            string        `json:"id"`
+	Name          string        `json:"name"`
+	Reasoning     bool          `json:"reasoning"`
+	Input         []string      `json:"input"`
+	Cost          piCatalogCost `json:"cost"`
+	ContextWindow int           `json:"contextWindow"`
+	MaxTokens     int           `json:"maxTokens"`
+}
+
+// piCatalogCost is in dollars per million tokens, as Pi expects.
+type piCatalogCost struct {
+	Input      float64 `json:"input"`
+	Output     float64 `json:"output"`
+	CacheRead  float64 `json:"cacheRead"`
+	CacheWrite float64 `json:"cacheWrite"`
+}
+
+// piEfforts maps Launch effort levels onto Pi's --thinking values, which
+// take the level name as is.
+var piEfforts = map[string]string{
+	EffortMinimal: "minimal",
+	EffortLow:     "low",
+	EffortMedium:  "medium",
+	EffortHigh:    "high",
+	EffortXHigh:   "xhigh",
+	EffortMax:     "max",
+}
+
+// piProviderFlags, piModelFlags and piThinkingFlags are the Pi flags that,
+// when the user passes them, mean we leave the corresponding choice alone.
+var (
+	piProviderFlags = []string{"--provider"}
+	piModelFlags    = []string{"--model"}
+	piThinkingFlags = []string{"--thinking"}
+)
+
+// piNeutralizedEnv are the credentials Pi reads for its built-in providers.
+// They are dropped from the launched process so every model Pi offers goes
+// through Requesty rather than straight to a vendor.
+var piNeutralizedEnv = []string{
+	"AI_GATEWAY_API_KEY",
+	"ANT_LING_API_KEY",
+	"ANTHROPIC_API_KEY",
+	"ANTHROPIC_AUTH_TOKEN",
+	"ANTHROPIC_OAUTH_TOKEN",
+	"AWS_BEARER_TOKEN_BEDROCK",
+	"AZURE_OPENAI_API_KEY",
+	"BASETEN_API_KEY",
+	"CEREBRAS_API_KEY",
+	"CLOUDFLARE_API_KEY",
+	"DEEPSEEK_API_KEY",
+	"FIREWORKS_API_KEY",
+	"GEMINI_API_KEY",
+	"GROQ_API_KEY",
+	"KIMI_API_KEY",
+	"MINIMAX_API_KEY",
+	"MISTRAL_API_KEY",
+	"MOONSHOT_API_KEY",
+	"NVIDIA_API_KEY",
+	"OPENAI_API_KEY",
+	"OPENCODE_API_KEY",
+	"OPENROUTER_API_KEY",
+	"QWEN_TOKEN_PLAN_API_KEY",
+	"QWEN_TOKEN_PLAN_CN_API_KEY",
+	"TOGETHER_API_KEY",
+	"XAI_API_KEY",
+	"XIAOMI_API_KEY",
+	"XIAOMI_TOKEN_PLAN_AMS_API_KEY",
+	"XIAOMI_TOKEN_PLAN_CN_API_KEY",
+	"XIAOMI_TOKEN_PLAN_SGP_API_KEY",
+	"ZAI_API_KEY",
+	"ZAI_CODING_CN_API_KEY",
+}
+
+// DefaultLaunchDirPi is where `requesty pi` keeps the extension and model
+// catalog it hands to Pi: under our own directory, not Pi's.
+func DefaultLaunchDirPi() (string, error) {
+	return requestyDirInHome("pi")
+}
+
+// Launch replaces this process with Pi pointed at Requesty. Pi has no flag
+// or variable for a custom provider, so a small extension of ours, loaded
+// with --extension, registers Requesty with the models the profile can use.
+// The extension and its model catalog live under ~/.requesty/pi; Pi's own
+// configuration is not touched.
+func (p *PiHarness) Launch(opts LaunchOptions) error {
+	status, err := p.Status()
+	if err != nil {
+		return fmt.Errorf("failed to check %s: %w", p.Name(), err)
+	}
+	if !status.Executable {
+		return fmt.Errorf("`pi` is not on PATH; install Pi (https://pi.dev) and try again")
+	}
+
+	effort, err := mapEffort(p.Name(), piEfforts, opts.Effort)
+	if err != nil {
+		return err
+	}
+
+	launchDir, err := DefaultLaunchDirPi()
+	if err != nil {
+		return fmt.Errorf("failed to find launch directory: %w", err)
+	}
+	extensionPath := filepath.Join(launchDir, piExtensionFile)
+	catalogPath := filepath.Join(launchDir, piCatalogFile)
+
+	if err := writeFile(extensionPath, piExtension, 0o600); err != nil {
+		return fmt.Errorf("failed to write Pi extension: %w", err)
+	}
+	if err := p.writeCatalog(catalogPath, opts.Model); err != nil {
+		return fmt.Errorf("failed to write Pi model catalog: %w", err)
+	}
+
+	env := parseEnvironmentVariables(opts.Env)
+	for _, key := range piNeutralizedEnv {
+		delete(env, key)
+	}
+	env["REQUESTY_API_KEY"] = p.config.APIKey
+	env["REQUESTY_BASE_URL"] = p.config.RouterBaseURL
+	env["REQUESTY_PI_CATALOG"] = catalogPath
+
+	argv := []string{"pi", "--extension", extensionPath}
+	switch {
+	case hasAnyFlag(opts.Args, piModelFlags), hasAnyFlag(opts.Args, piProviderFlags):
+		// The user has chosen for themselves.
+	case opts.Model != "":
+		argv = append(argv, "--model", piProvider+"/"+opts.Model)
+	default:
+		argv = append(argv, "--provider", piProvider)
+	}
+	if effort != "" && !hasAnyFlag(opts.Args, piThinkingFlags) {
+		argv = append(argv, "--thinking", effort)
+	}
+	argv = append(argv, opts.Args...)
+
+	if err := execProcess(status.ExecutablePath, argv, formatEnvironmentVariables(env)); err != nil {
+		return fmt.Errorf("failed to launch pi: %w", err)
+	}
+
+	return nil
+}
+
+// writeCatalog refreshes the model catalog from the profile's account. When
+// that fails, such as offline, the previous catalog is kept. Either way the
+// launched model is listed, since Pi only accepts models it knows about.
+func (p *PiHarness) writeCatalog(path, model string) error {
+	ctx, cancel := context.WithTimeout(context.Background(), piCatalogTimeout)
+	defer cancel()
+
+	catalog, err := p.fetchCatalog(ctx)
+	if err != nil {
+		_, _ = fmt.Fprintf(os.Stderr, "Warning: could not refresh the Requesty model list for Pi (%v); using the previous list.\n", err)
+		catalog = readPiCatalog(path)
+	}
+
+	if model != "" && !slices.ContainsFunc(catalog.Models, func(m piCatalogModel) bool { return m.ID == model }) {
+		catalog.Models = append(catalog.Models, piCatalogModel{
+			ID:            model,
+			Name:          model,
+			Reasoning:     true,
+			Input:         []string{"text", "image"},
+			ContextWindow: piCatalogContextWindow,
+			MaxTokens:     piCatalogMaxTokens,
+		})
+	}
+
+	data, err := json.MarshalIndent(catalog, "", "  ")
+	if err != nil {
+		return fmt.Errorf("failed to encode catalog: %w", err)
+	}
+
+	return writeFile(path, data, 0o600)
+}
+
+// fetchCatalog lists the profile's models and managed policies. Policies
+// are optional: an account without any still gets its models.
+func (p *PiHarness) fetchCatalog(ctx context.Context) (piCatalog, error) {
+	apiClient := client.New(p.config)
+
+	models, err := apiClient.Models(ctx)
+	if err != nil {
+		return piCatalog{}, err
+	}
+	policies, _ := apiClient.ManagedPolicies(ctx)
+
+	listed := slices.Concat(policies, models)
+	slices.SortFunc(listed, func(a, b client.Model) int { return strings.Compare(a.ID, b.ID) })
+
+	catalog := piCatalog{Models: make([]piCatalogModel, 0, len(listed))}
+	for _, model := range listed {
+		if model.ID == "" || slices.ContainsFunc(catalog.Models, func(m piCatalogModel) bool { return m.ID == model.ID }) {
+			continue
+		}
+		catalog.Models = append(catalog.Models, piCatalogModelFrom(model))
+	}
+
+	return catalog, nil
+}
+
+// piCatalogModelFrom describes a Requesty model to Pi. Prices arrive per
+// token and leave per million; capacities the list omits get defaults.
+func piCatalogModelFrom(model client.Model) piCatalogModel {
+	entry := piCatalogModel{
+		ID:        model.ID,
+		Name:      model.ID,
+		Reasoning: true,
+		Input:     []string{"text", "image"},
+		Cost: piCatalogCost{
+			Input:      model.InputPrice * 1_000_000,
+			Output:     model.OutputPrice * 1_000_000,
+			CacheRead:  model.CacheReadPrice * 1_000_000,
+			CacheWrite: model.CacheWritePrice * 1_000_000,
+		},
+		ContextWindow: model.ContextWindow,
+		MaxTokens:     model.MaxOutputTokens,
+	}
+	if entry.ContextWindow <= 0 {
+		entry.ContextWindow = piCatalogContextWindow
+	}
+	if entry.MaxTokens <= 0 {
+		entry.MaxTokens = piCatalogMaxTokens
+	}
+
+	return entry
+}
+
+// readPiCatalog returns the catalog at path, or an empty one when there is
+// none or it cannot be read.
+func readPiCatalog(path string) piCatalog {
+	var catalog piCatalog
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return catalog
+	}
+	if err := json.Unmarshal(data, &catalog); err != nil {
+		return piCatalog{}
+	}
+
+	return catalog
 }
 
 func (p *PiHarness) Configure(opts ConfigureOptions) error {
diff --git a/internal/harnesses/pi/requesty.ts b/internal/harnesses/pi/requesty.ts
new file mode 100644
index 0000000..984003a
--- /dev/null
+++ b/internal/harnesses/pi/requesty.ts
@@ -0,0 +1,53 @@
+// Requesty provider for Pi. Written by `requesty pi` before every launch and
+// loaded with `--extension`, so nothing in Pi's own configuration changes.
+//
+// The launch passes everything through the environment:
+//   REQUESTY_API_KEY     the key for this profile
+//   REQUESTY_BASE_URL    the router, without a /v1 suffix
+//   REQUESTY_PI_CATALOG  a JSON file listing the models the profile can use
+import { readFileSync } from "node:fs";
+import type { ExtensionAPI, ProviderModelConfig } from "@earendil-works/pi-coding-agent";
+
+const PROVIDER = "requesty";
+const DEFAULT_BASE_URL = "https://router.requesty.ai";
+
+// The native Anthropic Messages format lets Requesty apply automatic prompt
+// caching; it takes the router's base URL without /v1.
+const API = "anthropic-messages";
+
+const trimmed = (value: string | undefined): string | undefined => {
+	const text = value?.trim();
+	return text === undefined || text === "" ? undefined : text;
+};
+
+const loadCatalog = (path: string | undefined): ProviderModelConfig[] => {
+	if (path === undefined) {
+		return [];
+	}
+	const parsed: unknown = JSON.parse(readFileSync(path, "utf8"));
+	const models = (parsed as { models?: unknown }).models;
+	return Array.isArray(models) ? (models as ProviderModelConfig[]) : [];
+};
+
+export default function (pi: ExtensionAPI): void {
+	if (typeof pi.registerProvider !== "function") {
+		throw new Error("Requesty needs pi 0.84.0 or newer; upgrade pi and try again.");
+	}
+
+	const apiKey = trimmed(process.env.REQUESTY_API_KEY);
+	if (apiKey === undefined) {
+		throw new Error("REQUESTY_API_KEY is not set; start Pi with `requesty pi`.");
+	}
+
+	pi.registerProvider(PROVIDER, {
+		name: "Requesty",
+		baseUrl: trimmed(process.env.REQUESTY_BASE_URL) ?? DEFAULT_BASE_URL,
+		api: API,
+		apiKey,
+		headers: {
+			"HTTP-Referer": "https://pi.dev",
+			"X-Title": "Pi",
+		},
+		models: loadCatalog(trimmed(process.env.REQUESTY_PI_CATALOG)),
+	});
+}

From cdf61a9ae8114bbdb94c34723d2ba74719a86b57 Mon Sep 17 00:00:00 2001
From: fayzan <fayzan@requesty.ai>
Date: Thu, 24 Sep 2026 11:29:28 +0100
Subject: [PATCH 8/9] Remove requesty reasoning efforts

---
 README.md                         |  46 +++++-----
 cmd/auth.go                       |   4 +-
 cmd/environment.go                |  77 +++++++++--------
 cmd/harness.go                    |  37 +++-----
 cmd/harness_test.go               |  46 ++++------
 cmd/login.go                      |  18 ++--
 cmd/profiles.go                   |  17 +---
 cmd/requesty.go                   |   4 +-
 cmd/requesty_test.go              |  11 ---
 internal/config/config.go         |  55 ++++++++++--
 internal/config/config_test.go    |  12 ---
 internal/harnesses/claude.go      |  17 ----
 internal/harnesses/codex.go       |  17 ----
 internal/harnesses/harnesses.go   |  10 +--
 internal/harnesses/hermes.go      |  29 +------
 internal/harnesses/launch.go      |  37 --------
 internal/harnesses/opencode.go    |  28 +-----
 internal/harnesses/pi.go          |  24 +-----
 internal/onboarding/model.go      | 138 ++++++++++++++----------------
 internal/onboarding/model_test.go |  65 ++++++++------
 internal/onboarding/run.go        |   8 +-
 21 files changed, 275 insertions(+), 425 deletions(-)

diff --git a/README.md b/README.md
index afa4cc8..dbd75ef 100644
--- a/README.md
+++ b/README.md
@@ -46,33 +46,34 @@ a new terminal, or run the `source` command it prints, then run `requesty`.
 **Sign in with your browser**
 
 The first time you run `requesty` or a harness command such as `requesty claude` on a machine without a profile,
-the CLI opens with a welcome page that says what is about to happen. Press enter and it signs you in
-to Requesty in your browser; once you approve, it creates an API key in your account, named after
-this machine (`Requesty CLI (my-laptop)`), and saves it as a [profile](#profiles) in
-`~/.requesty/config.json`. The app then carries on to its dashboard, or the harness you asked for
-starts. Every later run reuses that profile. The key shows up on the
+the CLI opens your browser to sign in to Requesty straight away; once you approve, it creates an
+API key in your account, named after this machine (`Requesty CLI (my-laptop)`), and saves it as a
+[profile](#profiles) in `~/.requesty/config.json`. The app then carries on to its dashboard, or
+the harness you asked for starts. Every later run reuses that profile. The key shows up on the
 [API keys page](https://app.requesty.ai/api-keys) like any other, and can be revoked there.
 
 ```text
 ╭──────────────────────────────────────────────────────────────────╮
 │ Welcome to Requesty                                              │
+│                                                                  │
 │ One gateway for every model, in every tool you use, or app you   │
 │ build.                                                           │
 │                                                                  │
-│ Sign in with your browser to get started. This creates an API    │
-│ key named "Requesty CLI (my-laptop)" in your Requesty account    │
-│ and saves it to /home/you/.requesty/config.json.                 │
+│ Waiting for you to finish signing in with your browser…          │
+│                                                                  │
+│ If it did not open, visit this address:                          │
+│ https://app.requesty.ai/oauth/authorize?...                      │
+│                                                                  │
 │ Claude Code starts as soon as the key is saved.                  │
 │                                                                  │
 │ Working over SSH, or already have a key? Quit and run `requesty  │
 │ login --api-key <key>` instead.                                  │
 │                                                                  │
-│ enter sign in · q/esc quit                                   dev │
+│ esc quit                                                         │
 ╰──────────────────────────────────────────────────────────────────╯
 ```
 
-While the browser is open a dialog shows the sign-in address, for when the browser did not open on
-its own; `esc` cancels. The key is created in your group. If you belong to several groups a dialog
+`esc` quits; run the command again to retry. The key is created in your group. If you belong to several groups a dialog
 asks which one; if you belong to none it is a personal key. Organizations that require keys to live
 in a group will say so, in which case ask an admin to add you to one. The profile is named
 `default`; pass `--profile <name>` to choose another name.
@@ -119,14 +120,15 @@ requesty claude --profile eu                       # a named profile, with its o
 requesty claude --model anthropic/claude-opus-4-1  # this model, just for this run
 requesty claude --choose-model                     # pick again and remember the new answer
 requesty claude --choose-fast-model                # pick what background work runs on
-requesty codex --reasoning-effort high -- --full-auto
-requesty opencode --model gpt-5.5 -- run "explain this repo"
-requesty pi --reasoning-effort medium
-requesty hermes -- chat -q "hello"
+requesty codex --full-auto                         # everything else goes to the harness untouched
+requesty claude --effort high                      # so its own flags work as usual
+requesty opencode --model gpt-5.5 run "explain this repo"
+requesty pi --thinking off
+requesty hermes chat -q "hello"
 ```
 
-Profile precedence is `--profile <name>`, then `REQUESTY_PROFILE`, then the current profile set
-with `requesty profiles use`. For a harness command, put `--profile` after the harness name and
+`--profile <name>` picks the profile for a run; without it, the current profile set with
+`requesty profiles use` is used. For a harness command, put `--profile` after the harness name and
 before the first argument that is passed through to the harness.
 
 Each harness is pointed at Requesty in the way it allows without touching its files:
@@ -147,9 +149,10 @@ Each harness is pointed at Requesty in the way it allows without touching its fi
   Hermes loads `~/.hermes/.env` over the environment, so the CLI warns when a value there would
   replace one of its own.
 
-Reasoning effort (`--reasoning-effort minimal|low|medium|high|xhigh|max`) maps onto each harness's
-own flag; levels a harness does not support are rejected before it starts. Flags you pass through
-for the model, provider or effort take precedence over the CLI's.
+Anything the harness itself can be told, such as reasoning effort, is left to the harness's own
+flags: `claude --effort high`, `codex -c model_reasoning_effort=high`, `opencode --variant high`,
+`pi --thinking high`, `hermes --reasoning high`. A model or provider flag you pass through takes
+precedence over the CLI's.
 
 ## Profiles
 
@@ -167,8 +170,7 @@ requesty profiles remove personal                       # forget a profile (the
 ```
 
 `requesty login` creates the `default` profile unless you pass `--profile`. The first profile
-becomes current. Every command accepts `--profile <name>`, and `REQUESTY_PROFILE` does the same
-for a whole shell.
+becomes current. Every command accepts `--profile <name>`.
 
 Harnesses configured from the dashboard stay pinned to the profile used during configuration.
 Claude Code stores that profile's key in its settings. Codex fetches the key through
diff --git a/cmd/auth.go b/cmd/auth.go
index 4dc2c88..0f4ab32 100644
--- a/cmd/auth.go
+++ b/cmd/auth.go
@@ -18,8 +18,8 @@ func newAuthCommand(env *environment) *cobra.Command {
 	auth.AddCommand(&cobra.Command{
 		Use:   "token",
 		Short: "Print the Requesty API key of the profile in use",
-		Long: "Print the API key of the profile named with --" + profileFlag + " or " + profileEnv + ", else the\n" +
-			"current one. Harnesses that fetch their key on demand, such as Codex, call this.",
+		Long: "Print the API key of the profile named with --" + profileFlag + ", else the current one.\n" +
+			"Harnesses that fetch their key on demand, such as Codex, call this.",
 		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			if _, err := fmt.Fprintln(cmd.OutOrStdout(), env.session.config.APIKey); err != nil {
diff --git a/cmd/environment.go b/cmd/environment.go
index a796742..87a08ab 100644
--- a/cmd/environment.go
+++ b/cmd/environment.go
@@ -16,8 +16,6 @@ const (
 	// profileFlag names the saved profile to run with. It lives on the root
 	// so every subcommand inherits it; harness commands parse it themselves.
 	profileFlag = "profile"
-	// profileEnv is the environment variable that stands in for --profile.
-	profileEnv = "REQUESTY_PROFILE"
 	// defaultProfileName is what onboarding calls the first profile.
 	defaultProfileName = "default"
 )
@@ -29,6 +27,8 @@ type environment struct {
 	session *session
 }
 
+// session is the resolved profile and the client built from it, set once the
+// profile for a command has been picked.
 type session struct {
 	config config.Config
 	client *client.Client
@@ -63,7 +63,7 @@ func (env *environment) requireProfile(cmd *cobra.Command, _ []string) error {
 // resolveProfile returns the profile selected for this command.
 func (env *environment) resolveProfile(cmd *cobra.Command, name string) (config.Config, error) {
 	if name == "" {
-		name = requestedProfile(cmd)
+		name, _ = cmd.Flags().GetString(profileFlag)
 	}
 
 	return env.store.Resolve(name)
@@ -93,25 +93,25 @@ func (env *environment) ensureProfile(cmd *cobra.Command, name, harness string)
 }
 
 // ensureModels returns the model the harness launches with and, for
-// harnesses that have one, the model its background work goes to. Whatever
-// the picker decides is saved in the profile.
+// harnesses that have one, the model its background work goes to.
 func (env *environment) ensureModels(cmd *cobra.Command, cfg config.Config, spec harnessSpec, parsed harnessArgs) (model, fast string, err error) {
 	model, pickedModel, err := env.ensureModel(cmd, cfg, modelRequest{
-		what:       spec.displayName,
-		flag:       harnessModelFlag,
-		chooseFlag: harnessChooseModelFlag,
-		flagged:    parsed.launch.Model,
-		choose:     parsed.chooseModel,
-		saved:      cfg.HarnessModels[spec.binary],
-		defaults:   spec.defaultModels,
+		displayName:  spec.displayName,
+		override:     parsed.launch.Model,
+		overrideFlag: harnessModelFlag,
+		ask:          parsed.chooseModel,
+		askFlag:      harnessChooseModelFlag,
+		saved:        cfg.HarnessModels[spec.binary],
+		defaults:     spec.defaultModels,
 	})
 	if err != nil {
 		return "", "", err
 	}
 	if pickedModel {
-		// This also forgets the fast model, so it is picked again below to
-		// go with the new main model.
 		cfg.SetHarnessModel(spec.binary, model)
+		// A new main model may sit in another region, so the fast model is
+		// forgotten and picked again below to go with it.
+		delete(cfg.HarnessFastModels, spec.binary)
 	}
 
 	pickedFast := false
@@ -119,13 +119,13 @@ func (env *environment) ensureModels(cmd *cobra.Command, cfg config.Config, spec
 		// The main model is the last resort: it is known to be permitted,
 		// so an access list without any smaller model still works.
 		fast, pickedFast, err = env.ensureModel(cmd, cfg, modelRequest{
-			what:       spec.displayName + " background work",
-			flag:       harnessFastModelFlag,
-			chooseFlag: harnessChooseFastModelFlag,
-			flagged:    parsed.launch.FastModel,
-			choose:     parsed.chooseFastModel,
-			saved:      cfg.HarnessFastModels[spec.binary],
-			defaults:   slices.Concat(spec.defaultFastModels, []string{model}),
+			displayName:  spec.displayName + " background work",
+			override:     parsed.launch.FastModel,
+			overrideFlag: harnessFastModelFlag,
+			ask:          parsed.chooseFastModel,
+			askFlag:      harnessChooseFastModelFlag,
+			saved:        cfg.HarnessFastModels[spec.binary],
+			defaults:     slices.Concat(spec.defaultFastModels, []string{model}),
 		})
 		if err != nil {
 			return "", "", err
@@ -146,16 +146,17 @@ func (env *environment) ensureModels(cmd *cobra.Command, cfg config.Config, spec
 
 // modelRequest is how one of a harness's models was asked for on this run.
 type modelRequest struct {
-	// what is shown in the picker title and in messages: "Claude Code",
+	// displayName is shown in the picker title and in messages: "Claude Code",
 	// "Claude Code background work".
-	what string
-	// flag is the one to pass instead when there is no terminal to ask in;
-	// chooseFlag is the one that opens the picker again later.
-	flag, chooseFlag string
-	// flagged is the value of flag, for this run only.
-	flagged string
-	// choose says chooseFlag was passed: open the picker even if saved.
-	choose bool
+	displayName string
+	// override is the model for this run only, from overrideFlag.
+	override string
+	// overrideFlag is "--model" or "--fast-model", for messages.
+	overrideFlag string
+	// ask says askFlag was passed: open the picker even if saved.
+	ask bool
+	// askFlag is "--choose-model" or "--choose-fast-model", for messages.
+	askFlag string
 	// saved is what the profile remembers, if anything.
 	saved string
 	// defaults are tried in order when nothing is saved; the first one the
@@ -163,14 +164,14 @@ type modelRequest struct {
 	defaults []string
 }
 
-// ensureModel returns the model for one request: the flag for this run
+// ensureModel returns the model for one request: the override for this run
 // only, else the saved one, else whatever the picker decides, which it
 // reports through picked so the caller knows to save it.
 func (env *environment) ensureModel(cmd *cobra.Command, cfg config.Config, req modelRequest) (model string, picked bool, err error) {
 	switch {
-	case req.flagged != "":
-		return req.flagged, false, nil
-	case req.saved != "" && !req.choose:
+	case req.override != "":
+		return req.override, false, nil
+	case req.saved != "" && !req.ask:
 		return req.saved, false, nil
 	}
 
@@ -180,19 +181,19 @@ func (env *environment) ensureModel(cmd *cobra.Command, cfg config.Config, req m
 	}
 	model, asked, err := modelpicker.Run(cmd.Context(), modelpicker.Options{
 		Client:    client.New(cfg),
-		Harness:   req.what,
+		Harness:   req.displayName,
 		Preferred: preferred,
-		Confirm:   req.choose,
+		Confirm:   req.ask,
 	})
 	if errors.Is(err, modelpicker.ErrCancelled) {
 		return "", false, err
 	}
 	if err != nil {
 		// Most often there is no terminal to ask in, such as a script or CI.
-		return "", false, fmt.Errorf("no model picked for %s in profile %q; pass %s <id> or run in a terminal once (%w)", req.what, cfg.Name, req.flag, err)
+		return "", false, fmt.Errorf("no model picked for %s in profile %q; pass %s <id> or run in a terminal once (%w)", req.displayName, cfg.Name, req.overrideFlag, err)
 	}
 	if !asked {
-		if _, err := fmt.Fprintf(cmd.ErrOrStderr(), "Using %s for %s; change with %s.\n", model, req.what, req.chooseFlag); err != nil {
+		if _, err := fmt.Fprintf(cmd.ErrOrStderr(), "Using %s for %s; change with %s.\n", model, req.displayName, req.askFlag); err != nil {
 			return "", false, err
 		}
 	}
diff --git a/cmd/harness.go b/cmd/harness.go
index 25ef251..a143922 100644
--- a/cmd/harness.go
+++ b/cmd/harness.go
@@ -17,12 +17,11 @@ const (
 	harnessChooseModelFlag     = "--choose-model"
 	harnessFastModelFlag       = "--fast-model"
 	harnessChooseFastModelFlag = "--choose-fast-model"
-	harnessEffortFlag          = "--reasoning-effort"
 )
 
 // harnessValueFlags are our flags that take a value, as `--flag v` or
 // `--flag=v`.
-var harnessValueFlags = []string{harnessProfileFlag, harnessModelFlag, harnessFastModelFlag, harnessEffortFlag}
+var harnessValueFlags = []string{harnessProfileFlag, harnessModelFlag, harnessFastModelFlag}
 
 // errHarnessHelp signals that the leading flags asked for help.
 var errHarnessHelp = errors.New("help requested")
@@ -118,9 +117,7 @@ func newHarnessCommands(env *environment) []*cobra.Command {
 }
 
 // newHarnessCommand builds `requesty <binary>`. The harness is constructed
-// lazily, from the profile as it stands after any onboarding, so a machine
-// without a resolvable home directory still gets a help page and a clear
-// error, rather than a missing command.
+// lazily, from the profile as it stands after any onboarding.
 func newHarnessCommand(env *environment, spec harnessSpec) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   harnessUse(spec),
@@ -168,42 +165,37 @@ func harnessUse(spec harnessSpec) string {
 		use += fmt.Sprintf(" [%s <id> | %s]", harnessFastModelFlag, harnessChooseFastModelFlag)
 	}
 
-	return use + fmt.Sprintf(" [%s <level>] [-- ] [%s args...]", harnessEffortFlag, spec.binary)
+	return use + fmt.Sprintf(" [-- ] [%s args...]", spec.binary)
 }
 
 // harnessLong is the help page of `requesty <binary>`.
 func harnessLong(spec harnessSpec) string {
 	flags := [][2]string{
-		{harnessProfileFlag + " <name>", "Saved profile to run as (also " + profileEnv + ")"},
+		{harnessProfileFlag + " <name>", "Saved profile to run as"},
 		{harnessModelFlag + " <id>", "Model for this run only (a managed policy or any Requesty model id)"},
-		{harnessChooseModelFlag, "Pick the model to launch with from now on"},
+		{harnessChooseModelFlag, "Pick the model again and remember it"},
 	}
 	if spec.hasFastModel() {
 		flags = append(flags,
 			[2]string{harnessFastModelFlag + " <id>", "Model for background work, this run only"},
-			[2]string{harnessChooseFastModelFlag, "Pick the model for background work from now on"},
+			[2]string{harnessChooseFastModelFlag, "Pick the background model again and remember it"},
 		)
 	}
-	flags = append(flags,
-		[2]string{harnessEffortFlag + " <level>", "Reasoning effort: " + strings.Join(harnesses.Efforts, ", ")},
-		[2]string{"-h, --help", "Show this help"},
-	)
+	flags = append(flags, [2]string{"-h, --help", "Show this help"})
 
 	var b strings.Builder
-	fmt.Fprintf(&b, "Launch %s with its traffic routed through Requesty for this run only.\n\n", spec.displayName)
+	fmt.Fprintf(&b, "Launch %s through Requesty for this run; its own configuration is not changed.\n\n", spec.displayName)
 	b.WriteString("Flags:\n")
 	for _, flag := range flags {
 		fmt.Fprintf(&b, "  %-28s %s\n", flag[0], flag[1])
 	}
 	fmt.Fprintf(&b, "\nAnything else, or everything after `--`, is passed to `%s` untouched.\n\n", spec.binary)
-	fmt.Fprintf(&b, "Without %s, the model remembered for this harness in the profile is used. The first\n", harnessModelFlag)
-	fmt.Fprintf(&b, "time, %s is used when the profile can route to it, else a picker asks; either way\n", spec.defaultModels[0])
-	fmt.Fprintf(&b, "the answer is remembered and %s picks again.\n\n", harnessChooseModelFlag)
+	fmt.Fprintf(&b, "The first launch settles the model: %s is used when the profile can route to it,\n", spec.defaultModels[0])
+	fmt.Fprintf(&b, "else a picker asks. The answer is remembered in the profile.")
 	if spec.hasFastModel() {
-		fmt.Fprintf(&b, "%s hands background work (titles, summaries, subagents marked haiku) to a smaller\n", spec.displayName)
-		fmt.Fprintf(&b, "model. That is settled the same way, preferring %s and falling back to the main\n", spec.defaultFastModels[0])
-		fmt.Fprintf(&b, "model itself; %s picks again.\n\n", harnessChooseFastModelFlag)
+		fmt.Fprintf(&b, " Background work is settled\nthe same way, preferring %s.", spec.defaultFastModels[0])
 	}
+	b.WriteString("\n")
 
 	return b.String()
 }
@@ -311,11 +303,6 @@ func (p *harnessArgs) set(flag, value string) error {
 		p.launch.Model = value
 	case harnessFastModelFlag:
 		p.launch.FastModel = value
-	case harnessEffortFlag:
-		if !slices.Contains(harnesses.Efforts, value) {
-			return fmt.Errorf("%s must be one of %s (got %q)", flag, strings.Join(harnesses.Efforts, ", "), value)
-		}
-		p.launch.Effort = value
 	}
 
 	return nil
diff --git a/cmd/harness_test.go b/cmd/harness_test.go
index 6787257..7d23a4c 100644
--- a/cmd/harness_test.go
+++ b/cmd/harness_test.go
@@ -39,20 +39,19 @@ func TestParseHarnessArgs(t *testing.T) {
 		},
 		{
 			name: "leading flags then passthrough",
-			args: []string{"--profile", "eu", "--model", "anthropic/claude-fable-5", "--reasoning-effort=high", "--dangerously-skip-permissions", "-p", "hi"},
+			args: []string{"--profile", "eu", "--model", "anthropic/claude-fable-5", "--effort", "high", "--dangerously-skip-permissions", "-p", "hi"},
 			want: harnessArgs{
 				profile: "eu",
 				launch: harnesses.LaunchOptions{
-					Model:  "anthropic/claude-fable-5",
-					Effort: harnesses.EffortHigh,
-					Args:   []string{"--dangerously-skip-permissions", "-p", "hi"},
+					Model: "anthropic/claude-fable-5",
+					Args:  []string{"--effort", "high", "--dangerously-skip-permissions", "-p", "hi"},
 				},
 			},
 		},
 		{
 			name: "equals form for every flag",
-			args: []string{"--profile=eu", "--model=openai/gpt-5", "--reasoning-effort=low"},
-			want: harnessArgs{profile: "eu", launch: harnesses.LaunchOptions{Model: "openai/gpt-5", Effort: harnesses.EffortLow}},
+			args: []string{"--profile=eu", "--model=openai/gpt-5"},
+			want: harnessArgs{profile: "eu", launch: harnesses.LaunchOptions{Model: "openai/gpt-5"}},
 		},
 		{
 			// The second --model belongs to the harness because a foreign flag came first.
@@ -104,11 +103,6 @@ func TestParseHarnessArgsErrors(t *testing.T) {
 		spec harnessSpec
 		want string
 	}{
-		{
-			name: "unknown effort",
-			args: []string{"--reasoning-effort", "turbo"},
-			want: `--reasoning-effort must be one of minimal, low, medium, high, xhigh, max (got "turbo")`,
-		},
 		{
 			name: "model without value",
 			args: []string{"--model"},
@@ -119,11 +113,6 @@ func TestParseHarnessArgsErrors(t *testing.T) {
 			args: []string{"--profile"},
 			want: "--profile requires a value",
 		},
-		{
-			name: "effort without value",
-			args: []string{"--reasoning-effort"},
-			want: "--reasoning-effort requires a value",
-		},
 		{
 			name: "empty equals value",
 			args: []string{"--model="},
@@ -201,7 +190,7 @@ func TestHarnessCommandHelpShowsOurFlags(t *testing.T) {
 	assert.Contains(t, output.String(), "--choose-model")
 	assert.Contains(t, output.String(), "--fast-model")
 	assert.Contains(t, output.String(), "--choose-fast-model")
-	assert.Contains(t, output.String(), "--reasoning-effort")
+	assert.NotContains(t, output.String(), "reasoning-effort", "effort belongs to the harness's own flags")
 	assert.Contains(t, output.String(), "passed to `claude`")
 	assert.Contains(t, output.String(), "claude-sonnet-4-6 is used when the profile can route to it")
 	assert.Contains(t, output.String(), "claude-haiku-4-5")
@@ -317,6 +306,19 @@ func TestEnsureModelsFallsBackToTheMainModelForBackgroundWork(t *testing.T) {
 	assert.Contains(t, stderr.String(), "Using claude-sonnet-4-6 for Claude Code background work")
 }
 
+func TestEnsureModelsForgetsFastModelWhenMainModelIsNewlyPicked(t *testing.T) {
+	env, cfg, cmd, _ := modelsEnvironment(t, routerServing(t, "claude-sonnet-4-6", "claude-haiku-4-5"), config.Config{
+		HarnessFastModels: map[string]string{"claude": "claude-haiku-4-5@eu"},
+	})
+
+	model, fast, err := env.ensureModels(cmd, cfg, claudeSpec, harnessArgs{})
+
+	require.NoError(t, err)
+	assert.Equal(t, "claude-sonnet-4-6", model)
+	assert.Equal(t, "claude-haiku-4-5", fast, "the remembered fast model is settled again next to the new main model")
+	assert.Equal(t, "claude-haiku-4-5", env.store.Profiles["work"].HarnessFastModels["claude"])
+}
+
 func TestEnsureModelsUsesWhatIsRememberedWithoutLookingUp(t *testing.T) {
 	env, cfg, cmd, stderr := modelsEnvironment(t, routerServing(t), config.Config{
 		HarnessModels:     map[string]string{"claude": "claude-fable-5"},
@@ -381,13 +383,3 @@ func TestHarnessProfileFlag(t *testing.T) {
 
 	require.ErrorContains(t, err, `profile "sales" not found`)
 }
-
-func TestHarnessProfileFromEnvironment(t *testing.T) {
-	t.Setenv(profileEnv, "sales")
-	command := newRootCommand(&environment{store: twoProfiles})
-	command.SetArgs([]string{"claude"})
-
-	err := command.Execute()
-
-	require.ErrorContains(t, err, `profile "sales" not found`)
-}
diff --git a/cmd/login.go b/cmd/login.go
index 63265b9..f6e10f7 100644
--- a/cmd/login.go
+++ b/cmd/login.go
@@ -24,17 +24,11 @@ func newLoginCommand(env *environment) *cobra.Command {
 		Use:   "login [--group <name>] [--profile <name>] [--api-key <key>] [--router-url <url>] [--force]",
 		Short: "Sign in to Requesty and save a profile on this machine",
 		Long: "Sign in to Requesty in your browser and save a profile on this machine.\n\n" +
-			"Once you approve in the browser, the CLI creates an API key in your Requesty\n" +
-			"account and saves it as a profile in " + config.DisplayPath() + ", where\n" +
-			"`requesty claude`, `requesty codex` and the terminal app pick it up. The key is\n" +
-			"named after this machine so you can recognise it on " + onboarding.APIKeysURL + ".\n\n" +
-			"The key goes in your group. With several groups you are asked which, or you can\n" +
-			"name one with --group. Without any group the key is a personal one. The profile\n" +
-			"is called `" + defaultProfileName + "` unless you pass --profile; the first one saved becomes current.\n\n" +
-			"The browser hands the sign-in back to this machine on 127.0.0.1, which does not\n" +
-			"work over SSH. There, pass --api-key with a key from " + onboarding.APIKeysURL + "\n" +
-			"instead; it is checked against the gateway and saved.\n\n" +
-			"An existing profile is left alone; pass --force to replace its key.",
+			"The CLI creates an API key in your account, named after this machine, and saves\n" +
+			"it as the `" + defaultProfileName + "` profile in " + config.DisplayPath() + ". Harness commands and\n" +
+			"the terminal app run with it.\n\n" +
+			"The browser hands the sign-in back on 127.0.0.1, which does not work over SSH;\n" +
+			"there, pass --api-key with a key from " + onboarding.APIKeysURL + " instead.",
 		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			groupID, _ := cmd.Flags().GetString(loginGroupFlag)
@@ -42,7 +36,7 @@ func newLoginCommand(env *environment) *cobra.Command {
 			routerURL, _ := cmd.Flags().GetString(loginRouterURLFlag)
 			force, _ := cmd.Flags().GetBool(loginForceFlag)
 
-			name := requestedProfile(cmd)
+			name, _ := cmd.Flags().GetString(profileFlag)
 			if name == "" {
 				name = defaultProfileName
 			}
diff --git a/cmd/profiles.go b/cmd/profiles.go
index 66c12ad..d5936bd 100644
--- a/cmd/profiles.go
+++ b/cmd/profiles.go
@@ -2,7 +2,6 @@ package cmd
 
 import (
 	"fmt"
-	"os"
 
 	"github.com/requestyai/cli/internal/config"
 	"github.com/requestyai/cli/internal/onboarding"
@@ -16,8 +15,8 @@ func newProfilesCommand(env *environment) *cobra.Command {
 		Short:   "Manage the profiles saved on this machine",
 		Long: "Manage the profiles saved in " + config.DisplayPath() + ".\n\n" +
 			"A profile is one sign-in: an API key and the router it goes to. `requesty login`\n" +
-			"creates them; pick one for a run with --" + profileFlag + " or " + profileEnv + ", or make it\n" +
-			"current with `requesty profiles use`.",
+			"creates them; pick one for a run with --" + profileFlag + ", or make it current with\n" +
+			"`requesty profiles use`.",
 	}
 
 	cmd.PersistentFlags().Bool(jsonFlag, false, "print JSON instead of a table")
@@ -81,7 +80,7 @@ func newProfilesUseCommand(env *environment) *cobra.Command {
 	return &cobra.Command{
 		Use:   "use <name>",
 		Short: "Make a profile the current one",
-		Long:  "Make a profile the one used when none is named with --" + profileFlag + " or " + profileEnv + ".",
+		Long:  "Make a profile the one used when none is named with --" + profileFlag + ".",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			name := args[0]
@@ -121,13 +120,3 @@ func newProfilesRemoveCommand(env *environment) *cobra.Command {
 		},
 	}
 }
-
-// requestedProfile is the profile the user named for this run: the flag,
-// else the environment variable, else empty for whatever the config says.
-func requestedProfile(cmd *cobra.Command) string {
-	if flag := cmd.Flags().Lookup(profileFlag); flag != nil && flag.Changed {
-		return flag.Value.String()
-	}
-
-	return os.Getenv(profileEnv)
-}
diff --git a/cmd/requesty.go b/cmd/requesty.go
index b98415c..ad47fca 100644
--- a/cmd/requesty.go
+++ b/cmd/requesty.go
@@ -26,7 +26,7 @@ func newRootCommand(env *environment) *cobra.Command {
 			"Run with no arguments for the terminal app that configures harnesses and shows\n" +
 			"what you are spending. The subcommands manage your organization instead.\n\n" +
 			"Every command runs as one saved profile: an API key and its router. Name one\n" +
-			"with --" + profileFlag + " or " + profileEnv + "; otherwise the current profile is used.",
+			"with --" + profileFlag + "; otherwise the current profile is used.",
 		Args:          cobra.NoArgs,
 		SilenceUsage:  true,
 		SilenceErrors: true,
@@ -43,7 +43,7 @@ func newRootCommand(env *environment) *cobra.Command {
 			return nil
 		},
 	}
-	root.PersistentFlags().String(profileFlag, "", "saved profile to run as (also "+profileEnv+")")
+	root.PersistentFlags().String(profileFlag, "", "saved profile to run as")
 
 	root.AddCommand(
 		newLoginCommand(env),
diff --git a/cmd/requesty_test.go b/cmd/requesty_test.go
index 26236f9..1305d46 100644
--- a/cmd/requesty_test.go
+++ b/cmd/requesty_test.go
@@ -55,17 +55,6 @@ func TestAuthTokenPicksExplicitProfile(t *testing.T) {
 	assert.Equal(t, "rqsty-me\n", output.String())
 }
 
-func TestAuthTokenUsesEnvironmentProfile(t *testing.T) {
-	t.Setenv(profileEnv, "personal")
-	var output bytes.Buffer
-	command := newRootCommand(&environment{store: twoProfiles})
-	command.SetOut(&output)
-	command.SetArgs([]string{"auth", "token"})
-
-	require.NoError(t, command.Execute())
-	assert.Equal(t, "rqsty-me\n", output.String())
-}
-
 func TestAuthTokenRejectsMissingProfile(t *testing.T) {
 	command := newRootCommand(&environment{})
 	command.SetArgs([]string{"auth", "token"})
diff --git a/internal/config/config.go b/internal/config/config.go
index 8d429c6..8481c44 100644
--- a/internal/config/config.go
+++ b/internal/config/config.go
@@ -5,6 +5,8 @@ import (
 	"errors"
 	"fmt"
 	"io/fs"
+	"net"
+	"net/url"
 	"os"
 	"path/filepath"
 	"sort"
@@ -31,20 +33,16 @@ type Config struct {
 	// HarnessModels is the model each harness was picked to launch with.
 	HarnessModels map[string]string `json:"harness_models,omitempty"`
 	// HarnessFastModels is the model each harness hands background work to,
-	// for harnesses that have such a slot. Kept apart from HarnessModels so
-	// a settings file stays readable by versions before it existed.
+	// for harnesses that have such a slot.
 	HarnessFastModels map[string]string `json:"harness_fast_models,omitempty"`
 }
 
-// SetHarnessModel remembers model as the one to launch harness with. It also
-// forgets the fast model: a new main model may sit in another region, so
-// what goes alongside it is settled afresh.
+// SetHarnessModel remembers model as the one to launch harness with.
 func (c *Config) SetHarnessModel(harness, model string) {
 	if c.HarnessModels == nil {
 		c.HarnessModels = make(map[string]string)
 	}
 	c.HarnessModels[harness] = model
-	delete(c.HarnessFastModels, harness)
 }
 
 // SetHarnessFastModel remembers model as the one harness hands background
@@ -56,11 +54,32 @@ func (c *Config) SetHarnessFastModel(harness, model string) {
 	c.HarnessFastModels[harness] = model
 }
 
+// APIBaseURL is the management API that corresponds to the router: the host's
+// "router" becomes "api-v2" and the local stack's port 40000 becomes 40003.
+// The path is left alone, and an address that cannot be parsed comes back as
+// it was given.
 func (c Config) APIBaseURL() string {
-	apiBaseURL := strings.Replace(c.RouterBaseURL, "router", "api-v2", 1)
-	apiBaseURL = strings.Replace(apiBaseURL, "40000", "40003", 1)
+	parsed, err := url.Parse(c.RouterBaseURL)
+	if err != nil || parsed.Host == "" {
+		return c.RouterBaseURL
+	}
+
+	host, port := parsed.Hostname(), parsed.Port()
+	rewritten := strings.Replace(host, "router", "api-v2", 1)
+	if port == "40000" {
+		port = "40003"
+	}
+	if rewritten == host && port == parsed.Port() {
+		return c.RouterBaseURL
+	}
 
-	return apiBaseURL
+	if port != "" {
+		parsed.Host = net.JoinHostPort(rewritten, port)
+	} else {
+		parsed.Host = rewritten
+	}
+
+	return parsed.String()
 }
 
 // Store is the saved profiles and which one is current.
@@ -167,6 +186,9 @@ func Load() (Store, error) {
 		if err := json.Unmarshal(data, &store); err != nil {
 			return Store{}, fmt.Errorf("failed to parse config: %w", err)
 		}
+		if err := validate(store); err != nil {
+			return Store{}, err
+		}
 	}
 
 	for name, cfg := range store.Profiles {
@@ -202,6 +224,21 @@ func Save(store Store) error {
 	return nil
 }
 
+// validate reports a store that names no current profile, or names one that
+// is not saved. An empty store is the not-onboarded state and is fine.
+func validate(store Store) error {
+	if len(store.Profiles) > 0 && store.Current == "" {
+		return errors.New("current profile is required")
+	}
+	if store.Current != "" {
+		if _, ok := store.Profiles[store.Current]; !ok {
+			return fmt.Errorf("current profile %q is not saved", store.Current)
+		}
+	}
+
+	return nil
+}
+
 func configPath() (string, error) {
 	home, err := os.UserHomeDir()
 	if err != nil {
diff --git a/internal/config/config_test.go b/internal/config/config_test.go
index 819bb9e..e985496 100644
--- a/internal/config/config_test.go
+++ b/internal/config/config_test.go
@@ -137,18 +137,6 @@ func TestSaveRoundTrips(t *testing.T) {
 	assert.Equal(t, "claude-haiku-4-5", got.Profiles["work"].HarnessFastModels["claude"])
 }
 
-func TestSetHarnessModelForgetsFastModel(t *testing.T) {
-	var cfg Config
-	cfg.SetHarnessModel("claude", "claude-sonnet-4-6")
-	cfg.SetHarnessFastModel("claude", "claude-haiku-4-5")
-	cfg.SetHarnessFastModel("other", "kept")
-
-	cfg.SetHarnessModel("claude", "claude-sonnet-4-6@eu")
-
-	assert.NotContains(t, cfg.HarnessFastModels, "claude")
-	assert.Equal(t, "kept", cfg.HarnessFastModels["other"])
-}
-
 func TestHarnessModelsAreOmittedUntilSet(t *testing.T) {
 	data, err := json.Marshal(Config{APIKey: "k", RouterBaseURL: DefaultRouterBaseURL})
 
diff --git a/internal/harnesses/claude.go b/internal/harnesses/claude.go
index 44c9f26..3149366 100644
--- a/internal/harnesses/claude.go
+++ b/internal/harnesses/claude.go
@@ -139,15 +139,6 @@ func (c *ClaudeHarness) settingsPath() string {
 	return filepath.Join(c.configDir, "settings.json")
 }
 
-// claudeEfforts maps Launch effort levels onto Claude Code's --effort values.
-var claudeEfforts = map[string]string{
-	EffortLow:    "low",
-	EffortMedium: "medium",
-	EffortHigh:   "high",
-	EffortXHigh:  "xhigh",
-	EffortMax:    "max",
-}
-
 // claudeOverrideSettings are passed inline with --settings so they outrank
 // the user's own settings.json for this run only. Every alternative-provider
 // switch is blanked so a Bedrock or Vertex setup on the machine cannot route
@@ -189,11 +180,6 @@ func (c *ClaudeHarness) Launch(opts LaunchOptions) error {
 		return fmt.Errorf("`claude` is not on PATH; install Claude Code (https://code.claude.com/docs/en/setup) and try again")
 	}
 
-	effort, err := mapEffort(c.Name(), claudeEfforts, opts.Effort)
-	if err != nil {
-		return err
-	}
-
 	env := parseEnvironmentVariables(opts.Env)
 	env["ANTHROPIC_BASE_URL"] = c.config.RouterBaseURL
 	env["ANTHROPIC_API_KEY"] = c.config.APIKey
@@ -221,9 +207,6 @@ func (c *ClaudeHarness) Launch(opts LaunchOptions) error {
 		}
 		argv = append(argv, "--settings", settings)
 	}
-	if effort != "" {
-		argv = append(argv, "--effort", effort)
-	}
 	argv = append(argv, opts.Args...)
 
 	if err := execProcess(status.ExecutablePath, argv, formatEnvironmentVariables(env)); err != nil {
diff --git a/internal/harnesses/codex.go b/internal/harnesses/codex.go
index 15c0451..2dee932 100644
--- a/internal/harnesses/codex.go
+++ b/internal/harnesses/codex.go
@@ -194,15 +194,6 @@ func (c *CodexHarness) authArgs() []string {
 	return []string{"auth", "token", "--profile", c.config.Name}
 }
 
-// codexEfforts maps Launch effort levels onto Codex's model_reasoning_effort.
-var codexEfforts = map[string]string{
-	EffortMinimal: "minimal",
-	EffortLow:     "low",
-	EffortMedium:  "medium",
-	EffortHigh:    "high",
-	EffortXHigh:   "xhigh",
-}
-
 // Launch replaces this process with Codex pointed at Requesty using
 // `-c key=value` overrides, which outrank ~/.codex/config.toml for this run
 // only. Nothing is written to disk; the key is fetched on demand through
@@ -216,11 +207,6 @@ func (c *CodexHarness) Launch(opts LaunchOptions) error {
 		return fmt.Errorf("`codex` is not on PATH; install Codex (https://developers.openai.com/codex/cli) and try again")
 	}
 
-	effort, err := mapEffort(c.Name(), codexEfforts, opts.Effort)
-	if err != nil {
-		return err
-	}
-
 	provider := "model_providers." + codexModelProvider
 	argv := []string{
 		"codex",
@@ -235,9 +221,6 @@ func (c *CodexHarness) Launch(opts LaunchOptions) error {
 	if opts.Model != "" {
 		argv = append(argv, "-m", opts.Model)
 	}
-	if effort != "" {
-		argv = append(argv, "-c", "model_reasoning_effort="+tomlString(effort))
-	}
 	argv = append(argv, opts.Args...)
 
 	env := opts.Env
diff --git a/internal/harnesses/harnesses.go b/internal/harnesses/harnesses.go
index f625678..d3c85e5 100644
--- a/internal/harnesses/harnesses.go
+++ b/internal/harnesses/harnesses.go
@@ -21,17 +21,11 @@ type ConfigureOptions struct {
 
 type LaunchOptions struct {
 	// Model is what the harness is told to use: a managed policy or any
-	// Requesty model id. Empty leaves whatever the harness would pick on its
-	// own (including a model our Configure wrote into its settings file
-	// earlier), which a gateway with an access list may well reject.
+	// Requesty model id.
 	Model string
 	// FastModel is what the harness hands background work to, such as
-	// Claude Code's haiku alias. Empty leaves the harness's own default,
-	// which is an Anthropic model id a gateway does not know. Harnesses
-	// without such a slot ignore it.
+	// Claude Code's haiku alias.
 	FastModel string
-	// Effort is one of Efforts, or empty for the harness default.
-	Effort string
 	// Args is passed to the harness binary untouched, after our own flags.
 	Args []string
 	// Env is the environment to start from. nil means os.Environ().
diff --git a/internal/harnesses/hermes.go b/internal/harnesses/hermes.go
index 8068fae..0eaaafb 100644
--- a/internal/harnesses/hermes.go
+++ b/internal/harnesses/hermes.go
@@ -119,24 +119,11 @@ func (h *HermesHarness) Status() (Status, error) {
 	return status, nil
 }
 
-// hermesEfforts maps Launch effort levels onto Hermes's --reasoning values,
-// which take the level name as is.
-var hermesEfforts = map[string]string{
-	EffortMinimal: "minimal",
-	EffortLow:     "low",
-	EffortMedium:  "medium",
-	EffortHigh:    "high",
-	EffortXHigh:   "xhigh",
-	EffortMax:     "max",
-}
-
-// hermesProviderFlags, hermesModelFlags and hermesReasoningFlags are the
-// Hermes flags that, when the user passes them, mean we leave the
-// corresponding choice alone.
+// hermesProviderFlags and hermesModelFlags are the Hermes flags that, when
+// the user passes them, mean we leave the corresponding choice alone.
 var (
-	hermesProviderFlags  = []string{"--provider"}
-	hermesModelFlags     = []string{"-m", "--model"}
-	hermesReasoningFlags = []string{"--reasoning"}
+	hermesProviderFlags = []string{"--provider"}
+	hermesModelFlags    = []string{"-m", "--model"}
 )
 
 // hermesLaunchEnv are the variables the launch sets; a ~/.hermes/.env that
@@ -157,11 +144,6 @@ func (h *HermesHarness) Launch(opts LaunchOptions) error {
 		return fmt.Errorf("`hermes` is not on PATH; install Hermes (https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) and try again")
 	}
 
-	effort, err := mapEffort(h.Name(), hermesEfforts, opts.Effort)
-	if err != nil {
-		return err
-	}
-
 	env := parseEnvironmentVariables(opts.Env)
 	env["CUSTOM_BASE_URL"] = h.config.RouterBaseURL + "/v1"
 	env["REQUESTY_API_KEY"] = h.config.APIKey
@@ -177,9 +159,6 @@ func (h *HermesHarness) Launch(opts LaunchOptions) error {
 	if opts.Model != "" && !hasAnyFlag(opts.Args, hermesModelFlags) {
 		argv = append(argv, "-m", opts.Model)
 	}
-	if effort != "" && !hasAnyFlag(opts.Args, hermesReasoningFlags) {
-		argv = append(argv, "--reasoning", effort)
-	}
 	argv = append(argv, opts.Args...)
 
 	if err := execProcess(status.ExecutablePath, argv, formatEnvironmentVariables(env)); err != nil {
diff --git a/internal/harnesses/launch.go b/internal/harnesses/launch.go
index 677d444..7b59d02 100644
--- a/internal/harnesses/launch.go
+++ b/internal/harnesses/launch.go
@@ -4,46 +4,9 @@ import (
 	"fmt"
 	"os"
 	"slices"
-	"sort"
 	"strings"
 )
 
-// Effort levels understood by Launch. Each harness translates them to its own
-// vocabulary and rejects the ones it cannot express.
-const (
-	EffortMinimal = "minimal"
-	EffortLow     = "low"
-	EffortMedium  = "medium"
-	EffortHigh    = "high"
-	EffortXHigh   = "xhigh"
-	EffortMax     = "max"
-)
-
-// Efforts lists every level Launch accepts, weakest first.
-var Efforts = []string{EffortMinimal, EffortLow, EffortMedium, EffortHigh, EffortXHigh, EffortMax}
-
-// mapEffort translates a Launch effort level through a harness's own table.
-func mapEffort(harness string, table map[string]string, effort string) (string, error) {
-	if effort == "" {
-		return "", nil
-	}
-
-	if native, ok := table[effort]; ok {
-		return native, nil
-	}
-
-	accepted := make([]string, 0, len(table))
-	for level := range table {
-		accepted = append(accepted, level)
-	}
-	sort.Slice(accepted, func(i, j int) bool {
-		return slices.Index(Efforts, accepted[i]) < slices.Index(Efforts, accepted[j])
-	})
-
-	return "", fmt.Errorf("%s does not support reasoning effort %q (accepted: %s)",
-		harness, effort, strings.Join(accepted, ", "))
-}
-
 // launchNotImplemented is what harnesses without a launcher say instead of
 // doing anything.
 func launchNotImplemented(name string) error {
diff --git a/internal/harnesses/opencode.go b/internal/harnesses/opencode.go
index 4e4acdb..39c142e 100644
--- a/internal/harnesses/opencode.go
+++ b/internal/harnesses/opencode.go
@@ -100,23 +100,9 @@ func (o *OpenCodeHarness) Status() (Status, error) {
 	return status, nil
 }
 
-// openCodeEfforts maps Launch effort levels onto OpenCode's --variant values,
-// which take the level name as is.
-var openCodeEfforts = map[string]string{
-	EffortMinimal: "minimal",
-	EffortLow:     "low",
-	EffortMedium:  "medium",
-	EffortHigh:    "high",
-	EffortXHigh:   "xhigh",
-	EffortMax:     "max",
-}
-
-// openCodeModelFlags and openCodeVariantFlags are the OpenCode flags that,
-// when the user passes them, mean we leave the corresponding choice alone.
-var (
-	openCodeModelFlags   = []string{"-m", "--model"}
-	openCodeVariantFlags = []string{"--variant"}
-)
+// openCodeModelFlags are the OpenCode flags that, when the user passes them,
+// mean we leave the model alone.
+var openCodeModelFlags = []string{"-m", "--model"}
 
 // Launch replaces this process with OpenCode pointed at Requesty. OpenCode
 // knows Requesty as a built-in provider that switches on when
@@ -132,11 +118,6 @@ func (o *OpenCodeHarness) Launch(opts LaunchOptions) error {
 		return fmt.Errorf("`opencode` is not on PATH; install OpenCode (https://opencode.ai/docs) and try again")
 	}
 
-	effort, err := mapEffort(o.Name(), openCodeEfforts, opts.Effort)
-	if err != nil {
-		return err
-	}
-
 	env := parseEnvironmentVariables(opts.Env)
 	env["REQUESTY_API_KEY"] = o.config.APIKey
 	content, err := o.inlineConfig(env["OPENCODE_CONFIG_CONTENT"], opts.Model)
@@ -153,9 +134,6 @@ func (o *OpenCodeHarness) Launch(opts LaunchOptions) error {
 	if opts.Model != "" && !hasAnyFlag(opts.Args, openCodeModelFlags) {
 		argv = append(argv, "-m", o.modelID(opts.Model))
 	}
-	if effort != "" && !hasAnyFlag(opts.Args, openCodeVariantFlags) {
-		argv = append(argv, "--variant", effort)
-	}
 	argv = append(argv, opts.Args...)
 
 	if err := execProcess(status.ExecutablePath, argv, formatEnvironmentVariables(env)); err != nil {
diff --git a/internal/harnesses/pi.go b/internal/harnesses/pi.go
index c0874e7..e5cc384 100644
--- a/internal/harnesses/pi.go
+++ b/internal/harnesses/pi.go
@@ -176,23 +176,11 @@ type piCatalogCost struct {
 	CacheWrite float64 `json:"cacheWrite"`
 }
 
-// piEfforts maps Launch effort levels onto Pi's --thinking values, which
-// take the level name as is.
-var piEfforts = map[string]string{
-	EffortMinimal: "minimal",
-	EffortLow:     "low",
-	EffortMedium:  "medium",
-	EffortHigh:    "high",
-	EffortXHigh:   "xhigh",
-	EffortMax:     "max",
-}
-
-// piProviderFlags, piModelFlags and piThinkingFlags are the Pi flags that,
-// when the user passes them, mean we leave the corresponding choice alone.
+// piProviderFlags and piModelFlags are the Pi flags that, when the user
+// passes them, mean we leave the model choice alone.
 var (
 	piProviderFlags = []string{"--provider"}
 	piModelFlags    = []string{"--model"}
-	piThinkingFlags = []string{"--thinking"}
 )
 
 // piNeutralizedEnv are the credentials Pi reads for its built-in providers.
@@ -253,11 +241,6 @@ func (p *PiHarness) Launch(opts LaunchOptions) error {
 		return fmt.Errorf("`pi` is not on PATH; install Pi (https://pi.dev) and try again")
 	}
 
-	effort, err := mapEffort(p.Name(), piEfforts, opts.Effort)
-	if err != nil {
-		return err
-	}
-
 	launchDir, err := DefaultLaunchDirPi()
 	if err != nil {
 		return fmt.Errorf("failed to find launch directory: %w", err)
@@ -289,9 +272,6 @@ func (p *PiHarness) Launch(opts LaunchOptions) error {
 	default:
 		argv = append(argv, "--provider", piProvider)
 	}
-	if effort != "" && !hasAnyFlag(opts.Args, piThinkingFlags) {
-		argv = append(argv, "--thinking", effort)
-	}
 	argv = append(argv, opts.Args...)
 
 	if err := execProcess(status.ExecutablePath, argv, formatEnvironmentVariables(env)); err != nil {
diff --git a/internal/onboarding/model.go b/internal/onboarding/model.go
index c2b7b85..70215d8 100644
--- a/internal/onboarding/model.go
+++ b/internal/onboarding/model.go
@@ -4,9 +4,11 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"strings"
 
 	tea "charm.land/bubbletea/v2"
 	"charm.land/lipgloss/v2"
+	"github.com/charmbracelet/x/ansi"
 	"github.com/requestyai/cli/internal/client"
 	"github.com/requestyai/cli/internal/config"
 	"github.com/requestyai/cli/internal/tui/theme"
@@ -15,7 +17,6 @@ import (
 )
 
 const (
-	pageWidth       = 64
 	dialogMinWidth  = 24
 	dialogMaxWidth  = 80
 	groupListHeight = 8
@@ -60,25 +61,32 @@ type savedMsg struct {
 
 // model owns the complete interactive onboarding program.
 type model struct {
-	ctx    context.Context
-	opts   Options
-	dialog dialogState
-	err    error
-	width  int
-	height int
-	done   *config.Config
+	ctx     context.Context
+	opts    Options
+	dialog  dialogState
+	err     error
+	width   int
+	height  int
+	done    *config.Config
+	initCmd tea.Cmd
 }
 
+// newModel returns the program with the sign-in dialog already open, so it
+// is the first screen; Init starts the browser sign-in behind it. The welcome
+// page is only shown when the sign-in is cancelled or fails.
 func newModel(ctx context.Context, opts Options) model {
-	return model{
+	m := model{
 		ctx:    ctx,
 		opts:   opts,
 		width:  defaultWidth,
 		height: defaultHeight,
 	}
+	m, m.initCmd = m.signIn()
+
+	return m
 }
 
-func (m model) Init() tea.Cmd { return nil }
+func (m model) Init() tea.Cmd { return m.initCmd }
 
 func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 	switch typedMsg := msg.(type) {
@@ -96,31 +104,16 @@ func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
 
 	case savedMsg:
 		if typedMsg.err != nil {
-			return m.fail(typedMsg.err), nil
+			return m.fail(typedMsg.err)
 		}
 		m.done = &typedMsg.result.Config
 		return m, tea.Quit
 
 	case tea.KeyPressMsg:
-		switch typedMsg.String() {
-		case "ctrl+c":
+		if typedMsg.String() == "ctrl+c" {
 			return m, tea.Quit
-		case "q":
-			if !m.dialog.open {
-				return m, tea.Quit
-			}
-		case "esc":
-			if !m.dialog.open {
-				return m, tea.Quit
-			}
-		}
-
-		if m.dialog.open {
-			return m.updateDialog(typedMsg)
-		}
-		if typedMsg.String() == "enter" {
-			return m.signIn()
 		}
+		return m.updateDialog(typedMsg)
 	}
 
 	return m, nil
@@ -131,13 +124,13 @@ func (m model) updateDialog(msg tea.KeyPressMsg) (model, tea.Cmd) {
 	case dialogSigningIn:
 		if msg.String() == "esc" {
 			m.dialog.cancel()
-			m.dialog = dialogState{}
+			return m, tea.Quit
 		}
 	case dialogChooseGroup:
 		groups := m.dialog.session.groups
 		switch msg.String() {
 		case "esc":
-			m.dialog = dialogState{}
+			return m, tea.Quit
 		case "up", "k":
 			if m.dialog.groupCursor > 0 {
 				m.dialog.groupCursor--
@@ -183,11 +176,10 @@ func (m model) onSignedIn(msg signedInMsg) (model, tea.Cmd) {
 		return m, nil
 	}
 	if errors.Is(msg.err, context.Canceled) {
-		m.dialog = dialogState{}
-		return m, nil
+		return m, tea.Quit
 	}
 	if msg.err != nil {
-		return m.fail(msg.err), nil
+		return m.fail(msg.err)
 	}
 
 	m.dialog.session = msg.session
@@ -198,7 +190,7 @@ func (m model) onSignedIn(msg signedInMsg) (model, tea.Cmd) {
 		return m, nil
 	}
 	if err != nil {
-		return m.fail(err), nil
+		return m.fail(err)
 	}
 	return m.save(group)
 }
@@ -213,50 +205,18 @@ func (m model) save(group *client.Group) (model, tea.Cmd) {
 	}
 }
 
-func (m model) fail(err error) model {
-	m.dialog = dialogState{}
+// fail ends the program with err; Run reports it to the caller.
+func (m model) fail(err error) (model, tea.Cmd) {
 	m.err = err
-	return m
+	return m, tea.Quit
 }
 
 func (m model) View() tea.View {
-	view := tea.NewView(frame.Render(m.pageView()))
+	view := tea.NewView(frame.Render(m.dialogView()))
 	view.AltScreen = true
 	return view
 }
 
-func (m model) pageView() string {
-	if m.dialog.open {
-		return m.dialogView()
-	}
-
-	inner := max(min(m.width-4, pageWidth), dialogMinWidth)
-	wrap := lipgloss.NewStyle().Width(inner)
-	lines := []string{
-		theme.Heading.Render("Welcome to Requesty"),
-		wrap.Render(theme.Label.Render("One gateway for every model, in every tool you use, or app you build.")),
-		text.LineSeparator,
-		wrap.Render(theme.Body.Render(fmt.Sprintf(
-			"Sign in with your browser to get started. This creates an API key named %q in your Requesty account and saves it to %s.",
-			defaultKeyName(), config.DisplayPath()))),
-	}
-	if m.opts.Harness != "" {
-		lines = append(lines, wrap.Render(theme.Body.Render(m.opts.Harness+" starts as soon as the key is saved.")))
-	}
-	lines = append(lines,
-		text.LineSeparator,
-		wrap.Render(theme.Muted.Render("Working over SSH, or already have a key? Quit and run `requesty login --api-key <key>` instead.")),
-		text.LineSeparator,
-	)
-	if m.err != nil {
-		lines = append(lines, wrap.Render(theme.Bad.Render(m.err.Error())), text.LineSeparator)
-	}
-	lines = append(lines, text.RenderFooterHintList(inner, [2]string{"enter", "sign in"}, [2]string{"q/esc", "quit"}))
-
-	body := theme.Panel.Render(lipgloss.JoinVertical(lipgloss.Left, lines...))
-	return lipgloss.Place(m.width, m.height, lipgloss.Center, lipgloss.Center, body)
-}
-
 type dialogPage struct {
 	title string
 	body  string
@@ -281,18 +241,29 @@ func (m model) dialogPage(inner int) dialogPage {
 	wrap := lipgloss.NewStyle().Width(inner)
 	switch m.dialog.step {
 	case dialogSigningIn:
-		body := []string{wrap.Render(theme.Body.Render("Waiting for you to finish signing in in your browser…"))}
+		body := []string{
+			wrap.Render(theme.Label.Render("One gateway for every model, in every tool you use, or app you build.")),
+			text.LineSeparator,
+			wrap.Render(theme.Body.Render("Waiting for you to finish signing in with your browser…")),
+		}
 		if m.dialog.authorizeURL != "" {
 			body = append(body,
 				text.LineSeparator,
 				wrap.Render(theme.Muted.Render("If it did not open, visit this address:")),
-				wrap.Render(theme.Accent.Render(m.dialog.authorizeURL)),
+				hyperlinkLines(m.dialog.authorizeURL, inner),
 			)
 		}
+		if m.opts.Harness != "" {
+			body = append(body, text.LineSeparator, wrap.Render(theme.Muted.Render(m.opts.Harness+" starts as soon as the key is saved.")))
+		}
+		body = append(body,
+			text.LineSeparator,
+			wrap.Render(theme.Muted.Render("Working over SSH, or already have a key? Quit and run `requesty login --api-key <key>` instead.")),
+		)
 		return dialogPage{
-			title: "Sign in with your browser",
+			title: "Welcome to Requesty",
 			body:  lipgloss.JoinVertical(lipgloss.Left, body...),
-			hints: [][2]string{{"esc", "cancel"}},
+			hints: [][2]string{{"esc", "quit"}},
 		}
 	case dialogChooseGroup:
 		return dialogPage{
@@ -311,6 +282,25 @@ func (m model) dialogPage(inner int) dialogPage {
 	}
 }
 
+// authorizeLinkID ties the lines of a wrapped sign-in URL together, so the
+// terminal highlights them as one link on hover.
+const authorizeLinkID = "id=requesty-authorize"
+
+// hyperlinkLines renders url wrapped to width as a clickable link. Each line
+// is its own OSC 8 link to the full url, opened and closed around the text
+// alone, so the link does not spill into padding or borders and terminals
+// that join links by id highlight every line together.
+func hyperlinkLines(url string, width int) string {
+	wrapped := lipgloss.NewStyle().Width(width).Render(url)
+	lines := strings.Split(wrapped, "\n")
+	for i, line := range lines {
+		line = strings.TrimRight(line, " ")
+		lines[i] = ansi.SetHyperlink(url, authorizeLinkID) + theme.Accent.Render(line) + ansi.ResetHyperlink()
+	}
+
+	return strings.Join(lines, "\n")
+}
+
 func (m model) groupTable(inner int) table.Table {
 	groups := m.dialog.session.groups
 	rows := make([][]string, 0, len(groups))
diff --git a/internal/onboarding/model_test.go b/internal/onboarding/model_test.go
index 6489fa3..ca630d1 100644
--- a/internal/onboarding/model_test.go
+++ b/internal/onboarding/model_test.go
@@ -3,7 +3,7 @@ package onboarding
 import (
 	"context"
 	"errors"
-	"fmt"
+	"strings"
 	"testing"
 
 	tea "charm.land/bubbletea/v2"
@@ -44,23 +44,19 @@ func view(m model) string {
 	return ansi.Strip(m.View().Content)
 }
 
-func TestWelcomeExplainsOnboarding(t *testing.T) {
-	out := view(newModel(context.Background(), Options{Harness: "Claude Code"}))
-
-	assert.Contains(t, out, "Welcome to Requesty")
-	assert.Contains(t, out, fmt.Sprintf("%q", defaultKeyName()))
-	assert.Contains(t, out, "Claude Code starts as soon as the key is saved")
-	assert.Contains(t, out, "--api-key <key>")
-}
-
-func TestEnterOpensSigningInDialog(t *testing.T) {
-	m, cmd := update(newModel(context.Background(), Options{}), key("enter"))
+func TestSignInStartsImmediately(t *testing.T) {
+	m := newModel(context.Background(), Options{Harness: "Claude Code"})
 
 	assert.True(t, m.dialog.open)
 	assert.Equal(t, dialogSigningIn, m.dialog.step)
 	assert.NotNil(t, m.dialog.cancel)
-	assert.NotNil(t, cmd)
-	assert.Contains(t, view(m), "Waiting for you to finish signing in")
+	assert.NotNil(t, m.Init(), "Init hands the runtime the sign-in")
+	out := view(m)
+	assert.Contains(t, out, "Welcome to Requesty")
+	assert.Contains(t, out, "One gateway for every model")
+	assert.Contains(t, out, "Waiting for you to finish signing in")
+	assert.Contains(t, out, "Claude Code starts as soon as the key is saved")
+	assert.Contains(t, out, "--api-key <key>")
 }
 
 func TestSigningInDialogShowsAuthorizeURL(t *testing.T) {
@@ -72,27 +68,46 @@ func TestSigningInDialogShowsAuthorizeURL(t *testing.T) {
 	assert.Contains(t, view(m), "https://api.example/authorize")
 }
 
-func TestEscapeCancelsAndIgnoresLateSignIn(t *testing.T) {
+func TestAuthorizeURLIsOneHyperlinkWhenWrapped(t *testing.T) {
+	m := signingIn()
+	long := "https://api.example/authorize?" + strings.Repeat("x=1&", 40)
+
+	m, _ = update(m, authorizeURLMsg{url: long})
+	raw := m.View().Content
+
+	assert.Contains(t, ansi.Strip(raw), long[:20])
+	open := ansi.SetHyperlink(long, authorizeLinkID)
+	opens := strings.Count(raw, open)
+	assert.Greater(t, opens, 1, "each wrapped line is its own link to the full URL, sharing an id")
+	assert.Equal(t, opens, strings.Count(raw, ansi.ResetHyperlink()), "every line closes its link")
+	for _, segment := range strings.Split(raw, open)[1:] {
+		linked, _, found := strings.Cut(segment, ansi.ResetHyperlink())
+		require.True(t, found)
+		assert.NotContains(t, linked, "\n", "a link never runs past its line into padding or borders")
+	}
+}
+
+func TestEscapeCancelsAndQuits(t *testing.T) {
 	m := signingIn()
 	cancelled := false
 	m.dialog.cancel = func() { cancelled = true }
 
-	m, _ = update(m, key("esc"))
-	assert.True(t, cancelled)
-	assert.False(t, m.dialog.open)
+	m, cmd := update(m, key("esc"))
 
-	m, cmd := update(m, signedInMsg{session: &session{}})
-	assert.False(t, m.dialog.open)
-	assert.Nil(t, cmd)
+	assert.True(t, cancelled)
+	assert.NotNil(t, cmd, "quits")
+	assert.Nil(t, m.done)
+	assert.NoError(t, m.err, "a cancel is not an error")
 }
 
-func TestSignInFailureReturnsToWelcome(t *testing.T) {
+func TestSignInFailureQuitsWithError(t *testing.T) {
 	m := signingIn()
 
-	m, _ = update(m, signedInMsg{err: errors.New("access_denied")})
+	m, cmd := update(m, signedInMsg{err: errors.New("access_denied")})
 
-	assert.False(t, m.dialog.open)
-	assert.Contains(t, view(m), "access_denied")
+	assert.NotNil(t, cmd, "quits")
+	assert.EqualError(t, m.err, "access_denied")
+	assert.Nil(t, m.done)
 }
 
 func TestSeveralGroupsOpenPickerAndMoveCursor(t *testing.T) {
diff --git a/internal/onboarding/run.go b/internal/onboarding/run.go
index 9ac2160..6dfa6c7 100644
--- a/internal/onboarding/run.go
+++ b/internal/onboarding/run.go
@@ -25,7 +25,13 @@ func Run(ctx context.Context, opts Options) (config.Config, error) {
 	}
 
 	finished, ok := final.(model)
-	if !ok || finished.done == nil {
+	if !ok {
+		return config.Config{}, ErrCancelled
+	}
+	if finished.err != nil {
+		return config.Config{}, finished.err
+	}
+	if finished.done == nil {
 		return config.Config{}, ErrCancelled
 	}
 	return *finished.done, nil

From 1a3b95e2f06507b4fdb44d446d488de00f5c581e Mon Sep 17 00:00:00 2001
From: fayzan <fayzan@requesty.ai>
Date: Thu, 24 Sep 2026 16:18:54 +0100
Subject: [PATCH 9/9] Change default models for each harness

---
 README.md           |  5 +++--
 cmd/harness.go      | 24 +++++++++++++++++-------
 cmd/harness_test.go | 13 ++++++++++++-
 3 files changed, 32 insertions(+), 10 deletions(-)

diff --git a/README.md b/README.md
index dbd75ef..56bec23 100644
--- a/README.md
+++ b/README.md
@@ -101,7 +101,8 @@ configuration is not changed. The current profile is used unless you select anot
 
 The first time you launch a harness from a profile, the CLI settles which model it should use and
 remembers the answer in the profile. When the key can route to the harness's recommended default
-(`claude-sonnet-4-6` for Claude Code), that is used and printed, without asking. Otherwise a
+(`claude-sonnet-5` for Claude Code, `gpt-6-sol` for Codex, and for OpenCode, Pi and Hermes whichever
+of the two the key can route to first), that is used and printed, without asking. Otherwise a
 picker asks: the Policies tab lists Requesty's managed policies, which name a model once and
 route it across providers, and `tab` switches to every model the key can route to. `--model`
 overrides the remembered model for one run without changing it; `--choose-model` opens the picker
@@ -122,7 +123,7 @@ requesty claude --choose-model                     # pick again and remember the
 requesty claude --choose-fast-model                # pick what background work runs on
 requesty codex --full-auto                         # everything else goes to the harness untouched
 requesty claude --effort high                      # so its own flags work as usual
-requesty opencode --model gpt-5.5 run "explain this repo"
+requesty opencode --model gpt-6-sol run "explain this repo"
 requesty pi --thinking off
 requesty hermes chat -q "hello"
 ```
diff --git a/cmd/harness.go b/cmd/harness.go
index a143922..9e16e4e 100644
--- a/cmd/harness.go
+++ b/cmd/harness.go
@@ -55,7 +55,7 @@ func newHarnessCommands(env *environment) []*cobra.Command {
 		newHarnessCommand(env, harnessSpec{
 			binary:            "claude",
 			displayName:       "Claude Code",
-			defaultModels:     []string{"claude-sonnet-4-6"},
+			defaultModels:     []string{"claude-sonnet-5"},
 			defaultFastModels: []string{"claude-haiku-4-5"},
 			newHarness: func(cfg config.Config) (harnesses.Harness, error) {
 				dir, err := harnesses.DefaultConfigDirClaudeCode()
@@ -68,7 +68,7 @@ func newHarnessCommands(env *environment) []*cobra.Command {
 		newHarnessCommand(env, harnessSpec{
 			binary:        "codex",
 			displayName:   "Codex",
-			defaultModels: []string{"gpt-5.5"},
+			defaultModels: []string{"gpt-6-sol"},
 			newHarness: func(cfg config.Config) (harnesses.Harness, error) {
 				dir, err := harnesses.DefaultConfigDirCodex()
 				if err != nil {
@@ -80,7 +80,7 @@ func newHarnessCommands(env *environment) []*cobra.Command {
 		newHarnessCommand(env, harnessSpec{
 			binary:        "opencode",
 			displayName:   "OpenCode",
-			defaultModels: []string{"claude-sonnet-4-6"},
+			defaultModels: []string{"claude-sonnet-5", "gpt-6-sol"},
 			newHarness: func(cfg config.Config) (harnesses.Harness, error) {
 				dir, err := harnesses.DefaultConfigDirOpenCode()
 				if err != nil {
@@ -92,7 +92,7 @@ func newHarnessCommands(env *environment) []*cobra.Command {
 		newHarnessCommand(env, harnessSpec{
 			binary:        "pi",
 			displayName:   "Pi",
-			defaultModels: []string{"claude-sonnet-4-6"},
+			defaultModels: []string{"claude-sonnet-5", "gpt-6-sol"},
 			newHarness: func(cfg config.Config) (harnesses.Harness, error) {
 				dir, err := harnesses.DefaultConfigDirPi()
 				if err != nil {
@@ -104,7 +104,7 @@ func newHarnessCommands(env *environment) []*cobra.Command {
 		newHarnessCommand(env, harnessSpec{
 			binary:        "hermes",
 			displayName:   "Hermes",
-			defaultModels: []string{"claude-sonnet-4-6"},
+			defaultModels: []string{"claude-sonnet-5", "gpt-6-sol"},
 			newHarness: func(cfg config.Config) (harnesses.Harness, error) {
 				dir, err := harnesses.DefaultConfigDirHermes()
 				if err != nil {
@@ -190,16 +190,26 @@ func harnessLong(spec harnessSpec) string {
 		fmt.Fprintf(&b, "  %-28s %s\n", flag[0], flag[1])
 	}
 	fmt.Fprintf(&b, "\nAnything else, or everything after `--`, is passed to `%s` untouched.\n\n", spec.binary)
-	fmt.Fprintf(&b, "The first launch settles the model: %s is used when the profile can route to it,\n", spec.defaultModels[0])
+	fmt.Fprintf(&b, "The first launch settles the model: %s,\n", describeDefaults(spec.defaultModels))
 	fmt.Fprintf(&b, "else a picker asks. The answer is remembered in the profile.")
 	if spec.hasFastModel() {
-		fmt.Fprintf(&b, " Background work is settled\nthe same way, preferring %s.", spec.defaultFastModels[0])
+		fmt.Fprintf(&b, " Background work is settled\nthe same way, preferring %s.", strings.Join(spec.defaultFastModels, ", then "))
 	}
 	b.WriteString("\n")
 
 	return b.String()
 }
 
+// describeDefaults says in help text how the defaults are settled: the one
+// model is used when it can be routed to, or the first of several that can.
+func describeDefaults(models []string) string {
+	if len(models) == 1 {
+		return models[0] + " is used when the profile can route to it"
+	}
+
+	return fmt.Sprintf("the first of %s the profile can route to is used", strings.Join(models, " or "))
+}
+
 // harnessArgs is a harness command line split into our profile choice and
 // what the harness is launched with.
 type harnessArgs struct {
diff --git a/cmd/harness_test.go b/cmd/harness_test.go
index 7d23a4c..1f57fd6 100644
--- a/cmd/harness_test.go
+++ b/cmd/harness_test.go
@@ -192,7 +192,7 @@ func TestHarnessCommandHelpShowsOurFlags(t *testing.T) {
 	assert.Contains(t, output.String(), "--choose-fast-model")
 	assert.NotContains(t, output.String(), "reasoning-effort", "effort belongs to the harness's own flags")
 	assert.Contains(t, output.String(), "passed to `claude`")
-	assert.Contains(t, output.String(), "claude-sonnet-4-6 is used when the profile can route to it")
+	assert.Contains(t, output.String(), "claude-sonnet-5 is used when the profile can route to it")
 	assert.Contains(t, output.String(), "claude-haiku-4-5")
 }
 
@@ -208,6 +208,17 @@ func TestHarnessWithoutFastModelHidesItsFlags(t *testing.T) {
 	assert.NotContains(t, output.String(), "fast-model")
 }
 
+func TestHarnessHelpListsEveryDefault(t *testing.T) {
+	command := newRootCommand(&environment{store: oneProfile})
+	var output bytes.Buffer
+	command.SetOut(&output)
+	command.SetArgs([]string{"opencode", "--help"})
+
+	require.NoError(t, command.Execute())
+
+	assert.Contains(t, output.String(), "the first of claude-sonnet-5 or gpt-6-sol the profile can route to is used")
+}
+
 func TestHarnessWithoutFastModelRejectsItsFlags(t *testing.T) {
 	for _, args := range [][]string{{"--fast-model", "x"}, {"--choose-fast-model"}} {
 		command := newRootCommand(&environment{store: oneProfile})