docs(generate-usage): Add generated docs

Makefile

@@ -49,6 +49,13 @@ endif
 
 generate-api: generate-client format
 
+.PHONY: docs
+docs:
+	rm -rf docs
+	mkdir docs
+	go run -ldflags="-X 'github.com/codesphere-cloud/cs-go/pkg/out.binName=cs'" hack/gendocs/main.go 
+	cp docs/{cs,README}.md
+
 generate-license:
 	go-licenses report --template .NOTICE.template  ./... > NOTICE
 	copywrite headers apply

README.md

@@ -23,14 +23,14 @@ Not that some commands may require you to elevate to the root user with `sudo`.
 ##### ARM Mac
 
 ```
-gh release download -R codesphere-cloud/cs-go -o cs -D /usr/local/bin/cs -p *darwin_arm64
+gh release download -R codesphere-cloud/cs-go -O /usr/local/bin/cs -p "*darwin_arm64"
 chmod +x /usr/local/bin/cs
 ```
 
 ##### Linux Amd64
 
 ```
-gh release download -R codesphere-cloud/cs-go -o cs -D /usr/local/bin/cs -p *linux_amd4
+gh release download -R codesphere-cloud/cs-go -O /usr/local/bin/cs -p "*linux_amd64"
 chmod +x /usr/local/bin/cs
 ```
 
@@ -89,110 +89,7 @@ The `cs` CLI supports several global options that you can set via command-line f
 
 The `cs` CLI organizes its functionality into several top-level commands, each with specific subcommands and flags.
 
-##### `cs list`
-
-Use this command to list various resources available in Codesphere.
-
-**Usage:**
-
-```
-cs list [command]
-```
-
-###### `cs list teams`
-
-Lists all teams you have access to in Codesphere.
-
-**Usage:**
-
-```
-cs list teams
-```
-
-**Example:**
-
-```
-$ cs list teams
-```
-
-###### `cs list workspaces`
-
-Lists all workspaces available in Codesphere.
-
-**Usage:**
-
-```
-cs list workspaces [--team-id <team-id>]
-```
-
-**Example:**
-
-```
-$ cs list workspaces --team-id <team-id>
-```
-
-If you don't specify `--team-id`, the command will try to list workspaces for all teams you can access (or for the team specified by `CS_TEAM_ID`).
-
-##### `cs log`
-
-Retrieves run logs from services within your workspaces.
-
-**Usage:**
-
-```
-cs log --workspace-id <workspace-id> [options]
-```
-
-**Description:**
-
-You can retrieve logs based on the given scope. If you provide both the step number and server, it returns all logs from all replicas of that server. If you provide a specific replica ID, it will return logs for that replica only.
-
-**Examples:**
-
-```
-# Get logs from a specific server within a workspace
-$ cs log -w 637128 -s app
-
-# Get all logs from all servers in a workspace
-$ cs log -w 637128
-
-# Get logs from a specific replica
-$ cs log -w 637128 -r workspace-213d7a8c-48b4-42e2-8f70-c905ab04abb5-58d657cdc5-m8rrp
-
-# Get logs from a self-hosted Codesphere installation (using a custom API URL)
-$ cs log --api https://codesphere.acme.com/api -w 637128 -s app
-```
-
-**Flags:**
-
-* `--server`, `-s` (string): Name of the landscape server.
-
-* `--workspace-id`, `-w` (int): ID of your Codesphere workspace. You can also set this via the `CS_WORKSPACE_ID` environment variable. **This flag or environment variable is required if not set globally.**
-
-* `--step`, `-n` (int): Index of the execution step (default 0).
-
-* `--replica`, `-r` (string): ID of the server replica. If you provide this, the `--server` flag will be ignored.
-
-##### `cs set-env`
-
-Sets environment variables for your workspace.
-
-**Usage:**
-
-```
-cs set-env --workspace-id <workspace-id> --env <key>=<value> [--env <key2>=<key2> ...]
-```
-
-**Example:**
-
-```
-# Set environment variables for a specific workspace
-$ cs set-env --workspace-id <workspace-id> --env foo=bar --env hello=world
-```
-
-**Flags:**
-
-* `--env-var`, `-e` (stringArray): Environment variables to set, in the format `key=val`. You can use this flag multiple times to set several variables.
+See our [Usage Documentation](docs) for usage information about the specific subcommands.
 
 ## Go SDK
 

cli/cmd/list-teams.go

@@ -24,11 +24,9 @@ func addListTeamsCmd(p *cobra.Command, opts GlobalOptions) {
 			Use:   "teams",
 			Short: "list teams",
 			Long:  `list teams available in Codesphere`,
-			Example: `
-List all teams:
-
-$ cs list teams
-			`,
+			Example: out.FormatExampleCommands("list teams", map[string]string{
+				"": "List all teams",
+			}),
 		},
 		opts: opts,
 	}

