feat: improve CLI help text for root, run, bump, configure, lint, ope…

cmd/bump.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/hashicorp/go-version"
 	config "github.com/speakeasy-api/sdk-gen-config"
+	"github.com/speakeasy-api/speakeasy/internal/utils"
 	"github.com/spf13/cobra"
 )
 
@@ -19,19 +20,30 @@ const (
 	bumpGraduate bumpType = "graduate"
 )
 
-var bumpCommand = &cobra.Command{
-	Use:   "bump [patch|minor|major|graduate]",
-	Short: "Bumps the version of a Speakeasy Generation Target",
-	Long: `Bumps the version of a Speakeasy Generation Target, run within the target's directory. Allows the bumping of patch, minor, and major versions or setting to a specific version.
+const bumpLong = `# Bump
+
+Bumps the version of a Speakeasy Generation Target, run within the target's directory. Allows the bumping of patch, minor, and major versions or setting to a specific version.
 
 Examples:
 
 - speakeasy bump patch - Bumps the target's version by one patch version
 - speakeasy bump -v 1.2.3 - Sets the target's version to 1.2.3
 - speakeasy bump major -t typescript - Bumps the typescript target's version by one major version
 - speakeasy bump graduate - Current version 1.2.3-alpha.1 sets the target's version to 1.2.3
-`,
-	Args: cobra.RangeArgs(0, 1),
+`
+
+const bumpExamples = `
+
+const version = require("@speakeasy/sdk-typescript").version;
+console.log(version);
+`
+
+var bumpCommand = &cobra.Command{
+	Use:     "bump [patch|minor|major|graduate]",
+	Short:   "Bumps the version of a Speakeasy Generation Target",
+	Long:    utils.RenderMarkdown(bumpLong),
+	Example: utils.RenderMarkdown(bumpExamples),
+	Args:    cobra.RangeArgs(0, 1),
 }
 
 func bumpInit() {

cmd/configure.go

@@ -15,6 +15,7 @@ import (
 	"github.com/speakeasy-api/speakeasy-core/events"
 
 	"github.com/speakeasy-api/speakeasy/internal/model/flag"
+	"github.com/speakeasy-api/speakeasy/internal/utils"
 
 	"github.com/charmbracelet/lipgloss"
 	"github.com/pkg/errors"
@@ -38,10 +39,22 @@ const (
 	appInstallURL        = "https://github.com/apps/speakeasy-github"
 )
 
+const configureLong = `# Configure
+
+Configure your Speakeasy workflow file.
+
+[Workflows](https://www.speakeasy.com/docs/workflow-file-reference)
+
+[GitHub Setup](https://www.speakeasy.com/docs/publish-sdks/github-setup)
+
+[Publishing](https://www.speakeasy.com/docs/publish-sdks/publish-sdks)
+
+`
+
 var configureCmd = &model.CommandGroup{
 	Usage:          "configure",
 	Short:          "Configure your Speakeasy SDK Setup.",
-	Long:           `Configure your Speakeasy SDK Setup.`,
+	Long:           utils.RenderMarkdown(configureLong),
 	InteractiveMsg: "What do you want to configure?",
 	Commands:       []model.Command{configureSourcesCmd, configureTargetCmd, configureGithubCmd, configurePublishingCmd},
 }

cmd/lint.go

@@ -18,11 +18,13 @@ import (
 	"github.com/speakeasy-api/speakeasy/internal/validation"
 )
 
+const lintLong = "# Lint \n The `lint` command provides a set of commands for linting OpenAPI docs and more."
+
 var lintCmd = &model.CommandGroup{
 	Usage:          "lint",
 	Aliases:        []string{"validate"},
 	Short:          "Lint/Validate OpenAPI documents and Speakeasy configuration files",
-	Long:           `The "lint" command provides a set of commands for linting OpenAPI docs and more.`,
+	Long:           utils.RenderMarkdown(lintLong),
 	InteractiveMsg: "What do you want to lint?",
 	Commands:       []model.Command{lintOpenapiCmd, lintConfigCmd},
 }
@@ -36,10 +38,15 @@ type LintOpenapiFlags struct {
 	Ruleset               string `json:"ruleset"`
 }
 
+const lintOpenAPILong = `# Lint 
+## OpenAPI
+
+Validates an OpenAPI document is valid and conforms to the Speakeasy OpenAPI specification.`
+
 var lintOpenapiCmd = &model.ExecutableCommand[LintOpenapiFlags]{
 	Usage:          "openapi",
 	Short:          "Lint an OpenAPI document",
-	Long:           `Validates an OpenAPI document is valid and conforms to the Speakeasy OpenAPI specification.`,
+	Long:           utils.RenderMarkdown(lintOpenAPILong),
 	Run:            lintOpenapi,
 	RunInteractive: lintOpenapiInteractive,
 	Flags: []flag.Flag{

cmd/openapi.go

@@ -13,6 +13,7 @@ import (
 	"github.com/speakeasy-api/sdk-gen-config/workflow"
 	"github.com/speakeasy-api/speakeasy-core/events"
 	"github.com/speakeasy-api/speakeasy/internal/transform"
+	"github.com/speakeasy-api/speakeasy/internal/utils"
 	"github.com/speakeasy-api/speakeasy/registry"
 
 	"github.com/speakeasy-api/speakeasy/internal/changes"
@@ -21,10 +22,12 @@ import (
 	"github.com/speakeasy-api/speakeasy/internal/model/flag"
 )
 
+const openapiLong = "# OpenAPI \n The `openapi` command provides a set of commands for visualizing, linting and transforming OpenAPI documents."
+
 var openapiCmd = &model.CommandGroup{
 	Usage:          "openapi",
 	Short:          "Utilities for working with OpenAPI documents",
-	Long:           `The "openapi" command provides a set of commands for visualizing, linting and transforming OpenAPI documents.`,
+	Long:           utils.RenderMarkdown(openapiLong),
 	InteractiveMsg: "What do you want to do?",
 	Commands:       []model.Command{openapiLintCmd, openapiDiffCmd, transformCmd},
 }

cmd/overlay.go

@@ -19,9 +19,15 @@ var overlayFlag = flag.StringFlag{
 	Required:    true,
 }
 
+const overlayLong = `# Overlay
+
+Command group for working with OpenAPI Overlays.
+`
+
 var overlayCmd = &model.CommandGroup{
 	Usage:    "overlay",
 	Short:    "Work with OpenAPI Overlays",
+	Long:     utils.RenderMarkdown(overlayLong),
 	Commands: []model.Command{overlayCompareCmd, overlayValidateCmd, overlayApplyCmd},
 }
 

cmd/root.go

@@ -26,17 +26,31 @@ import (
 	"go.uber.org/zap"
 )
 
+const rootLong = `# Speakeasy 
+
+A CLI tool for interacting with the [Speakeasy platform](https://www.speakeasy.com/) and its APIs.
+
+Use this CLI to:
+- Lint and validate OpenAPI specs
+- Create, manage, and run Speakeasy workflows
+- Configure GitHub Actions for Speakeasy workflows
+- Suggest improvements to OpenAPI specs
+
+Generate from OpenAPI Specs:
+- Client and Server SDKs in GO, Python, TypeScript, Java, PHP, C#, Swift, Ruby
+- Postman collections
+- Terraform providers
+
+[Quickstart guide](https://www.speakeasy.com/docs/create-client-sdks)
+
+Visit [Speakeasy](https://www.speakeasy.com/) for more information
+`
+
 var rootCmd = &cobra.Command{
 	Use:   "speakeasy",
-	Short: "The speakeasy cli tool provides access to the speakeasyapi.dev toolchain",
-	Long: ` A cli tool for interacting with the Speakeasy https://www.speakeasyapi.dev/ platform and its various functions including:
-	- Generating Client SDKs from OpenAPI specs (go, python, typescript, java, php, c#, swift, ruby, terraform)
-	- Validating OpenAPI specs
-	- Interacting with the Speakeasy API to create and manage your API workspaces
-	- Generating OpenAPI specs from your API traffic
-	- Generating Postman collections from OpenAPI Specs
-`,
-	RunE: rootExec,
+	Short: "The Speakeasy CLI tool provides access to the Speakeasy.com platform",
+	Long:  utils.RenderMarkdown(rootLong),
+	RunE:  rootExec,
 }
 
 var l = log.New().WithLevel(log.LevelInfo)

cmd/run.go

@@ -41,19 +41,23 @@ type RunFlags struct {
 	GitHub           bool              `json:"github"`
 }
 
-var runCmd = &model.ExecutableCommand[RunFlags]{
-	Usage: "run",
-	Short: "generate an SDK, compile OpenAPI sources, and much more from a workflow.yaml file",
-	Long: "run the workflow(s) defined in your `.speakeasy/workflow.yaml` file." + `
+const runLong = "# Run \n Execute the workflow(s) defined in your `.speakeasy/workflow.yaml` file." + `
+
 A workflow can consist of multiple targets that define a source OpenAPI document that can be downloaded from a URL, exist as a local file, or be created via merging multiple OpenAPI documents together and/or overlaying them with an OpenAPI overlay document.
-A full workflow is capable of running the following steps:
+
+A full workflow is capable of running the following:
   - Downloading source OpenAPI documents from a URL
   - Merging multiple OpenAPI documents together
   - Overlaying OpenAPI documents with an OpenAPI overlay document
   - Generating one or many SDKs from the resulting OpenAPI document
   - Compiling the generated SDKs
 
-` + "If `speakeasy run` is run without any arguments it will run either the first target in the workflow or the first source in the workflow if there are no other targets or sources, otherwise it will prompt you to select a target or source to run.",
+` + "If `speakeasy run` is run without any arguments it will run either the first target in the workflow or the first source in the workflow if there are no other targets or sources, otherwise it will prompt you to select a target or source to run."
+
+var runCmd = &model.ExecutableCommand[RunFlags]{
+	Usage:            "run",
+	Short:            "Run all the workflows defined in your workflow.yaml file. This can include multiple SDK generations from different OpenAPI sources",
+	Long:             utils.RenderMarkdown(runLong),
 	PreRun:           preRun,
 	Run:              runFunc,
 	RunInteractive:   runInteractive,

cmd/suggest.go

@@ -12,9 +12,16 @@ import (
 	"os"
 )
 
+const suggestLong = `
+# Suggest 
+
+Automatically optimise your OpenAPI document for SDK generation with an LLM powered suggestions
+`
+
 var suggestCmd = &model.CommandGroup{
 	Usage:          "suggest",
 	Short:          "Automatically improve your OpenAPI document with an LLM",
+	Long:           utils.RenderMarkdown(suggestLong),
 	InteractiveMsg: "What would you like to improve?",
 	Commands:       []model.Command{suggestOperationIDsCmd},
 }

go.mod

@@ -43,6 +43,7 @@ require (
 require (
 	github.com/AlekSi/pointer v1.2.0
 	github.com/cenkalti/backoff/v4 v4.3.0
+	github.com/charmbracelet/glamour v0.7.0
 	github.com/dustin/go-humanize v1.0.1
 	github.com/ericlagergren/decimal v0.0.0-20240411145413-00de7ca16731
 	github.com/inkeep/ai-api-go v0.3.1
@@ -66,10 +67,12 @@ require (
 	github.com/ProtonMail/go-crypto v1.1.0-alpha.2 // indirect
 	github.com/agext/levenshtein v1.2.1 // indirect
 	github.com/alecthomas/chroma v0.10.0 // indirect
+	github.com/alecthomas/chroma/v2 v2.8.0 // indirect
 	github.com/apparentlymart/go-textseg/v13 v13.0.0 // indirect
 	github.com/apparentlymart/go-textseg/v15 v15.0.0 // indirect
 	github.com/atotto/clipboard v0.1.4 // indirect
 	github.com/aymanbagabas/go-osc52/v2 v2.0.1 // indirect
+	github.com/aymerick/douceur v0.2.0 // indirect
 	github.com/bahlo/generic-list-go v0.2.0 // indirect
 	github.com/buger/jsonparser v1.1.1 // indirect
 	github.com/bytedance/sonic v1.9.1 // indirect
@@ -126,6 +129,7 @@ require (
 	github.com/google/pprof v0.0.0-20240117000934-35fc243c5815 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/gookit/color v1.5.4 // indirect
+	github.com/gorilla/css v1.0.0 // indirect
 	github.com/gorilla/handlers v1.5.1 // indirect
 	github.com/gorilla/mux v1.8.1 // indirect
 	github.com/gorilla/websocket v1.5.1 // indirect
@@ -156,6 +160,7 @@ require (
 	github.com/mattn/go-isatty v0.0.20 // indirect
 	github.com/mattn/go-localereader v0.0.1 // indirect
 	github.com/mattn/go-runewidth v0.0.15 // indirect
+	github.com/microcosm-cc/bluemonday v1.0.25 // indirect
 	github.com/mitchellh/copystructure v1.2.0 // indirect
 	github.com/mitchellh/go-wordwrap v1.0.1 // indirect
 	github.com/mitchellh/hashstructure/v2 v2.0.2 // indirect
@@ -167,6 +172,7 @@ require (
 	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/muesli/reflow v0.3.0 // indirect
 	github.com/muesli/termenv v0.15.2 // indirect
+	github.com/olekukonko/tablewriter v0.0.5 // indirect
 	github.com/opencontainers/go-digest v1.0.0 // indirect
 	github.com/opencontainers/image-spec v1.1.0 // indirect
 	github.com/pb33f/doctor v0.0.8 // indirect
@@ -211,6 +217,8 @@ require (
 	github.com/xanzy/ssh-agent v0.3.3 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
 	github.com/xtgo/uuid v0.0.0-20140804021211-a0b114877d4c // indirect
+	github.com/yuin/goldmark v1.7.1 // indirect
+	github.com/yuin/goldmark-emoji v1.0.2 // indirect
 	github.com/zclconf/go-cty v1.14.4 // indirect
 	go.opentelemetry.io/otel v1.24.0 // indirect
 	go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.24.0 // indirect