Improve CLI usability and improve automation cases (e.g. LLMs)

- Migrated from Cobra to Kong framework
- Improved help text for better readability by humans and LLMs
- Dynamic shell completions with comprehensive flag and subcommand suggestions
- Better error messages
- Various improvements to make things more LLM friendly:
  - Non-interactive modes for `bk build watch`
  - Add `bk job logs <job-id>`` command for viewing individual job logs
  - Add `--logs` and `--failed-only` flags to `bk build download` command
- New `--output` flag for all data query commands (deprecated `--json`)

See UPGRADING.md for breaking changes and upgrade instructions.

Author: toolmantim

AGENT.md

@@ -1,13 +1,12 @@
 package main
 
 import (
-	"context"
 	"os"
 
 	bkErrors "github.com/buildkite/cli/v3/internal/errors"
 	"github.com/buildkite/cli/v3/internal/version"
+	"github.com/buildkite/cli/v3/pkg/cli"
 	"github.com/buildkite/cli/v3/pkg/cmd/factory"
-	"github.com/buildkite/cli/v3/pkg/cmd/root"
 )
 
 func main() {
@@ -16,8 +15,6 @@ func main() {
 }
 
 func mainRun() int {
-	ctx := context.Background()
-
 	// Create factory
 	f, err := factory.New(version.Version)
 	if err != nil {
@@ -31,37 +28,6 @@ func mainRun() int {
 		return bkErrors.ExitCodeInternalError
 	}
 
-	// Create root command
-	rootCmd, err := root.NewCmdRoot(f)
-	if err != nil {
-		errHandler := bkErrors.NewHandler()
-		errHandler.Handle(bkErrors.NewInternalError(
-			err,
-			"failed to create command structure",
-			"This is likely a bug in the CLI",
-			"Please report this issue to the Buildkite CLI team",
-		))
-		return bkErrors.ExitCodeInternalError
-	}
-
-	// Set context
-	rootCmd.SetContext(ctx)
-
-	// Get verbose flag value
-	verbose, _ := rootCmd.PersistentFlags().GetBool("verbose")
-
-	// Silence Cobra's error printing so we can handle it ourselves
-	rootCmd.SilenceErrors = true
-
-	// Execute the command
-	err = rootCmd.Execute()
-	if err != nil {
-		// Handle the error with our error handler
-		errHandler := bkErrors.NewHandler().WithVerbose(verbose)
-		errHandler.HandleWithDetails(err, rootCmd.CommandPath())
-		return bkErrors.GetExitCodeForError(err)
-	}
-
-	// If we get here, the command executed successfully
-	return bkErrors.ExitCodeSuccess
+	// Use Kong CLI
+	return cli.Run(version.Version, f)
 }

README.md

@@ -13,3 +13,5 @@ bindings:
     type: string
   YAML:
     type: string
+  DateTime:
+    type: string

UPGRADING.md

@@ -7,6 +7,7 @@ toolchain go1.24.1
 require (
 	github.com/AlecAivazis/survey/v2 v2.3.7
 	github.com/MakeNowJust/heredoc v1.0.0
+	github.com/alecthomas/kong v1.12.0
 	github.com/buildkite/go-buildkite/v4 v4.1.0
 	github.com/charmbracelet/bubbles v0.21.0
 	github.com/charmbracelet/bubbletea v1.3.5
@@ -18,9 +19,11 @@ require (
 	github.com/go-git/go-git/v5 v5.16.2
 	github.com/muesli/reflow v0.3.0
 	github.com/pkg/browser v0.0.0-20210911075715-681adbf594b8
+	github.com/posener/complete v1.2.3
 	github.com/spf13/cobra v1.9.1
 	github.com/spf13/viper v1.20.1
 	github.com/vektah/gqlparser/v2 v2.5.30
+	github.com/willabides/kongplete v0.4.0
 	github.com/xeipuuv/gojsonschema v1.2.0
 	golang.org/x/sync v0.16.0
 	gopkg.in/yaml.v3 v3.0.1
@@ -46,8 +49,11 @@ require (
 	github.com/go-viper/mapstructure/v2 v2.3.0 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/gorilla/css v1.0.1 // indirect
+	github.com/hashicorp/errwrap v1.1.0 // indirect
+	github.com/hashicorp/go-multierror v1.1.1 // indirect
 	github.com/microcosm-cc/bluemonday v1.0.27 // indirect
 	github.com/mitchellh/hashstructure/v2 v2.0.2 // indirect
+	github.com/riywo/loginshell v0.0.0-20200815045211-7d26008be1ab // indirect
 	github.com/xeipuuv/gojsonpointer v0.0.0-20180127040702-4e3ac2762d5f // indirect
 	github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect