Clean up domain command i'm unsure of

Author: OisinKyne

CLAUDE.md

@@ -88,7 +88,7 @@ obol
 ├── model           setup (has sub: custom), status, token, sync, pull, list, prefer, discover, remove
 ├── app             install, sync, list, delete
 ├── tunnel          status, setup, restart, stop, logs (login hidden: browser-managed fallback)
-├── domain          search, check, register
+├── domain          list, search, check, register
 ├── kubectl/helm/helmfile/k9s   Passthrough (auto KUBECONFIG)
 ├── update          Helm + CLI version check (--json)
 ├── upgrade         Apply chart upgrades (--defaults-only, --pinned, --major)
@@ -102,7 +102,7 @@ obol
 - `sell info <name>` prints purchase instructions (URL, model, buy.py command).
 - `sell mcp [name]` runs a foreground x402-paid MCP server: forwards buyer JSON args to a backend HTTP service, injecting the seller's own API key (buyer never sees it). Payment rides MCP `_meta` (`internal/x402mcp`).
 - `sell resume` replays every persisted sell offer (inference incl. detached host-gateway relaunch; http/agent/demo-agent via the manifest ledger at `$OBOL_CONFIG_DIR/sell-http/`) — run after a host reboot; `obol stack up` runs the same path. `--install-boot-unit` adds a systemd user unit (Linux). `sell mcp` is foreground-only, no offer, not resumed.
-- `tunnel setup [<token>]`: the one permanent-URL command. Connector-token based (dashboard-managed) — no host binary, no account-wide API key. Accepts the bare connector token, the `--token` flag, a positional arg, or the whole `cloudflared tunnel run --token …` line (prefix stripped via `extractConnectorToken`). Reuses the remote runtime (`ProvisionWithToken` → `TUNNEL_TOKEN` secret, chart `management_mode=remote`); DNS/ingress are configured by the user in the Cloudflare dashboard (route Public Hostname → `http://traefik.traefik.svc.cluster.local:80`), not via API. The API-token provisioning path was removed (no more `tunnel provision`, no setup `--api-token/--account-id/--zone-id/--register-domain`). `--management local` (alias hidden `tunnel login`) is the browser fallback (needs `cloudflared`). `tunnel status` reads connector health from cloudflared's in-cluster `/ready`+`/metrics` (port 2000, no token) plus a public HTTP probe; concise by default, `--verbose` for replicas/pods, `--no-probe` to stay offline. Domain registration still lives under `obol domain register` (still uses a Cloudflare API token).
+- `tunnel setup [<token>]`: the one permanent-URL command. Connector-token based (dashboard-managed) — no host binary, no account-wide API key. Accepts the bare connector token, the `--token` flag, a positional arg, or the whole `cloudflared tunnel run --token …` line (prefix stripped via `extractConnectorToken`). Reuses the remote runtime (`ProvisionWithToken` → `TUNNEL_TOKEN` secret, chart `management_mode=remote`); DNS/ingress are configured by the user in the Cloudflare dashboard (route Public Hostname → `http://traefik.traefik.svc.cluster.local:80`), not via API. The API-token provisioning path was removed (no more `tunnel provision`, no setup `--api-token/--account-id/--zone-id/--register-domain`). `--management local` (alias hidden `tunnel login`) is the browser fallback (needs `cloudflared`). `tunnel status` reads connector health from cloudflared's in-cluster `/ready`+`/metrics` (port 2000, no token) plus a public HTTP probe; concise by default, `--verbose` for replicas/pods, `--no-probe` to stay offline. Domain management lives under `obol domain` (`list`, `search`, `check`, `register`) — an optional CLI wrapper around Cloudflare Registrar; still uses a scoped Cloudflare **API token** (Account → Domain perm, via `--api-token`/`CLOUDFLARE_API_TOKEN`; on a TTY it walks you through token creation and prompts). `--api-token` deliberately has NO `-t` alias to avoid colliding with `tunnel setup -t` (connector token — a different credential). `register` is billable (needs a payment method on the CF account); on success it prints the `obol tunnel setup --hostname …` handoff.
 - `hermes` is passthrough to native hermes CLI via `hermes.CLI()` (cmd/obol/hermes.go:27). No Go-level subcommands registered.
 - `bootstrap` (cmd/obol/bootstrap.go) is a hidden command for installer use only — not user-facing.
 

cmd/obol/tunnel_domain.go

@@ -3,11 +3,13 @@ package main
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"strings"
 
 	"github.com/ObolNetwork/obol-stack/internal/config"
 	"github.com/ObolNetwork/obol-stack/internal/tunnel"