cli/cmd/list-workspaces.go

@@ -24,11 +24,9 @@ func addListWorkspacesCmd(p *cobra.Command, opts GlobalOptions) {
 			Use:   "workspaces",
 			Short: "list workspaces",
 			Long:  `list workspaces available in Codesphere`,
-			Example: `
-List all workspaces:
-
-$ cs list workspaces --team-id <team-id>
-			`,
+			Example: out.FormatExampleCommands("list workspaces", map[string]string{
+				"--team-id <team-id>": "List all workspaces",
+			}),
 		},
 		Opts: opts,
 	}

cli/cmd/list.go

@@ -4,6 +4,7 @@
 package cmd
 
 import (
+	"github.com/codesphere-cloud/cs-go/pkg/out"
 	"github.com/spf13/cobra"
 )
 
@@ -17,11 +18,9 @@ func addListCmd(rootCmd *cobra.Command, opts GlobalOptions) {
 			Use:   "list",
 			Short: "list resources",
 			Long:  `list resources available in Codesphere`,
-			Example: `
-				List all workspaces:
-
-			  $ cs list workspaces
-			`,
+			Example: out.FormatExampleCommands("list", map[string]string{
+				"workspaces": "List all workspaces",
+			}),
 		},
 	}
 	rootCmd.AddCommand(l.cmd)

cli/cmd/log.go

@@ -18,6 +18,7 @@ import (
 	"sync"
 
 	"github.com/codesphere-cloud/cs-go/pkg/cs"
+	"github.com/codesphere-cloud/cs-go/pkg/out"
 	"github.com/spf13/cobra"
 )
 
