feat(repo): show repository columns, state and README

repo list and search repo printed bare names. They now render a table
with NAME, DESCRIPTION, INFO (public or private, fork, mirror, template,
archived, empty) and UPDATED under "Showing N of M repositories ...", an
empty-state message on stderr, and tab-separated rows with the URL when
piped. --type, --sort and --order complete and validate their values.

repo view shows the visibility and kind badges, stars, forks, open
issues and pull requests, the parent of a fork, the source of a mirror,
the default branch and the clone URLs, followed by the README of the
default branch (or --branch), rendered on a terminal. The repository
JSON gains empty, stars_count, forks_count, open_issues_count,
open_pr_count, topics and updated_at.

Signed-off-by: bircni <bircni@icloud.com>

internal/app/app_test.go

@@ -511,13 +511,10 @@ const (
 	repo delete
 	repo edit
 	repo fork
-	repo list
 	repo migrate
 	repo set-default
-	repo view
 	search issue
 	search pr
-	search repo
 	status
 	time create
 	time delete
@@ -543,8 +540,6 @@ const (
 	pr comment
 	release
 	release asset
-	repo
-	search
 	time
 	wiki
 `

internal/app/repos.go

@@ -5,6 +5,7 @@ package app
 
 import (
 	"errors"
+	"fmt"
 	"strings"
 
 	"gitea.dev/tea/internal/clierr"
@@ -14,6 +15,10 @@ import (
 	"github.com/spf13/cobra"
 )
 
+// repositoryArguments documents the [<repository>] argument of repository commands.
+const repositoryArguments = `A repository can be supplied as NAME (one of yours), OWNER/NAME, HOST/OWNER/NAME or a URL.
+Without an argument, the repository of the current Git clone is used.`
+
 // repositoryArgument selects the repository from an optional positional owner/name or URL.
 func (a *application) repositoryArgument(args []string) error {
 	if len(args) == 0 {
@@ -40,75 +45,13 @@ func (a *application) rejectRepoFlag(cmd *cobra.Command, suggest func(owner stri
 }
 
 func (a *application) repoCommand() *cobra.Command {
-	group := &cobra.Command{Use: "repo", Short: "Work with Gitea repositories"}
-	var opts services.RepositoryListOptions
-	list := &cobra.Command{Use: "list [<owner>]", Short: "List your repositories", Args: usageArgs(cobra.MaximumNArgs(1)), RunE: func(cmd *cobra.Command, args []string) error {
-		if err := a.rejectRepoFlag(cmd, func(owner string) string { return "tea repo list " + owner }); err != nil {
-			return err
-		}
-		if len(args) > 0 {
-			if cmd.Flags().Changed("owner") {
-				return clierr.Wrap(clierr.Usage, errors.New("supply the owner as an argument or --owner, not both"))
-			}
-			opts.Owner = args[0]
-		}
-		if err := validateRepositoryKind(opts.Kind); err != nil {
-			return err
-		}
-		scopes := 0
-		for _, selected := range []bool{opts.Owner != "", opts.Starred, opts.Watched} {
-			if selected {
-				scopes++
-			}
-		}
-		if scopes > 1 {
-			return clierr.Wrap(clierr.Usage, errors.New("--owner, --starred, and --watched select mutually exclusive collections"))
-		}
-		target, err := a.resolve(cmd.Context(), false)
-		if err != nil {
-			return err
-		}
-		items, more, err := (services.Repositories{Client: target.client}).List(cmd.Context(), opts)
-		if err != nil {
-			return err
-		}
-		if err := writeList(a, cmd, items, func(item services.Repository) []terminal.Cell {
-			return []terminal.Cell{{Text: item.FullName, Link: item.URL}}
-		}); err != nil {
-			return err
-		}
-		return a.morePagesHint(cmd, more, opts.Page)
-	}}
-	pageFlags(list, &opts.Limit, &opts.Page)
-	list.Flags().StringVar(&opts.Owner, "owner", "", "List repositories belonging to this user or organization")
-	list.Flags().StringVar(&opts.Kind, "type", "", "Repository kind: fork, source, mirror")
-	list.Flags().BoolVar(&opts.Starred, "starred", false, "List your starred repositories")
-	list.Flags().BoolVar(&opts.Watched, "watched", false, "List your watched repositories")
-	group.AddCommand(list, a.repositorySyncCommand())
-	var web bool
-	view := &cobra.Command{Use: "view [repository]", Short: "View the selected repository", Args: usageArgs(cobra.MaximumNArgs(1)), RunE: func(cmd *cobra.Command, args []string) error {
-		if err := a.repositoryArgument(args); err != nil {
-			return err
-		}
-		target, err := a.resolve(cmd.Context(), true)
-		if err != nil {
-			return err
-		}
-		item, err := (services.Repositories{Client: target.client}).View(cmd.Context(), target.Repo)
-		if err != nil {
-			return err
-		}
-		if web {
-			return a.openBrowser(cmd, item.URL)
-		}
-		return writeRecord(a, cmd, item, func(item services.Repository) terminal.Record {
-			record := repositoryRecord(item)
-			record.Lines = append([]string{terminal.SafeLine(item.Description)}, record.Lines...)
-			return record
-		})
-	}}
-	view.Flags().BoolVar(&web, "web", false, "Open the repository in a browser")
-	group.AddCommand(view)
+	group := &cobra.Command{
+		Use:   "repo",
+		Short: "Work with Gitea repositories",
+		Long: `Work with Gitea repositories: list and view them, create, fork, clone and migrate them, keep
+local branches and forks in sync, and change their settings.`,
+	}
+	group.AddCommand(a.repoListCommand(), a.repoViewCommand(), a.repositorySyncCommand())
 	group.AddCommand(&cobra.Command{Use: "set-default [repository]", Short: "Save the selected repository in local Git configuration", Annotations: textOutput("set-default configures Git"), Args: usageArgs(cobra.MaximumNArgs(1)), RunE: func(cmd *cobra.Command, args []string) error {
 		if err := a.repositoryArgument(args); err != nil {
 			return err
@@ -123,3 +66,212 @@ func (a *application) repoCommand() *cobra.Command {
 	a.addRepositoryMutations(group)
 	return group
 }
+
+func (a *application) repoListCommand() *cobra.Command {
+	var opts services.RepositoryListOptions
+	list := &cobra.Command{
+		Use:   "list [<owner>]",
+		Short: "List repositories",
+		Long: `List the repositories you can access, those of a user or organization, or the repositories you
+starred or watch.`,
+		Example: `# List the repositories you can access
+$ tea repo list
+
+# List the forks of an organization
+$ tea repo list acme --type fork
+
+# List your starred repositories as JSON
+$ tea repo list --starred --json full_name,url`,
+		Args: usageArgs(cobra.MaximumNArgs(1)),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if err := a.rejectRepoFlag(cmd, func(owner string) string { return "tea repo list " + owner }); err != nil {
+				return err
+			}
+			if len(args) > 0 {
+				if cmd.Flags().Changed("owner") {
+					return clierr.Wrap(clierr.Usage, errors.New("supply the owner as an argument or --owner, not both"))
+				}
+				opts.Owner = args[0]
+			}
+			scopes := 0
+			for _, selected := range []bool{opts.Owner != "", opts.Starred, opts.Watched} {
+				if selected {
+					scopes++
+				}
+			}
+			if scopes > 1 {
+				return clierr.Wrap(clierr.Usage, errors.New("an owner, --starred and --watched select different collections; pass one"))
+			}
+			target, err := a.resolve(cmd.Context(), false)
+			if err != nil {
+				return err
+			}
+			result, err := (services.Repositories{Client: target.client}).ListPage(cmd.Context(), opts)
+			if err != nil {
+				return err
+			}
+			collection := repositoryCollection(opts)
+			spec := listSpec[services.Repository]{Columns: repositoryColumns, Row: repositoryRow, Context: collection, Empty: "no " + collection}
+			return writeTable(a, cmd, result.Items, spec, listPage{Number: opts.Page, More: result.More, Total: result.Total, Counted: result.Counted})
+		},
+	}
+	pageFlags(list, &opts.Limit, &opts.Page)
+	list.Flags().StringVar(&opts.Owner, "owner", "", "List the repositories of this user or organization")
+	_ = list.Flags().MarkHidden("owner")
+	enumFlag(list, &opts.Kind, "type", "", "", "Only list repositories of this kind", "fork", "source", "mirror")
+	list.Flags().BoolVar(&opts.Starred, "starred", false, "List your starred repositories")
+	list.Flags().BoolVar(&opts.Watched, "watched", false, "List the repositories you watch")
+	_ = list.RegisterFlagCompletionFunc("owner", a.completeOrgs())
+	list.ValidArgsFunction = a.completeOrgs()
+	return list
+}
+
+// repositoryCollection names the repositories that repo list selects, as in "forks owned by acme".
+func repositoryCollection(opts services.RepositoryListOptions) string {
+	kinds := map[string]string{"fork": "forks", "mirror": "mirrors", "source": "source repositories"}
+	noun, ok := kinds[opts.Kind]
+	if !ok {
+		noun = "repositories"
+	}
+	switch {
+	case opts.Owner != "":
+		return noun + " owned by " + opts.Owner
+	case opts.Starred:
+		return "starred " + noun
+	case opts.Watched:
+		return "watched " + noun
+	}
+	return noun + " you can access"
+}
+
+// repositoryColumns head the rows of repositoryRow in repo list and search repo.
+var repositoryColumns = []terminal.Column{{Header: "Name"}, {Header: "Description", Flex: true}, {Header: "Info"}, {Header: "Updated"}, {Header: "URL", PipedOnly: true}}
+
+func repositoryRow(item services.Repository) []terminal.Cell {
+	return []terminal.Cell{{Text: item.FullName, Link: item.URL}, {Text: item.Description}, {Text: strings.Join(repositoryInfo(item), ", ")}, {Time: terminal.ParseTime(item.UpdatedAt)}, {Text: item.URL}}
+}
+
+// repositoryInfo describes the visibility and the kind of a repository: public or private, then
+// fork, mirror, template, archived or empty.
+func repositoryInfo(item services.Repository) []string {
+	info := []string{"public"}
+	if item.Private {
+		info[0] = "private"
+	}
+	for _, kind := range []struct {
+		is   bool
+		name string
+	}{{item.Fork, "fork"}, {item.Mirror, "mirror"}, {item.Template, "template"}, {item.Archived, "archived"}, {item.Empty, "empty"}} {
+		if kind.is {
+			info = append(info, kind.name)
+		}
+	}
+	return info
+}
+
+func (a *application) repoViewCommand() *cobra.Command {
+	var web bool
+	var branch string
+	view := &cobra.Command{
+		Use:   "view [<repository>]",
+		Short: "View a repository",
+		Long: `View a repository: its description, state, counts and clone URLs, followed by its README, which
+is rendered on a terminal.`,
+		Example: `# View the repository of the current clone
+$ tea repo view
+
+# View the README of another branch
+$ tea repo view alice/project --branch develop
+
+# Open the repository in the browser
+$ tea repo view alice/project --web`,
+		Annotations: map[string]string{"tea.arguments": repositoryArguments},
+		Args:        usageArgs(cobra.MaximumNArgs(1)),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if err := a.repositoryArgument(args); err != nil {
+				return err
+			}
+			target, err := a.resolve(cmd.Context(), true)
+			if err != nil {
+				return err
+			}
+			service := services.Repositories{Client: target.client}
+			item, err := service.View(cmd.Context(), target.Repo)
+			if err != nil {
+				return err
+			}
+			if web {
+				return a.openBrowser(cmd, item.URL)
+			}
+			readme := ""
+			if a.options.json == "" && !item.Empty {
+				if _, readme, err = service.Readme(cmd.Context(), target.Repo, branch); err != nil {
+					return err
+				}
+			}
+			return writeView(a, cmd, item, func(item services.Repository) terminal.View { return a.repositoryView(item, readme) })
+		},
+	}
+	view.Flags().BoolVarP(&web, "web", "w", false, "Open the repository in the browser")
+	view.Flags().StringVarP(&branch, "branch", "b", "", "Show the README of this branch (default: the default branch)")
+	_ = view.RegisterFlagCompletionFunc("branch", a.completeBranches())
+	view.ValidArgsFunction = a.completeRepos()
+	return view
+}
+
+// repositoryView shows a repository with its README as the body.
+func (a *application) repositoryView(item services.Repository, readme string) terminal.View {
+	badges := []terminal.Cell{{Text: "public", Color: "green"}}
+	if item.Private {
+		badges[0] = terminal.Cell{Text: "private", Color: "yellow"}
+	}
+	for _, kind := range repositoryInfo(item)[1:] {
+		badge := terminal.Cell{Text: kind, Muted: true}
+		if kind == "archived" {
+			badge = terminal.Cell{Text: "archived (read-only)", Color: "yellow"}
+		}
+		badges = append(badges, badge)
+	}
+	meta := []string{
+		fmt.Sprintf("★ %d", item.Stars), countNoun(item.Forks, "fork"), countNoun(item.OpenIssues, "open issue"),
+		countNoun(item.OpenPulls, "open pull request"),
+	}
+	if updated := terminal.ParseTime(item.UpdatedAt); !updated.IsZero() {
+		meta = append(meta, "updated "+terminal.RelativeTime(a.deps.Now(), updated))
+	}
+	view := terminal.View{
+		Title: item.FullName, Badges: badges, Meta: strings.Join(meta, " · "), Body: readme, Kind: "repository", URL: item.URL,
+		Fields: []terminal.Field{
+			{Label: "Description", Value: item.Description},
+			{Label: "Forked from", Value: parentName(item)},
+			{Label: "Mirror of", Value: mirrorSourceURL(item)},
+			{Label: "Default branch", Value: item.DefaultBranch},
+			{Label: "Website", Value: item.Website},
+			{Label: "Topics", Value: strings.Join(item.Topics, ", ")},
+			{Label: "Clone", Value: item.CloneURL},
+			{Label: "SSH", Value: item.SSHURL},
+		},
+	}
+	if a.deps.Streams.OutTTY && strings.TrimSpace(readme) == "" {
+		view.Body = "_This repository has no README._"
+		if item.Empty {
+			view.Body = "_This repository is empty._"
+		}
+	}
+	return view
+}
+
+func parentName(item services.Repository) string {
+	if item.Parent == nil {
+		return ""
+	}
+	return item.Parent.FullName
+}
+
+// countNoun counts n of a noun, as in "1 fork" or "3 forks".
+func countNoun(n int, noun string) string {
+	if n == 1 {
+		return "1 " + noun
+	}
+	return fmt.Sprintf("%d %ss", n, noun)
+}

internal/app/repos_test.go

@@ -5,14 +5,114 @@ package app
 
 import (
 	"bytes"
+	"context"
+	"net/http"
 	"testing"
+	"time"
+
+	"github.com/stretchr/testify/require"
 )
 
-// repoTTYDeps returns serverDeps for a 100-column terminal without color or links, as people read tea's output.
+// repoTTYDeps returns serverDeps for a 100-column terminal without color or links, as people read
+// tea's output, at a fixed time.
 func repoTTYDeps(t *testing.T, serverURL string) (Dependencies, *bytes.Buffer, *bytes.Buffer) {
 	t.Helper()
 	deps, out, diagnostics := serverDeps(t, serverURL)
 	deps.Getenv = serverEnv(serverURL, map[string]string{"TERM": "dumb"})
 	deps.Streams.OutTTY, deps.Streams.Width = true, 100
+	deps.Now = func() time.Time { return time.Date(2026, 10, 11, 20, 0, 0, 0, time.UTC) }
 	return deps, out, diagnostics
 }
+
+const listedRepositories = `[
+	{"full_name":"alice/old-stuff","description":"Archived repository","archived":true,"html_url":"https://gitea.test/alice/old-stuff","updated_at":"2026-10-11T18:00:00Z"},
+	{"full_name":"acme/service","private":true,"fork":true,"html_url":"https://gitea.test/acme/service","updated_at":"2026-10-09T18:00:00Z"}
+]`
+
+func TestRepoListShowsColumns(t *testing.T) {
+	server := newAuthenticatedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		require.Equal(t, "/api/v1/user/repos", r.URL.Path)
+		w.Header().Set("X-Total-Count", "2")
+		_, _ = w.Write([]byte(listedRepositories))
+	}))
+	defer server.Close()
+	deps, out, _ := repoTTYDeps(t, server.URL)
+	require.NoError(t, Execute(context.Background(), deps, []string{"repo", "list"}))
+	require.Equal(t, `Showing 2 of 2 repositories you can access
+
+NAME             DESCRIPTION          INFO              UPDATED
+alice/old-stuff  Archived repository  public, archived  about 2 hours ago
+acme/service                          private, fork     about 2 days ago
+`, out.String())
+	deps, out, _ = serverDeps(t, server.URL)
+	require.NoError(t, Execute(context.Background(), deps, []string{"repo", "list"}))
+	require.Equal(t, "alice/old-stuff\tArchived repository\tpublic, archived\t2026-10-11T18:00:00Z\thttps://gitea.test/alice/old-stuff\n"+
+		"acme/service\t\tprivate, fork\t2026-10-09T18:00:00Z\thttps://gitea.test/acme/service\n", out.String())
+}
+
+func TestRepoListReportsAnEmptyCollection(t *testing.T) {
+	server := newAuthenticatedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/api/v1/orgs/acme":
+			_, _ = w.Write([]byte(`{"id":3,"username":"acme"}`))
+		default:
+			_, _ = w.Write([]byte(`[]`))
+		}
+	}))
+	defer server.Close()
+	deps, out, diagnostics := repoTTYDeps(t, server.URL)
+	require.NoError(t, Execute(context.Background(), deps, []string{"repo", "list", "acme", "--type", "fork"}))
+	require.Empty(t, out.String())
+	require.Equal(t, "no forks owned by acme\n", diagnostics.String())
+}
+
+func TestRepoViewShowsStateAndReadme(t *testing.T) {
+	server := newAuthenticatedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		switch r.URL.Path {
+		case "/api/v1/repos/bob/project":
+			_, _ = w.Write([]byte(`{"full_name":"bob/project","description":"Demo","fork":true,"archived":true,"default_branch":"main",
+				"stars_count":1,"forks_count":0,"open_issues_count":2,"open_pr_counter":1,"updated_at":"2026-10-11T19:00:00Z",
+				"html_url":"https://gitea.test/bob/project","clone_url":"https://gitea.test/bob/project.git",
+				"parent":{"full_name":"alice/project"}}`))
+		case "/api/v1/repos/bob/project/contents/":
+			require.Equal(t, "develop", r.URL.Query().Get("ref"))
+			_, _ = w.Write([]byte(`[{"name":"docs","type":"dir"},{"name":"README","type":"file"},{"name":"readme.md","type":"file"}]`))
+		case "/api/v1/repos/bob/project/raw/readme.md":
+			_, _ = w.Write([]byte("Hello **there**"))
+		default:
+			t.Errorf("unexpected request %s", r.URL)
+		}
+	}))
+	defer server.Close()
+	deps, out, _ := repoTTYDeps(t, server.URL)
+	deps.Getenv = serverEnv(server.URL, map[string]string{"TERM": "dumb", "TEA_MARKDOWN": "raw"})
+	require.NoError(t, Execute(context.Background(), deps, []string{"repo", "view", "bob/project", "--branch", "develop"}))
+	require.Equal(t, `bob/project
+public • fork • archived (read-only) • ★ 1 · 0 forks · 2 open issues · 1 open pull request · updated about 1 hour ago
+Description:    Demo
+Forked from:    alice/project
+Default branch: main
+Clone:          https://gitea.test/bob/project.git
+
+Hello **there**
+
+View this repository on Gitea: https://gitea.test/bob/project
+`, out.String())
+	deps, out, _ = serverDeps(t, server.URL)
+	require.NoError(t, Execute(context.Background(), deps, []string{"repo", "view", "bob/project", "-b", "develop"}))
+	require.Equal(t, "title:\tbob/project\ndescription:\tDemo\nforked from:\talice/project\nmirror of:\t\ndefault branch:\tmain\nwebsite:\t\ntopics:\t\n"+
+		"clone:\thttps://gitea.test/bob/project.git\nssh:\t\nurl:\thttps://gitea.test/bob/project\n--\nHello **there**\n", out.String())
+}
+
+func TestRepoViewOfAnEmptyRepositorySkipsTheReadme(t *testing.T) {
+	server := newAuthenticatedServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		require.Equal(t, "/api/v1/repos/alice/empty", r.URL.Path)
+		_, _ = w.Write([]byte(`{"full_name":"alice/empty","private":true,"empty":true,"html_url":"https://gitea.test/alice/empty"}`))
+	}))
+	defer server.Close()
+	deps, out, _ := repoTTYDeps(t, server.URL)
+	deps.Getenv = serverEnv(server.URL, map[string]string{"TERM": "dumb", "TEA_MARKDOWN": "raw"})
+	require.NoError(t, Execute(context.Background(), deps, []string{"repo", "view", "alice/empty"}))
+	require.Contains(t, out.String(), "private • empty • ★ 0")
+	require.Contains(t, out.String(), "_This repository is empty._")
+}

internal/app/search.go

@@ -4,69 +4,70 @@
 package app
 
 import (
-	"errors"
 	"strings"
 
-	"gitea.dev/tea/internal/clierr"
 	"gitea.dev/tea/internal/services"
-	"gitea.dev/tea/internal/terminal"
 	"github.com/spf13/cobra"
 )
 
-func validateRepositoryKind(kind string) error {
-	switch kind {
-	case "", "fork", "source", "mirror":
-		return nil
-	default:
-		return clierr.Wrap(clierr.Usage, errors.New("--type must be fork, source, or mirror"))
-	}
-}
-
 func (a *application) searchCommand() *cobra.Command {
-	group := &cobra.Command{Use: "search", Short: "Search within one selected Gitea instance"}
+	group := &cobra.Command{
+		Use:   "search",
+		Short: "Search within one selected Gitea instance",
+		Long: `Search the repositories, issues and pull requests of the selected Gitea instance that your
+account can see.`,
+	}
 	var opts services.RepositorySearchOptions
 	var private, archived bool
-	command := &cobra.Command{Use: "repo [query]...", Short: "Search repository names, descriptions or topics", RunE: func(cmd *cobra.Command, args []string) error {
-		if err := a.rejectRepoFlag(cmd, func(owner string) string { return "tea search repo --owner " + owner }); err != nil {
-			return err
-		}
-		if err := validateRepositoryKind(opts.Kind); err != nil {
-			return err
-		}
-		if err := oneOf("sort", opts.Sort, "alpha", "created", "updated", "size", "id"); err != nil {
-			return err
-		}
-		if err := oneOf("order", opts.Order, "asc", "desc"); err != nil {
-			return err
-		}
-		if cmd.Flags().Changed("private") {
-			opts.Private = &private
-		}
-		if cmd.Flags().Changed("archived") {
-			opts.Archived = &archived
-		}
-		opts.Query = strings.Join(args, " ")
-		target, err := a.resolve(cmd.Context(), false)
-		if err != nil {
-			return err
-		}
-		items, err := (services.Repositories{Client: target.client}).Search(cmd.Context(), opts)
-		if err != nil {
-			return err
-		}
-		return writeList(a, cmd, items, func(item services.Repository) []terminal.Cell {
-			return terminal.Row(item.FullName, item.Description, item.URL)
-		})
-	}}
+	command := &cobra.Command{
+		Use:   "repo [<query>...]",
+		Short: "Search repositories",
+		Long:  "Search the names and descriptions of repositories, or their topics with --topic.",
+		Example: `# Search repositories about a CLI
+$ tea search repo command line
+
+# Search the archived repositories of an organization
+$ tea search repo --owner acme --archived
+
+# Search by topic, most recently updated first
+$ tea search repo go --topic --sort updated --order desc`,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if err := a.rejectRepoFlag(cmd, func(owner string) string { return "tea search repo --owner " + owner }); err != nil {
+				return err
+			}
+			if cmd.Flags().Changed("private") {
+				opts.Private = &private
+			}
+			if cmd.Flags().Changed("archived") {
+				opts.Archived = &archived
+			}
+			opts.Query = strings.Join(args, " ")
+			target, err := a.resolve(cmd.Context(), false)
+			if err != nil {
+				return err
+			}
+			result, err := (services.Repositories{Client: target.client}).Search(cmd.Context(), opts)
+			if err != nil {
+				return err
+			}
+			what := "repositories"
+			if opts.Query != "" {
+				what += " matching " + opts.Query
+			}
+			spec := listSpec[services.Repository]{Columns: repositoryColumns, Row: repositoryRow, Context: what, Empty: "no " + what}
+			return writeTable(a, cmd, result.Items, spec, listPage{Number: opts.Page, More: result.More, Total: result.Total, Counted: result.Counted})
+		},
+	}
 	flags := command.Flags()
 	pageFlags(command, &opts.Limit, &opts.Page)
-	flags.StringVar(&opts.Owner, "owner", "", "Repository owner")
-	flags.StringVar(&opts.Kind, "type", "", "Repository kind: fork, source, mirror")
-	flags.StringVar(&opts.Sort, "sort", "alpha", "Sort by alpha, created, updated, size, id")
-	flags.StringVar(&opts.Order, "order", "asc", "Sort order: asc, desc")
+	flags.StringVar(&opts.Owner, "owner", "", "Only repositories of this user or organization")
+	enumFlag(command, &opts.Kind, "type", "", "", "Only repositories of this kind", "fork", "source", "mirror")
+	enumFlag(command, &opts.Sort, "sort", "", "alpha", "Sort by", "alpha", "created", "updated", "size", "id")
+	enumFlag(command, &opts.Order, "order", "", "asc", "Sort order", "asc", "desc")
 	flags.BoolVar(&opts.Topic, "topic", false, "Match repository topics")
 	flags.BoolVar(&private, "private", false, "Only private repositories (use =false for public)")
 	flags.BoolVar(&archived, "archived", false, "Only archived repositories (use =false for active)")
+	_ = command.RegisterFlagCompletionFunc("owner", a.completeOrgs())
 	group.AddCommand(command, a.discussionSearchCommand(false), a.discussionSearchCommand(true))
 	return group
 }

internal/app/validation_test.go

@@ -166,9 +166,9 @@ func TestUsageErrorsPrecedeRequests(t *testing.T) {
 		{[]string{"repo", "edit", "--default-branch="}, "default branch cannot be empty"},
 		{[]string{"repo", "archive", "alice/project", "-R", "alice/other", "--yes"}, "supply the repository as an argument or --repo, not both"},
 		{[]string{"repo", "view", "alice/project", "--repo", "alice/other"}, "supply the repository as an argument or --repo, not both"},
-		{[]string{"repo", "view", "alice/project", "alice/other"}, "too many arguments\nUsage: tea repo view [repository] [flags]"},
-		{[]string{"repo", "list", "--owner", "account", "--starred"}, "--owner, --starred, and --watched select mutually exclusive collections"},
-		{[]string{"repo", "list", "--starred", "--watched"}, "--owner, --starred, and --watched select mutually exclusive collections"},
+		{[]string{"repo", "view", "alice/project", "alice/other"}, "too many arguments\nUsage: tea repo view [<repository>] [flags]"},
+		{[]string{"repo", "list", "--owner", "account", "--starred"}, "an owner, --starred and --watched select different collections; pass one"},
+		{[]string{"repo", "list", "--starred", "--watched"}, "an owner, --starred and --watched select different collections; pass one"},
 		{[]string{"repo", "list", "--type", "invalid"}, "--type must be fork, source, or mirror"},
 		{[]string{"repo", "set-default", "--json"}, "set-default configures Git"},
 		{[]string{"repo", "sync", "--branch="}, "--branch cannot be empty"},