+	"github.com/ObolNetwork/obol-stack/internal/ui"
 	"github.com/urfave/cli/v3"
 )
 
@@ -38,6 +40,8 @@ func tunnelCommand(cfg *config.Config) *cli.Command {
 					"Cloudflare dashboard, route its Public Hostname to\n" +
 					"http://traefik.traefik.svc.cluster.local:80, then paste the token here — you can\n" +
 					"paste the whole 'cloudflared tunnel run --token …' line and Obol extracts it.\n\n" +
+					"No domain yet? Register one from the CLI with 'obol domain', or buy/transfer one\n" +
+					"in the Cloudflare dashboard first — either way it must be a zone in your account.\n\n" +
 					"Advanced: '--management local' uses a browser login on this machine instead\n" +
 					"(needs cloudflared installed); 'obol tunnel login' is the same flow directly.",
 				Flags: tunnelSetupFlags(),
@@ -116,19 +120,45 @@ func tunnelCommand(cfg *config.Config) *cli.Command {
 func domainCommand(cfg *config.Config) *cli.Command {
 	return &cli.Command{
 		Name:  "domain",
-		Usage: "Search, check, and register Cloudflare Registrar domains",
+		Usage: "Search, check, and register Cloudflare Registrar domains (optional)",
+		Description: "Buying a domain through Obol is entirely optional — it's a convenience wrapper\n" +
+			"around Cloudflare Registrar so you can get a domain without leaving the CLI.\n" +
+			"If you'd rather, buy or transfer a domain in the Cloudflare dashboard before\n" +
+			"setting up a tunnel; anything that lands as a zone in your account works.\n\n" +
+			"These commands need a scoped Cloudflare API token (with the Account → Domain\n" +
+			"permission) — separate from the tunnel connector token — and registering a\n" +
+			"domain is billable, so your Cloudflare account needs a saved payment method.\n\n" +
+			"Once you own a domain, give your stack a permanent URL with 'obol tunnel setup'.",
 		Commands: []*cli.Command{
+			{
+				Name:  "list",
+				Usage: "List domains already registered in your Cloudflare account",
+				Flags: domainAuthFlags(),
+				Action: func(ctx context.Context, cmd *cli.Command) error {
+					u := getUI(cmd)
+					opts, err := domainListOptionsFromCommand(cmd, u)
+					if err != nil {
+						return err
+					}
+					result, err := tunnel.ListDomains(opts)
+					if err != nil {
+						return err
+					}
+					if u.IsJSON() {
+						return u.JSON(result)
+					}
+					printDomainList(u, result)
+					return nil
+				},
+			},
 			{
 				Name:  "search",
 				Usage: "Search for available Cloudflare Registrar domains",
-				Flags: []cli.Flag{
+				Flags: append([]cli.Flag{
 					&cli.StringFlag{Name: "query", Aliases: []string{"q"}, Usage: "Keyword, phrase, or domain to search for"},
 					&cli.StringSliceFlag{Name: "extensions", Usage: "Optional extension filter(s), e.g. --extensions com --extensions dev"},
 					&cli.IntFlag{Name: "limit", Usage: "Maximum number of suggestions to return", Value: 10},
-					&cli.StringFlag{Name: "account-id", Aliases: []string{"a"}, Usage: "Cloudflare account ID", Sources: cli.EnvVars("CLOUDFLARE_ACCOUNT_ID")},
-					&cli.StringFlag{Name: "api-token", Aliases: []string{"t"}, Usage: "Cloudflare API token", Sources: cli.EnvVars("CLOUDFLARE_API_TOKEN")},
-					&cli.StringFlag{Name: "from-json", Usage: "Read search options from JSON file (or - for stdin)"},
-				},
+				}, domainAuthFlags()...),
 				Action: func(ctx context.Context, cmd *cli.Command) error {
 					u := getUI(cmd)
 					opts, err := domainSearchOptionsFromCommand(cmd, u)
@@ -150,14 +180,10 @@ func domainCommand(cfg *config.Config) *cli.Command {
 				Name:      "check",
 				Usage:     "Check authoritative availability for one or more domains",
 				ArgsUsage: "<domain> [<domain> ...]",
-				Flags: []cli.Flag{
-					&cli.StringFlag{Name: "account-id", Aliases: []string{"a"}, Usage: "Cloudflare account ID", Sources: cli.EnvVars("CLOUDFLARE_ACCOUNT_ID")},
-					&cli.StringFlag{Name: "api-token", Aliases: []string{"t"}, Usage: "Cloudflare API token", Sources: cli.EnvVars("CLOUDFLARE_API_TOKEN")},
-					&cli.StringFlag{Name: "from-json", Usage: "Read check options from JSON file (or - for stdin)"},
-				},
+				Flags:     domainAuthFlags(),
 				Action: func(ctx context.Context, cmd *cli.Command) error {
 					u := getUI(cmd)
-					opts, err := domainCheckOptionsFromCommand(cmd)
+					opts, err := domainCheckOptionsFromCommand(cmd, u)
 					if err != nil {
 						return err
 					}
@@ -174,21 +200,18 @@ func domainCommand(cfg *config.Config) *cli.Command {
 			},
 			{
 				Name:      "register",
-				Usage:     "Register a domain through Cloudflare Registrar",
+				Usage:     "Register a domain through Cloudflare Registrar (billable)",
 				ArgsUsage: "<domain>",
-				Flags: []cli.Flag{
+				Flags: append([]cli.Flag{
 					&cli.IntFlag{Name: "years", Usage: "Registration term in years (default 1 or registry minimum)", Value: 1},
 					&cli.BoolFlag{Name: "auto-renew", Usage: "Enable automatic renewal"},
 					&cli.StringFlag{Name: "privacy-mode", Usage: "WHOIS privacy mode", Value: "redaction"},
 					&cli.BoolFlag{Name: "yes", Aliases: []string{"y"}, Usage: "Confirm the billable registration without prompting"},
-					&cli.BoolFlag{Name: "respond-async", Usage: "Request an immediate async workflow response from Cloudflare"},
-					&cli.StringFlag{Name: "account-id", Aliases: []string{"a"}, Usage: "Cloudflare account ID", Sources: cli.EnvVars("CLOUDFLARE_ACCOUNT_ID")},
-					&cli.StringFlag{Name: "api-token", Aliases: []string{"t"}, Usage: "Cloudflare API token", Sources: cli.EnvVars("CLOUDFLARE_API_TOKEN")},
-					&cli.StringFlag{Name: "from-json", Usage: "Read registration options from JSON file (or - for stdin)"},
-				},
+					&cli.BoolFlag{Name: "respond-async", Hidden: true, Usage: "Request an immediate async workflow response from Cloudflare"},
+				}, domainAuthFlags()...),
 				Action: func(ctx context.Context, cmd *cli.Command) error {
 					u := getUI(cmd)
-					opts, err := domainRegisterOptionsFromCommand(cmd)
+					opts, err := domainRegisterOptionsFromCommand(cmd, u)
 					if err != nil {
 						return err
 					}
@@ -207,6 +230,50 @@ func domainCommand(cfg *config.Config) *cli.Command {
 	}
 }
 
+// domainAuthFlags are the shared Cloudflare credential flags for `obol domain`.
+// Note: --api-token deliberately has no -t alias, to avoid colliding with
+// `obol tunnel setup -t` (which takes a tunnel connector token, a different
+// credential). The token here is a scoped Cloudflare API token.
+func domainAuthFlags() []cli.Flag {
+	return []cli.Flag{
+		&cli.StringFlag{Name: "account-id", Aliases: []string{"a"}, Usage: "Cloudflare account ID", Sources: cli.EnvVars("CLOUDFLARE_ACCOUNT_ID")},
+		&cli.StringFlag{Name: "api-token", Usage: "Cloudflare API token (Account → Domain permission)", Sources: cli.EnvVars("CLOUDFLARE_API_TOKEN")},
+		&cli.StringFlag{Name: "from-json", Usage: "Read options from JSON file (or - for stdin)"},
+	}
+}
+
+// resolveDomainAPIToken returns the Cloudflare API token from the flag/env or,
+// in an interactive session, walks the user through creating a scoped token and
+// prompts for it. This mirrors the tunnel connector-token flow.
+func resolveDomainAPIToken(u *ui.UI, supplied string) (string, error) {
+	if token := strings.TrimSpace(supplied); token != "" {
+		return token, nil
+	}
+
+	if !u.IsTTY() || u.IsJSON() {
+		return "", errors.New("a Cloudflare API token is required: pass --api-token or set CLOUDFLARE_API_TOKEN.\n" +
+			"Create one with the Account → Domain permission at https://dash.cloudflare.com/profile/api-tokens")
+	}
+
+	u.Blank()
+	u.Bold("Cloudflare API token needed")
+	u.Print("Managing Cloudflare Registrar domains from the CLI needs a scoped API token.")
+	u.Dim("This is a different credential from the tunnel connector token.")
+	u.Print("  1. Open https://dash.cloudflare.com/profile/api-tokens → Create Token")
+	u.Print("  2. Grant the Account → Domain permission (and select your account).")
+	u.Print("  3. Create the token and copy it.")
+	u.Blank()
+	token, err := u.SecretInput("Paste your Cloudflare API token")
+	if err != nil {
+		return "", err
+	}
+	token = strings.TrimSpace(token)
+	if token == "" {
+		return "", errors.New("no Cloudflare API token provided")
+	}
+	return token, nil
+}
+
 func tunnelTransportProtocolFlag() cli.Flag {
 	return &cli.StringFlag{
 		Name:  "transport-protocol",
@@ -252,10 +319,31 @@ func setupOptionsFromCommand(cmd *cli.Command) (tunnel.SetupOptions, error) {
 	}, nil
 }
 
-func domainSearchOptionsFromCommand(cmd *cli.Command, u interface {
-	Input(string, string) (string, error)
-},
-) (tunnel.DomainSearchOptions, error) {
+func domainListOptionsFromCommand(cmd *cli.Command, u *ui.UI) (tunnel.DomainListOptions, error) {
+	if jsonPath := cmd.String("from-json"); jsonPath != "" {
+		var opts tunnel.DomainListOptions
+		data, err := readJSONInput(jsonPath)
+		if err != nil {
+			return opts, err
+		}
+		if err := json.Unmarshal(data, &opts); err != nil {
+			return opts, fmt.Errorf("parse domain list JSON: %w", err)
+		}
+		return opts, nil
+	}
+
+	token, err := resolveDomainAPIToken(u, cmd.String("api-token"))
+	if err != nil {
+		return tunnel.DomainListOptions{}, err
+	}
+
+	return tunnel.DomainListOptions{
+		AccountID: cmd.String("account-id"),
+		APIToken:  token,
+	}, nil
+}
+
+func domainSearchOptionsFromCommand(cmd *cli.Command, u *ui.UI) (tunnel.DomainSearchOptions, error) {
 	if jsonPath := cmd.String("from-json"); jsonPath != "" {
 		var opts tunnel.DomainSearchOptions
 		data, err := readJSONInput(jsonPath)
@@ -277,16 +365,21 @@ func domainSearchOptionsFromCommand(cmd *cli.Command, u interface {
 		query = input
 	}
 
+	token, err := resolveDomainAPIToken(u, cmd.String("api-token"))
+	if err != nil {
+		return tunnel.DomainSearchOptions{}, err
+	}
+
 	return tunnel.DomainSearchOptions{
 		Query:      query,
 		Extensions: cmd.StringSlice("extensions"),
 		Limit:      cmd.Int("limit"),
 		AccountID:  cmd.String("account-id"),
-		APIToken:   cmd.String("api-token"),
+		APIToken:   token,
 	}, nil
 }
 
-func domainCheckOptionsFromCommand(cmd *cli.Command) (tunnel.DomainCheckOptions, error) {
+func domainCheckOptionsFromCommand(cmd *cli.Command, u *ui.UI) (tunnel.DomainCheckOptions, error) {
 	if jsonPath := cmd.String("from-json"); jsonPath != "" {
 		var opts tunnel.DomainCheckOptions
 		data, err := readJSONInput(jsonPath)
@@ -299,14 +392,19 @@ func domainCheckOptionsFromCommand(cmd *cli.Command) (tunnel.DomainCheckOptions,
 		return opts, nil
 	}
 
+	token, err := resolveDomainAPIToken(u, cmd.String("api-token"))
+	if err != nil {
+		return tunnel.DomainCheckOptions{}, err
+	}
+
 	return tunnel.DomainCheckOptions{
 		Domains:   cmd.Args().Slice(),
 		AccountID: cmd.String("account-id"),
-		APIToken:  cmd.String("api-token"),
+		APIToken:  token,
 	}, nil
 }
 
-func domainRegisterOptionsFromCommand(cmd *cli.Command) (tunnel.DomainRegisterOptions, error) {
+func domainRegisterOptionsFromCommand(cmd *cli.Command, u *ui.UI) (tunnel.DomainRegisterOptions, error) {
 	if jsonPath := cmd.String("from-json"); jsonPath != "" {
 		var opts tunnel.DomainRegisterOptions
 		data, err := readJSONInput(jsonPath)
@@ -319,6 +417,11 @@ func domainRegisterOptionsFromCommand(cmd *cli.Command) (tunnel.DomainRegisterOp
 		return opts, nil
 	}
 
+	token, err := resolveDomainAPIToken(u, cmd.String("api-token"))
+	if err != nil {
+		return tunnel.DomainRegisterOptions{}, err
+	}
+
 	return tunnel.DomainRegisterOptions{
 		DomainName:    cmd.Args().First(),
 		Years:         cmd.Int("years"),
@@ -327,62 +430,78 @@ func domainRegisterOptionsFromCommand(cmd *cli.Command) (tunnel.DomainRegisterOp
 		ConfirmCharge: cmd.Bool("yes"),
 		RespondAsync:  cmd.Bool("respond-async"),
 		AccountID:     cmd.String("account-id"),
-		APIToken:      cmd.String("api-token"),
+		APIToken:      token,
 	}, nil
 }
 
-func printDomainSuggestions(u interface {
-	Blank()
-	Bold(string)
-	Print(string)
-	Detail(string, string)
-}, result *tunnel.DomainSearchResult,
-) {
+func printDomainList(u *ui.UI, result *tunnel.DomainListResult) {
+	u.Blank()
+	u.Bold("Registered Domains")
+	if len(result.Domains) == 0 {
+		u.Print("No domains registered in this Cloudflare account.")
+		u.Dim("Find one with: obol domain search <keyword>")
+		return
+	}
+	for _, domain := range result.Domains {
+		u.Print("- " + domain.Name)
+		if domain.ExpiresAt != "" {
+			u.Detail("  Expires", domain.ExpiresAt)
+		}
+		renew := "off"
+		if domain.AutoRenew {
+			renew = "on"
+		}
+		u.Detail("  Auto-renew", renew)
+	}
+	u.Blank()
+	u.Dim("Give your stack a permanent URL on one of these: obol tunnel setup --hostname <subdomain>.<domain>")
+}
+
+func printDomainSuggestions(u *ui.UI, result *tunnel.DomainSearchResult) {
 	u.Blank()
 	u.Bold("Domain Suggestions")
+	registrable := false
 	for _, domain := range result.Domains {
 		summary := "not registrable"
 		if domain.Registrable {
 			summary = tunnelSummaryPrice(domain)
+			registrable = true
 		}
 		if domain.Reason != "" {
 			summary = summary + " — " + domain.Reason
 		}
 		u.Print("- " + domain.Name)
 		u.Detail("  Status", summary)
 	}
+	if registrable {
+		u.Blank()
+		u.Dim("Register one with: obol domain register <name>")
+	}
 }
 
-func printDomainChecks(u interface {
-	Blank()
-	Bold(string)
-	Print(string)
-	Detail(string, string)
-}, result *tunnel.DomainCheckResult,
-) {
+func printDomainChecks(u *ui.UI, result *tunnel.DomainCheckResult) {
 	u.Blank()
 	u.Bold("Domain Availability")
+	registrable := false
 	for _, domain := range result.Domains {
 		status := "not registrable"
 		if domain.Registrable {
 			status = tunnelSummaryPrice(domain)
+			registrable = true
 		}
 		if domain.Reason != "" {
 			status = status + " — " + domain.Reason
 		}
 		u.Print("- " + domain.Name)
 		u.Detail("  Status", status)
 	}
+	if registrable {
+		u.Blank()
+		u.Dim("Register one with: obol domain register <name>")
+	}
 }
 
-func printDomainRegistration(u interface {
-	Blank()
-	Bold(string)
-	Print(string)
-	Detail(string, string)
-	Successf(string, ...any)
-}, result *tunnel.DomainRegisterResult,
-) {
+func printDomainRegistration(u *ui.UI, result *tunnel.DomainRegisterResult) {
 	u.Blank()
 	u.Successf("Domain registration submitted for %s", result.Availability.Name)
 	u.Detail("Price", tunnelSummaryPrice(result.Availability))
@@ -395,6 +514,11 @@ func printDomainRegistration(u interface {
 			u.Detail("Domain Resource", result.Workflow.Links.Resource)
 		}
 	}
+	u.Blank()
+	u.Bold("Next: put your new domain to work")
+	u.Print("Give your stack a permanent public URL on it with a Cloudflare tunnel:")
+	u.Printf("  obol tunnel setup --hostname <subdomain>.%s", result.Availability.Name)
+	u.Dim("A Registrar domain is automatically a zone in your account — all the tunnel needs.")
 }
 
 func tunnelSummaryPrice(domain tunnel.CloudflareRegistrarDomainAlias) string {