@@ -59,20 +60,16 @@ func addLogCmd(rootCmd *cobra.Command, opts GlobalOptions) {
 			Short: "Retrieve Run logs from services",
 			Long: `You can retrieve logs based on the given scope.
 
-	If you provide the step number and server, it returns all logs from
-	all replicas of that server.
-
-	If you provide a specific replica id, it will return the logs of
-	that replica only.`,
-			Example: `
-	Get logs from a server
-		log -w 637128 -s app
-	Get all logs of all servers
-		log -w 637128
-	Get logs from a replica
-		log -w 637128 -r workspace-213d7a8c-48b4-42e2-8f70-c905ab04abb5-58d657cdc5-m8rrp
-	Get logs from a self-hosted Codesphere installation:
-		log --api https://codesphere.acme.com/api -w 637128 -s app`,
+If you provide the step number and server, it returns all logs from
+all replicas of that server.
+
+If you provide a specific replica id, it will return the logs of
+that replica only.`,
+			Example: out.FormatExampleCommands("log", map[string]string{
+				"-w 637128 -s app": "Get logs from a server",
+				"-w 637128":        "Get all logs of all servers",
+				"-w 637128 -r workspace-213d7a8c-48b4-42e2-8f70-c905ab04abb5-58d657cdc5-m8rrp": "Get logs from a replica",
+			}),
 		},
 		opts: opts,
 	}
@@ -83,10 +80,9 @@ func addLogCmd(rootCmd *cobra.Command, opts GlobalOptions) {
 
 func (logCmd *LogCmd) parseLogCmdFlags() {
 	logCmd.scope = LogCmdScope{
-		server:      logCmd.cmd.Flags().StringP("server", "s", "", "Name of the landscape server"),
-		workspaceId: logCmd.cmd.Flags().IntP("workspace-id", "w", 0, "ID of Codesphere workspace (can also be CS_WORKSPACE_ID)"),
-		step:        logCmd.cmd.Flags().IntP("step", "n", 0, "Index of execution step (default 0)"),
-		replica:     logCmd.cmd.Flags().StringP("replica", "r", "", "ID of server replica"),
+		server:  logCmd.cmd.Flags().StringP("server", "s", "", "Name of the landscape server"),
+		step:    logCmd.cmd.Flags().IntP("step", "n", 0, "Index of execution step (default 0)"),
+		replica: logCmd.cmd.Flags().StringP("replica", "r", "", "ID of server replica"),
 	}
 }
 

cli/cmd/root.go

@@ -60,24 +60,26 @@ func (o GlobalOptions) GetWorkspaceId() (int, error) {
 	return wsId, nil
 }
 
-func Execute() {
+func GetRootCmd() *cobra.Command {
 	var rootCmd = &cobra.Command{
 		Use:   "cs",
 		Short: "The codesphere CLI",
 		Long:  `Manage and debug resources deployed in Codesphere via command line.`,
 	}
 
 	opts := GlobalOptions{Env: cs.NewEnv()}
-
 	addLogCmd(rootCmd, opts)
 	addListCmd(rootCmd, opts)
 	addSetEnvVarCmd(rootCmd, opts)
 
 	opts.ApiUrl = rootCmd.PersistentFlags().StringP("api", "a", "https://codesphere.com/api", "URL of Codesphere API (can also be CS_API)")
 	opts.TeamId = rootCmd.PersistentFlags().IntP("team", "t", -1, "Team ID (relevant for some commands, can also be CS_TEAM_ID)")
 	opts.WorkspaceId = rootCmd.PersistentFlags().IntP("workspace", "w", -1, "Workspace ID (relevant for some commands, can also be CS_WORKSPACE_ID)")
+	return rootCmd
+}
 
-	err := rootCmd.Execute()
+func Execute() {
+	err := GetRootCmd().Execute()
 	if err != nil {
 		os.Exit(1)
 	}

cli/cmd/set-env-vars.go

@@ -7,6 +7,7 @@ import (
 	"fmt"
 	"strings"
 
+	"github.com/codesphere-cloud/cs-go/pkg/out"
 	"github.com/spf13/cobra"
 )
 
@@ -26,11 +27,10 @@ func addSetEnvVarCmd(p *cobra.Command, opts GlobalOptions) {
 			Use:   "set-env",
 			Short: "set env vars",
 			Long:  `set environment variables for your workspace`,
-			Example: `
-Set environment variables:
-
-$ cs set-env --workspace-id <workspace-id> --env foo=bar --env hello=world
-			`,
+			Example: out.FormatExampleCommands("set-env", map[string]string{
+				"--workspace-id <workspace-id> --env foo=bar":                   "Set single environment variable",
+				"--workspace-id <workspace-id> --env foo=bar --env hello=world": "Set multiple environment variables",
+			}),
 		},
 		Opts: SetEnvVarOptions{GlobalOptions: opts},
 	}

docs/README.md

@@ -0,0 +1,24 @@
+## cs
+
+The codesphere CLI
+
+### Synopsis
+
+Manage and debug resources deployed in Codesphere via command line.
+
+### Options
+
+```
+  -a, --api string      URL of Codesphere API (can also be CS_API) (default "https://codesphere.com/api")
+  -h, --help            help for cs
+  -t, --team int        Team ID (relevant for some commands, can also be CS_TEAM_ID) (default -1)
+  -w, --workspace int   Workspace ID (relevant for some commands, can also be CS_WORKSPACE_ID) (default -1)
+```
+
+### SEE ALSO
+
+* [cs list](cs_list.md)	 - list resources
+* [cs log](cs_log.md)	 - Retrieve Run logs from services
+* [cs set-env](cs_set-env.md)	 - set env vars
+
+###### Auto generated by spf13/cobra on 3-Jun-2025

docs/cs.md

@@ -0,0 +1,24 @@
+## cs
+
+The codesphere CLI
+
+### Synopsis
+
+Manage and debug resources deployed in Codesphere via command line.
+
+### Options
+
+```
+  -a, --api string      URL of Codesphere API (can also be CS_API) (default "https://codesphere.com/api")
+  -h, --help            help for cs
+  -t, --team int        Team ID (relevant for some commands, can also be CS_TEAM_ID) (default -1)
+  -w, --workspace int   Workspace ID (relevant for some commands, can also be CS_WORKSPACE_ID) (default -1)
+```
+
+### SEE ALSO
+
+* [cs list](cs_list.md)	 - list resources
+* [cs log](cs_log.md)	 - Retrieve Run logs from services
+* [cs set-env](cs_set-env.md)	 - set env vars
+
+###### Auto generated by spf13/cobra on 3-Jun-2025

docs/cs_list.md

@@ -0,0 +1,37 @@
+## cs list
+
+list resources
+
+### Synopsis
+
+list resources available in Codesphere
+
+### Examples
+
+```
+# List all workspaces
+$ cs list workspaces
+
+```
+
+### Options
+
+```
+  -h, --help   help for list
+```
+
+### Options inherited from parent commands
+
+```
+  -a, --api string      URL of Codesphere API (can also be CS_API) (default "https://codesphere.com/api")
+  -t, --team int        Team ID (relevant for some commands, can also be CS_TEAM_ID) (default -1)
+  -w, --workspace int   Workspace ID (relevant for some commands, can also be CS_WORKSPACE_ID) (default -1)
+```
+
+### SEE ALSO
+
+* [cs](cs.md)	 - The codesphere CLI
+* [cs list teams](cs_list_teams.md)	 - list teams
+* [cs list workspaces](cs_list_workspaces.md)	 - list workspaces
+
+###### Auto generated by spf13/cobra on 3-Jun-2025