relay-flow 0.2.8-alpha → 0.2.10-alpha

package/cmd/relay-flow/main.go

@@ -17,6 +17,7 @@ import (
 	"os/exec"
 	"os/signal"
 	"path/filepath"
+	"runtime"
 	"strings"
 	"syscall"
 	"time"
@@ -52,6 +53,14 @@ const (
 	exitUsage = 2
 )
 
+// Build metadata has safe local-build defaults and can be replaced by release
+// builds with -ldflags -X main.version=... and friends.
+var (
+	version   = "dev"
+	commit    = "unknown"
+	buildDate = "unknown"
+)
+
 func main() { os.Exit(run(os.Args[1:], os.Stdin)) }
 
 // home returns the relay-flow root, honoring RELAY_FLOW_HOME (tests and
@@ -81,6 +90,13 @@ func run(args []string, stdin io.Reader) int {
 		usage(os.Stderr)
 		return exitUsage
 	}
+	if isVersionArgs(args) {
+		printVersion(os.Stdout, len(args) == 1 && args[0] == "version")
+		return exitOK
+	}
+	if hasHelpArg(args) {
+		return printScopedHelp(args, os.Stdout)
+	}
 	p, err := home()
 	if err != nil {
 		fmt.Fprintln(os.Stderr, err)
@@ -133,28 +149,185 @@ func usage(w io.Writer) {
 	fmt.Fprintln(w, `relay-flow — durable ticket runner
 
 Usage:
+  relay-flow [command] [flags]
+
+Setup and server:
   relay-flow init [--force] [--task-plugin <name> --runner-plugin <name> --harness-plugin <name>]
                    [--executor-plugin <goworkflows|temporal>]
                    [--temporal-address <host:port>] [--temporal-namespace <name>]
+                   (interactive first run also authenticates and optionally registers repos)
   relay-flow task auth [task-plugin options]
   relay-flow serve [--recover] [--debug] [--background]
   relay-flow stop
   relay-flow report
+  relay-flow version | --version | -v
 
+Workflow:
   relay-flow workflow submit --file <path>
   relay-flow workflow remove --name <name>
-  relay-flow workflow list
-  relay-flow workflow get --name <name>
+  relay-flow workflow list [--json]
+  relay-flow workflow get --name <name> [--json]
 
+Repository:
   relay-flow repo register [--name <name> --path <path> --set key=value ...]
   relay-flow repo remove --name <name>
   relay-flow repo list
   relay-flow repo get --name <name>
 
-  relay-flow run list
-  relay-flow run get --ticket <key>
+Run:
+  relay-flow run list [--repo <name>] [--workflow <name>] [--ticket <key>] [--active] [--json]
+  relay-flow run get --ticket <key> [--json]
   relay-flow run restart --ticket <key>
-  relay-flow run cancel --ticket <key>`)
+  relay-flow run cancel --ticket <key>
+
+Examples:
+  relay-flow workflow list --json
+  relay-flow run get --ticket PAY-101
+Example: relay-flow run get --ticket PAY-101`)
+}
+
+func isVersionArgs(args []string) bool {
+	return len(args) == 1 && (args[0] == "version" || args[0] == "--version" || args[0] == "-v")
+}
+
+func hasHelpArg(args []string) bool {
+	for _, arg := range args {
+		if arg == "--help" || arg == "-h" {
+			return true
+		}
+	}
+	return false
+}
+
+func printVersion(w io.Writer, long bool) {
+	if !long {
+		fmt.Fprintf(w, "relay-flow %s\n", version)
+		return
+	}
+	fmt.Fprintf(w, "relay-flow %s\n", version)
+	fmt.Fprintf(w, "Commit: %s\n", commit)
+	fmt.Fprintf(w, "Build date: %s\n", buildDate)
+	fmt.Fprintf(w, "Go: %s\n", runtime.Version())
+	fmt.Fprintf(w, "Platform: %s/%s\n", runtime.GOOS, runtime.GOARCH)
+}
+
+func printScopedHelp(args []string, w io.Writer) int {
+	// Help is handled before home/config/client creation. Keep each block
+	// scoped to the requested command instead of dumping the entire surface.
+	path := make([]string, 0, len(args))
+	for _, arg := range args {
+		if arg == "--help" || arg == "-h" {
+			continue
+		}
+		// Command names are positional; once a flag appears, the remaining
+		// tokens are command arguments and must not change the help scope.
+		if strings.HasPrefix(arg, "-") {
+			break
+		}
+		path = append(path, arg)
+	}
+	if len(path) == 0 {
+		usage(w)
+		return exitOK
+	}
+	name := strings.Join(path, " ")
+	switch name {
+	case "init":
+		fmt.Fprintln(w, "Usage: relay-flow init [flags]")
+		fmt.Fprintln(w, "\nInitialize relay-flow and its durable state.")
+		fmt.Fprintln(w, "Flags: --force, --task-plugin, --runner-plugin, --harness-plugin, --executor-plugin")
+		fmt.Fprintln(w, "Example: relay-flow init --task-plugin jira --runner-plugin orca --harness-plugin opencode")
+	case "serve":
+		fmt.Fprintln(w, "Usage: relay-flow serve [--recover] [--debug] [--background]")
+		fmt.Fprintln(w, "\nStart the relay-flow server.")
+		fmt.Fprintln(w, "Example: relay-flow serve --background")
+	case "stop":
+		fmt.Fprintln(w, "Usage: relay-flow stop")
+		fmt.Fprintln(w, "\nStop the running relay-flow server.")
+		fmt.Fprintln(w, "Example: relay-flow stop")
+	case "report":
+		fmt.Fprintln(w, "Usage: relay-flow report < report.json")
+		fmt.Fprintln(w, "\nSubmit one complete structured node report.")
+		fmt.Fprintln(w, "Example: relay-flow report < report.json")
+	case "task":
+		fmt.Fprintln(w, "Usage: relay-flow task <command>")
+		fmt.Fprintln(w, "\nCommands: auth")
+		fmt.Fprintln(w, "Example: relay-flow task auth")
+	case "task auth":
+		fmt.Fprintln(w, "Usage: relay-flow task auth [task-plugin options]")
+		fmt.Fprintln(w, "\nDelegate authentication to the configured task-system plugin.")
+		fmt.Fprintln(w, "Example: relay-flow task auth")
+	case "runtime-register":
+		fmt.Fprintln(w, "Usage: relay-flow runtime-register < session.json")
+		fmt.Fprintln(w, "\nRegister a harness runtime session with the server.")
+		fmt.Fprintln(w, "Example: relay-flow runtime-register < session.json")
+	case "version":
+		fmt.Fprintln(w, "Usage: relay-flow version")
+		fmt.Fprintln(w, "\nPrint release and build metadata without contacting the server.")
+		fmt.Fprintln(w, "Example: relay-flow version")
+	case "workflow":
+		fmt.Fprintln(w, "Usage: relay-flow workflow <command>")
+		fmt.Fprintln(w, "\nCommands: submit, remove, list, get")
+		fmt.Fprintln(w, "Use relay-flow workflow <command> --help for command-specific flags.")
+		fmt.Fprintln(w, "Example: relay-flow workflow list --json")
+	case "workflow submit":
+		fmt.Fprintln(w, "Usage: relay-flow workflow submit --file <path>")
+		fmt.Fprintln(w, "\nCreate or replace a validated workflow definition.")
+		fmt.Fprintln(w, "Example: relay-flow workflow submit --file workflow.yaml")
+	case "workflow remove":
+		fmt.Fprintln(w, "Usage: relay-flow workflow remove --name <name>")
+		fmt.Fprintln(w, "\nRemove a workflow with no active runs.")
+		fmt.Fprintln(w, "Example: relay-flow workflow remove --name basicFlow")
+	case "workflow list":
+		fmt.Fprintln(w, "Usage: relay-flow workflow list [--json] [--no-color]")
+		fmt.Fprintln(w, "\nList configured workflows and their latest execution summaries.")
+		fmt.Fprintln(w, "Example: relay-flow workflow list --json")
+	case "workflow get":
+		fmt.Fprintln(w, "Usage: relay-flow workflow get --name <name> [--json] [--no-color]")
+		fmt.Fprintln(w, "\nShow validated static graph and recent runs. Use --json for automation.")
+		fmt.Fprintln(w, "Example: relay-flow workflow get --name basicFlow")
+	case "repo":
+		fmt.Fprintln(w, "Usage: relay-flow repo <command>")
+		fmt.Fprintln(w, "\nCommands: register, remove, list, get")
+		fmt.Fprintln(w, "Use relay-flow repo <command> --help for command-specific flags.")
+		fmt.Fprintln(w, "Example: relay-flow repo list")
+	case "repo register":
+		fmt.Fprintln(w, "Usage: relay-flow repo register [--name <name> --path <path> --set key=value]")
+		fmt.Fprintln(w, "\nRegister a runner repository and task-system configuration.")
+		fmt.Fprintln(w, "Example: relay-flow repo register --name payments --path /work/payments")
+	case "repo remove", "repo get":
+		fmt.Fprintf(w, "Usage: relay-flow %s --name <name>\n", name)
+		fmt.Fprintf(w, "Example: relay-flow %s --name payments\n", name)
+	case "repo list":
+		fmt.Fprintln(w, "Usage: relay-flow repo list")
+		fmt.Fprintln(w, "\nList registered repositories.")
+		fmt.Fprintln(w, "Example: relay-flow repo list")
+	case "run":
+		fmt.Fprintln(w, "Usage: relay-flow run <command>")
+		fmt.Fprintln(w, "\nCommands: list, get, restart, cancel")
+		fmt.Fprintln(w, "Use relay-flow run <command> --help for command-specific flags.")
+		fmt.Fprintln(w, "Example: relay-flow run get --ticket PAY-101")
+	case "run list":
+		fmt.Fprintln(w, "Usage: relay-flow run list [--repo <name>] [--workflow <name>] [--ticket <key>] [--active] [--json] [--no-color]")
+		fmt.Fprintln(w, "\nList durable runs. Use --json for automation.")
+		fmt.Fprintln(w, "Example: relay-flow run list --active --json")
+	case "run get":
+		fmt.Fprintln(w, "Usage: relay-flow run get --ticket <key> [--json] [--no-color]")
+		fmt.Fprintln(w, "\nShow an Argo-shaped execution detail view and actual step visits.")
+		fmt.Fprintln(w, "Example: relay-flow run get --ticket PAY-101")
+	case "run restart":
+		fmt.Fprintln(w, "Usage: relay-flow run restart --ticket <key>")
+		fmt.Fprintln(w, "\nStart a fresh attempt for a canceled run.")
+		fmt.Fprintln(w, "Example: relay-flow run restart --ticket PAY-101")
+	case "run cancel":
+		fmt.Fprintln(w, "Usage: relay-flow run cancel --ticket <key> [--reason <text>]")
+		fmt.Fprintln(w, "\nPermanently cancel the current execution attempt.")
+		fmt.Fprintln(w, "Example: relay-flow run cancel --ticket PAY-101 --reason "+`"operator request"`)
+	default:
+		fmt.Fprintf(os.Stderr, "unknown help target: %s\n", name)
+		return exitUsage
+	}
+	return exitOK
 }
 
 // --- init / serve delegate to the section-5 composition root ---
@@ -168,6 +341,14 @@ Usage:
 // a TTY → three stdin lines (task, runner, harness), the documented test
 // seam and script path.
 func cmdInit(p paths.Paths, args []string, stdin io.Reader) int {
+	if err := recoverFirstRunPublication(p); err != nil {
+		fmt.Fprintln(os.Stderr, "init: "+err.Error())
+		return exitFail
+	}
+	if err := cleanupFirstRunStaging(p); err != nil {
+		fmt.Fprintln(os.Stderr, "init: "+err.Error())
+		return exitFail
+	}
 	fs := flag.NewFlagSet("init", flag.ContinueOnError)
 	taskName := fs.String("task-plugin", "", "task plugin name (non-interactive)")
 	runnerName := fs.String("runner-plugin", "", "runner plugin name (non-interactive)")
@@ -206,11 +387,17 @@ func cmdInit(p paths.Paths, args []string, stdin io.Reader) int {
 		fmt.Fprintln(os.Stderr, "init: database is missing; refusing to recreate existing durable state")
 		return exitFail
 	}
-	if err := os.MkdirAll(p.Root, 0o700); err != nil {
-		fmt.Fprintln(os.Stderr, err)
-		return exitFail
+	// A first interactive setup keeps the final home untouched until the
+	// selected task plugin has authenticated successfully. Scripted setup and
+	// --force retain the existing eager directory creation behavior.
+	firstRunInteractive := !*force && !configExists && !databaseExists && !flagged && interactiveInitTTY(stdin)
+	if !firstRunInteractive {
+		if err := os.MkdirAll(p.Root, 0o700); err != nil {
+			fmt.Fprintln(os.Stderr, err)
+			return exitFail
+		}
+		_ = os.Chmod(p.Root, 0o700)
 	}
-	_ = os.Chmod(p.Root, 0o700)
 	var unlock func()
 	if *force {
 		unlock, err = lockForForcedInit(p.Lock)
@@ -240,9 +427,9 @@ func cmdInit(p paths.Paths, args []string, stdin io.Reader) int {
 	switch {
 	case flagged:
 		names = []string{*taskName, *runnerName, *harnessName}
-	case isTTY(stdin):
+	case interactiveInitTTY(stdin):
 		var err error
-		names, err = pickPluginsInteractive()
+		names, err = interactiveInitPluginPick()
 		if err != nil {
 			fmt.Fprintln(os.Stderr, "init: "+err.Error())
 			return exitFail
@@ -258,7 +445,7 @@ func cmdInit(p paths.Paths, args []string, stdin io.Reader) int {
 			return exitFail
 		}
 	}
-	if executor == executorTemporal && isTTY(stdin) {
+	if executor == executorTemporal && interactiveInitTTY(stdin) {
 		address, namespace, err := promptTemporalSettings(*temporalAddress, *temporalNamespace)
 		if err != nil {
 			fmt.Fprintln(os.Stderr, "init: "+err.Error())
@@ -353,6 +540,19 @@ func cmdInit(p paths.Paths, args []string, stdin io.Reader) int {
 	} else {
 		cfg.HarnessConfig = config.Merge(harnessDefaults, cfg.HarnessConfig)
 	}
+	var stagedAuthDir string
+	if firstRunInteractive {
+		if names[0] == "beads" {
+			fmt.Println("Beads authentication is managed by the Beads workspace and Dolt setup; relay-flow does not store task credentials.")
+		}
+		var authErr error
+		cfg, stagedAuthDir, authErr = stageFirstRunAuthentication(p, cfg, names[0], stdin)
+		if authErr != nil {
+			fmt.Fprintln(os.Stderr, "init: task auth: "+authErr.Error())
+			return exitFail
+		}
+		defer os.RemoveAll(stagedAuthDir)
+	}
 	identity := projection.ExecutorIdentity{
 		ExecutorPlugin:    executor,
 		TemporalAddress:   cfg.TemporalAddress,
@@ -373,13 +573,30 @@ func cmdInit(p paths.Paths, args []string, stdin io.Reader) int {
 			return exitFail
 		}
 	}
-	if !databaseExists {
+	if !firstRunInteractive && !databaseExists {
 		if err := projection.InitDatabaseWithIdentity(p.Database, identity); err != nil {
 			fmt.Fprintln(os.Stderr, "init: "+err.Error())
 			return exitFail
 		}
 	}
-	if err := config.SaveMachine(p.Config, cfg); err != nil {
+	if firstRunInteractive {
+		if err := commitFirstRun(p, stagedAuthDir, identity); err != nil {
+			fmt.Fprintln(os.Stderr, "init: "+err.Error())
+			return exitFail
+		}
+		register, err := interactiveInitRepoPrompt()
+		if err != nil {
+			fmt.Fprintln(os.Stderr, "init: "+err.Error())
+			return exitFail
+		}
+		if register {
+			if err := interactiveInitRepoSetup(p, stdin); err != nil {
+				fmt.Fprintln(os.Stderr, "init: "+err.Error())
+				return exitFail
+			}
+			fmt.Println("Repository setup complete. The server is running; stop it with `relay-flow stop`.")
+		}
+	} else if err := config.SaveMachine(p.Config, cfg); err != nil {
 		fmt.Fprintln(os.Stderr, err)
 		return exitFail
 	}
@@ -540,55 +757,121 @@ func cmdServe(p paths.Paths, args []string) int {
 	return exitOK
 }
 
+var (
+	backgroundServeStartupTimeout = 10 * time.Second
+	backgroundServePollInterval   = 50 * time.Millisecond
+)
+
 func startBackgroundServe(p paths.Paths, recover, debug bool) error {
 	client := server.NewClient(p.Socket)
 	if serverResponding(client, 200*time.Millisecond) {
 		return fmt.Errorf("serve --background: server is already running")
 	}
-	executable, err := os.Executable()
+	deadline := time.Now().Add(backgroundServeStartupTimeout)
+	lockHeld, err := serverLockHeld(p.Lock)
 	if err != nil {
-		return fmt.Errorf("serve --background: resolve executable: %w", err)
+		return fmt.Errorf("serve --background: inspect server lock: %w", err)
 	}
-	childArgs := []string{"serve"}
-	if recover {
-		childArgs = append(childArgs, "--recover")
-	}
-	if debug {
-		childArgs = append(childArgs, "--debug")
+
+	var (
+		cmd           *exec.Cmd
+		wait          chan error
+		observedOwner = lockHeld
+		devNull       *os.File
+	)
+	if !lockHeld {
+		executable, resolveErr := os.Executable()
+		if resolveErr != nil {
+			return fmt.Errorf("serve --background: resolve executable: %w", resolveErr)
+		}
+		childArgs := []string{"serve"}
+		if recover {
+			childArgs = append(childArgs, "--recover")
+		}
+		if debug {
+			childArgs = append(childArgs, "--debug")
+		}
+		devNull, err = os.OpenFile(os.DevNull, os.O_RDWR, 0)
+		if err != nil {
+			return fmt.Errorf("serve --background: open %s: %w", os.DevNull, err)
+		}
+		defer devNull.Close()
+		cmd = exec.Command(executable, childArgs...)
+		cmd.Stdin, cmd.Stdout, cmd.Stderr = devNull, devNull, devNull
+		cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
+		if err := cmd.Start(); err != nil {
+			return fmt.Errorf("serve --background: start: %w; see %s", err, p.ServerLog)
+		}
+		wait = make(chan error, 1)
+		go func() { wait <- cmd.Wait() }()
 	}
-	devNull, err := os.OpenFile(os.DevNull, os.O_RDWR, 0)
-	if err != nil {
-		return fmt.Errorf("serve --background: open %s: %w", os.DevNull, err)
-	}
-	defer devNull.Close()
-	cmd := exec.Command(executable, childArgs...)
-	cmd.Stdin, cmd.Stdout, cmd.Stderr = devNull, devNull, devNull
-	cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
-	if err := cmd.Start(); err != nil {
-		return fmt.Errorf("serve --background: start: %w; see %s", err, p.ServerLog)
-	}
-	wait := make(chan error, 1)
-	go func() { wait <- cmd.Wait() }()
-	deadline := time.NewTimer(10 * time.Second)
-	defer deadline.Stop()
-	ticker := time.NewTicker(50 * time.Millisecond)
+
+	ticker := time.NewTicker(backgroundServePollInterval)
 	defer ticker.Stop()
 	for {
-		select {
-		case err := <-wait:
-			return fmt.Errorf("serve --background: server exited before readiness: %v; see %s", err, p.ServerLog)
-		case <-deadline.C:
-			_ = cmd.Process.Kill()
-			<-wait
+		if serverResponding(client, 200*time.Millisecond) {
+			return nil
+		}
+		if !time.Now().Before(deadline) {
+			if cmd != nil && wait != nil {
+				_ = cmd.Process.Kill()
+				<-wait
+			}
 			return fmt.Errorf("serve --background: startup timed out; see %s", p.ServerLog)
-		case <-ticker.C:
-			if serverResponding(client, 200*time.Millisecond) {
-				return nil
+		}
+		if observedOwner && wait == nil {
+			held, lockErr := serverLockHeld(p.Lock)
+			if lockErr != nil {
+				return fmt.Errorf("serve --background: inspect server lock: %w", lockErr)
+			}
+			if !held {
+				return fmt.Errorf("serve --background: server exited before readiness; see %s", p.ServerLog)
+			}
+		}
+		select {
+		case childErr := <-wait:
+			held, lockErr := serverLockHeld(p.Lock)
+			if lockErr != nil {
+				return fmt.Errorf("serve --background: inspect server lock: %w", lockErr)
+			}
+			if held {
+				// Another process acquired the lock while this child was
+				// starting. Wait for that owner instead of spawning again.
+				observedOwner = true
+				wait = nil
+				cmd = nil
+				continue
 			}
+			return fmt.Errorf("serve --background: server exited before readiness: %v; see %s", childErr, p.ServerLog)
+		case <-ticker.C:
 		}
 	}
 }
 
+func serverLockHeld(path string) (bool, error) {
+	f, err := os.OpenFile(path, os.O_CREATE|os.O_RDWR, 0o600)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return false, nil
+		}
+		return false, err
+	}
+	defer f.Close()
+	if err := f.Chmod(0o600); err != nil {
+		return false, err
+	}
+	if err := syscall.Flock(int(f.Fd()), syscall.LOCK_EX|syscall.LOCK_NB); err != nil {
+		if err == syscall.EWOULDBLOCK || err == syscall.EAGAIN {
+			return true, nil
+		}
+		return false, err
+	}
+	if err := syscall.Flock(int(f.Fd()), syscall.LOCK_UN); err != nil {
+		return false, err
+	}
+	return false, nil
+}
+
 func serverResponding(client *server.Client, timeout time.Duration) bool {
 	ctx, cancel := context.WithTimeout(context.Background(), timeout)
 	defer cancel()
@@ -690,21 +973,28 @@ func cmdWorkflow(c *server.Client, args []string) int {
 		return exitOK
 	case "list":
 		fs := flag.NewFlagSet("workflow list", flag.ContinueOnError)
+		jsonOutput := fs.Bool("json", false, "print stable JSON")
+		fs.Bool("no-color", false, "disable terminal colors")
 		if err := fs.Parse(args[1:]); err != nil {
 			return exitUsage
 		}
-		wfs, err := c.ListWorkflows(context.Background())
+		finishLoading := beginLoading("Loading workflows", *jsonOutput)
+		summaries, err := c.ListWorkflowSummaries(context.Background())
+		finishLoading(err)
 		if err != nil {
 			fmt.Fprintln(os.Stderr, err)
 			return exitFail
 		}
-		for _, wf := range wfs {
-			fmt.Println(wf.Name)
+		if *jsonOutput {
+			return encodeJSON(summaries)
 		}
+		renderWorkflowSummaries(os.Stdout, summaries, cliRenderOptions())
 		return exitOK
 	case "get":
 		fs := flag.NewFlagSet("workflow get", flag.ContinueOnError)
 		name := fs.String("name", "", "workflow name")
+		jsonOutput := fs.Bool("json", false, "print stable JSON")
+		fs.Bool("no-color", false, "disable terminal colors")
 		if err := fs.Parse(args[1:]); err != nil {
 			return exitUsage
 		}
@@ -712,14 +1002,23 @@ func cmdWorkflow(c *server.Client, args []string) int {
 			fmt.Fprintln(os.Stderr, "workflow get: --name is required")
 			return exitUsage
 		}
-		wf, err := c.GetWorkflow(context.Background(), *name)
+		finishLoading := beginLoading("Loading workflow", *jsonOutput)
+		if *jsonOutput {
+			wf, err := c.GetWorkflow(context.Background(), *name)
+			finishLoading(err)
+			if err != nil {
+				fmt.Fprintln(os.Stderr, err)
+				return exitFail
+			}
+			return encodeJSON(wf)
+		}
+		detail, err := c.GetWorkflowDetail(context.Background(), *name)
+		finishLoading(err)
 		if err != nil {
 			fmt.Fprintln(os.Stderr, err)
 			return exitFail
 		}
-		enc := json.NewEncoder(os.Stdout)
-		enc.SetIndent("", "  ")
-		_ = enc.Encode(wf)
+		renderWorkflowDetail(os.Stdout, detail, cliRenderOptions())
 		return exitOK
 	}
 	usage(os.Stderr)
@@ -811,7 +1110,7 @@ func cmdRepoRegister(c *server.Client, flagName, flagPath string, sets kvFlags,
 		}
 		registration, err := loadRepoRegistration(ctx, c, sets)
 		if err != nil {
-			fmt.Fprintln(os.Stderr, err)
+			fmt.Fprintln(os.Stderr, standaloneRepoServerHint(err))
 			return exitFail
 		}
 		taskCfg, err := registrationTaskConfig(registration, sets, flagName)
@@ -821,7 +1120,7 @@ func cmdRepoRegister(c *server.Client, flagName, flagPath string, sets kvFlags,
 		}
 		info, err := c.RegisterRepo(ctx, repo.RegisterInput{Name: flagName, Path: flagPath, TaskConfig: taskCfg})
 		if err != nil {
-			fmt.Fprintln(os.Stderr, err)
+			fmt.Fprintln(os.Stderr, standaloneRepoServerHint(err))
 			return exitFail
 		}
 		fmt.Println(info.Name)
@@ -830,7 +1129,7 @@ func cmdRepoRegister(c *server.Client, flagName, flagPath string, sets kvFlags,
 
 	registration, err := c.RepoRegistrationFields(ctx, nil)
 	if err != nil {
-		fmt.Fprintln(os.Stderr, err)
+		fmt.Fprintln(os.Stderr, standaloneRepoServerHint(err))
 		return exitFail
 	}
 
@@ -840,23 +1139,17 @@ func cmdRepoRegister(c *server.Client, flagName, flagPath string, sets kvFlags,
 	}
 	candidates, err := c.DiscoverRepos(ctx)
 	if err != nil {
-		fmt.Fprintln(os.Stderr, err)
+		fmt.Fprintln(os.Stderr, standaloneRepoServerHint(err))
 		return exitFail
 	}
-	if len(candidates) == 0 {
-		fmt.Fprintln(os.Stderr, "repo register: runner discovered no repos")
+	registered, err := c.ListRepos(ctx)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, standaloneRepoServerHint(err))
 		return exitFail
 	}
-
-	selected := []int{}
-	options := make([]huh.Option[int], len(candidates))
-	for i, cand := range candidates {
-		options[i] = huh.NewOption(cand.Name+"  ("+cand.Path+")", i)
-	}
-	pickField := repoMultiSelect(options, &selected)
-	pick := huh.NewForm(huh.NewGroup(pickField))
-	if err := pick.Run(); err != nil {
-		fmt.Fprintln(os.Stderr, "repo register: "+err.Error())
+	candidates, selected, err := selectReposInteractive(ctx, c, candidates, registered)
+	if err != nil {
+		fmt.Fprintln(os.Stderr, "repo register: "+standaloneRepoServerHint(err).Error())
 		return exitFail
 	}
 
@@ -868,7 +1161,7 @@ func cmdRepoRegister(c *server.Client, flagName, flagPath string, sets kvFlags,
 	if len(shared) > 0 {
 		dependent, err := c.RepoRegistrationFields(ctx, flatRegistrationValues(shared))
 		if err != nil {
-			fmt.Fprintln(os.Stderr, err)
+			fmt.Fprintln(os.Stderr, standaloneRepoServerHint(err))
 			return exitFail
 		}
 		registration = mergeRegistration(registration, dependent)
@@ -878,7 +1171,7 @@ func cmdRepoRegister(c *server.Client, flagName, flagPath string, sets kvFlags,
 		}
 	}
 	if err := registerSelectedReposDynamic(ctx, c, candidates, selected, registration, shared); err != nil {
-		fmt.Fprintln(os.Stderr, "repo register: "+err.Error())
+		fmt.Fprintln(os.Stderr, "repo register: "+standaloneRepoServerHint(err).Error())
 		return exitFail
 	}
 	return exitOK
@@ -887,6 +1180,8 @@ func cmdRepoRegister(c *server.Client, flagName, flagPath string, sets kvFlags,
 func repoMultiSelect(options []huh.Option[int], selected *[]int) *huh.MultiSelect[int] {
 	return huh.NewMultiSelect[int]().
 		Title("Select repositories").
+		Description("Press / to filter repositories; select [+] Add repository to add a runner resource.").
+		Filterable(true).
 		Options(options...).
 		Value(selected).
 		Validate(func(values []int) error {
@@ -927,25 +1222,35 @@ func cmdRun(c *server.Client, args []string) int {
 		repoName := fs.String("repo", "", "filter by repo")
 		workflowName := fs.String("workflow", "", "filter by workflow")
 		ticket := fs.String("ticket", "", "filter by ticket")
+		activeOnly := fs.Bool("active", false, "show only active runs")
+		jsonOutput := fs.Bool("json", false, "print stable JSON")
+		fs.Bool("no-color", false, "disable terminal colors")
 		if err := fs.Parse(args[1:]); err != nil {
 			return exitUsage
 		}
-		runs, err := c.ListRuns(context.Background(), runsvc.Filter{
-			Repo:     *repoName,
-			Workflow: *workflowName,
-			Ticket:   *ticket,
-		})
+		var active *bool
+		if *activeOnly {
+			value := true
+			active = &value
+		}
+		filter := runsvc.Filter{Repo: *repoName, Workflow: *workflowName, Ticket: *ticket, Active: active}
+		finishLoading := beginLoading("Loading runs", *jsonOutput)
+		runs, err := c.ListRuns(context.Background(), filter)
+		finishLoading(err)
 		if err != nil {
 			fmt.Fprintln(os.Stderr, err)
 			return exitFail
 		}
-		for _, r := range runs {
-			fmt.Println(formatRunListRow(r))
+		if *jsonOutput {
+			return encodeJSON(runs)
 		}
+		renderRunsFiltered(os.Stdout, runs, cliRenderOptions(), filter)
 		return exitOK
 	case "get":
 		fs := flag.NewFlagSet("run get", flag.ContinueOnError)
 		ticket := fs.String("ticket", "", "ticket key")
+		jsonOutput := fs.Bool("json", false, "print stable JSON")
+		fs.Bool("no-color", false, "disable terminal colors")
 		if err := fs.Parse(args[1:]); err != nil {
 			return exitUsage
 		}
@@ -953,14 +1258,17 @@ func cmdRun(c *server.Client, args []string) int {
 			fmt.Fprintln(os.Stderr, "run get: --ticket is required")
 			return exitUsage
 		}
-		rn, err := c.GetRunByTicket(context.Background(), *ticket)
+		finishLoading := beginLoading("Loading run", *jsonOutput)
+		detail, err := c.GetRunDetailByTicket(context.Background(), *ticket)
+		finishLoading(err)
 		if err != nil {
 			fmt.Fprintln(os.Stderr, err)
 			return exitFail
 		}
-		enc := json.NewEncoder(os.Stdout)
-		enc.SetIndent("", "  ")
-		_ = enc.Encode(rn)
+		if *jsonOutput {
+			return encodeJSON(detail)
+		}
+		renderRunDetail(os.Stdout, detail, cliRenderOptions())
 		return exitOK
 	case "restart":
 		fs := flag.NewFlagSet("run restart", flag.ContinueOnError)