add debug mode and update readme

README.md

@@ -11,13 +11,16 @@
 ![demo gif](./demo.gif)
 
 ```
+NAME:
   tea - command line tool to interact with Gitea
-   version 0.8.0-preview
 
- USAGE
+USAGE:
-   tea command [subcommand] [command options] [arguments...]
+  tea [global options] [command [command options]]
 
- DESCRIPTION
+VERSION:
+  Version: 0.10.1+15-g8876fe3  golang: 1.25.0  go-sdk: v0.21.0
+
+DESCRIPTION:
   tea is a productivity helper for Gitea. It can be used to manage most entities on
   one or multiple Gitea instances & provides local helpers like 'tea pr checkout'.
 
@@ -26,33 +29,40 @@
   upstream repo. tea assumes that local git state is published on the remote before
   doing operations with tea.    Configuration is persisted in $XDG_CONFIG_HOME/tea.
 
- COMMANDS
+COMMANDS:
   help, h  Shows a list of commands or help for one command
+
   ENTITIES:
     issues, issue, i                  List, create and update issues
     pulls, pull, pr                   Manage and checkout pull requests
     labels, label                     Manage issue labels
     milestones, milestone, ms         List and create milestones
     releases, release, r              Manage releases
-     release assets, release asset, r a  Manage release attachments
     times, time, t                    Operate on tracked times of a repository's issues & pulls
     organizations, organization, org  List, create, delete organizations
     repos, repo                       Show repository details
+    branches, branch, b               Consult branches
     comment, c                        Add a comment to an issue / pr
+
   HELPERS:
     open, o                         Open something of the repository in web browser
     notifications, notification, n  Show notifications
     clone, C                        Clone a repository locally
+
+  MISCELLANEOUS:
+    whoami    Show current logged in user
+    admin, a  Operations requiring admin access on the Gitea instance
+
   SETUP:
     logins, login  Log in to a Gitea server
     logout         Log out from a Gitea server
-     whoami                         Show current logged in user
 
- OPTIONS
+GLOBAL OPTIONS:
-   --help, -h     show help (default: false)
+  --debug, --vvv  Enable debug mode (default: false)
-   --version, -v  print the version (default: false)
+  --help, -h      show help
+  --version, -v   print the version
 
- EXAMPLES
+EXAMPLES
   tea login add                       # add a login once to get started
 
   tea pulls                           # list open pulls for the repo in $PWD
@@ -70,7 +80,7 @@
   # send gitea desktop notifications every 5 minutes (bash + libnotify)
   while :; do tea notifications --mine -o simple | xargs -i notify-send {}; sleep 300; done
 
- ABOUT
+ABOUT
   Written & maintained by The Gitea Authors.
   If you find a bug or want to contribute, we'll welcome you at https://gitea.com/gitea/tea.
   More info about Gitea itself on https://about.gitea.com.

cmd/clone.go

@@ -10,6 +10,7 @@ import (
 	"code.gitea.io/tea/cmd/flags"
 	"code.gitea.io/tea/modules/config"
 	"code.gitea.io/tea/modules/context"
+	"code.gitea.io/tea/modules/debug"
 	"code.gitea.io/tea/modules/git"
 	"code.gitea.io/tea/modules/interact"
 	"code.gitea.io/tea/modules/task"
@@ -68,12 +69,15 @@ func runRepoClone(ctx stdctx.Context, cmd *cli.Command) error {
 		return err
 	}
 
+	debug.Printf("Cloning repository %s into %s", url.String(), dir)
+
 	owner, repo = utils.GetOwnerAndRepo(url.Path, login.User)
 	if url.Host != "" {
 		login = config.GetLoginByHost(url.Host)
 		if login == nil {
 			return fmt.Errorf("No login configured matching host '%s', run `tea login add` first", url.Host)
 		}
+		debug.Printf("Matched login '%s' for host '%s'", login.Name, url.Host)
 	}
 
 	_, err = task.RepoClone(

main.go

@@ -10,10 +10,12 @@ import (
 	"os"
 
 	"code.gitea.io/tea/cmd"
+	"code.gitea.io/tea/modules/debug"
 )
 
 func main() {
 	app := cmd.App()
+	app.Flags = append(app.Flags, debug.CliFlag())
 	err := app.Run(context.Background(), os.Args)
 	if err != nil {
 		// app.Run already exits for errors implementing ErrorCoder,

modules/config/login.go

@@ -17,6 +17,7 @@ import (
 	"time"
 
 	"code.gitea.io/sdk/gitea"
+	"code.gitea.io/tea/modules/debug"
 	"code.gitea.io/tea/modules/theme"
 	"code.gitea.io/tea/modules/utils"
 	"github.com/charmbracelet/huh"
@@ -277,6 +278,9 @@ func (l *Login) Client(options ...gitea.ClientOption) *gitea.Client {
 	}
 
 	options = append(options, gitea.SetToken(l.Token), gitea.SetHTTPClient(httpClient))
+	if debug.IsDebug() {
+		options = append(options, gitea.SetDebugMode())
+	}
 
 	if ok, err := utils.IsKeyEncrypted(l.SSHKey); ok && err == nil && l.SSHPassphrase == "" {
 		if err := huh.NewInput().

modules/debug/debug.go

@@ -0,0 +1,40 @@
+// Copyright 2025 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package debug
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/urfave/cli/v3"
+)
+
+var debug bool
+
+func IsDebug() bool {
+	return debug
+}
+
+func SetDebug(on bool) {
+	debug = on
+}
+
+func Printf(info string, args ...any) {
+	if debug {
+		fmt.Printf("DEBUG: "+info+"\n", args...)
+	}
+}
+
+func CliFlag() cli.Flag {
+	return &cli.BoolFlag{
+		Name:    "debug",
+		Aliases: []string{"vvv"},
+		Usage:   "Enable debug mode",
+		Value:   false,
+		Action: func(ctx context.Context, cmd *cli.Command, v bool) error {
+			SetDebug(v)
+			return nil
+		},
+	}
+}