STAC-24007: Update the help descriptions of the CLI (#128)

Author: viliakov

AGENTS.md

@@ -0,0 +1,198 @@
+# AGENTS.md
+
+This file provides guidance to OpenCode agents when working with code in this repository.
+
+## Important Product Naming
+
+**CRITICAL**: Always use "SUSE Observability" when referring to the product. "StackState" is deprecated and should not be used in new code, documentation, or communications.
+
+## Project Overview
+
+SUSE Observability CLI (`sts`) - A command-line tool for managing topology-powered observability within the SUSE Observability platform. Built with Go and Cobra framework.
+
+## Development Environment
+
+This project uses Nix Flakes for development environment management:
+
+```bash
+# Enter development shell (requires Nix with flakes enabled)
+nix develop
+
+# Build the CLI
+nix build
+
+# Or use Go directly
+go build -o sts main.go
+```
+
+## Common Commands
+
+```bash
+# Run CLI locally
+go run main.go
+
+# Run all tests
+go test -v ./...
+
+# Run tests for a specific package
+go test -v ./cmd/monitor/...
+
+# Run a single test
+go test -v ./cmd/monitor/... -run TestMonitorApply
+
+# Lint
+golangci-lint run
+
+# Regenerate OpenAPI clients (when openapi_version changes)
+nix develop -c ./scripts/generate_stackstate_api.sh
+```
+
+## Architecture
+
+### Command Structure Pattern
+
+All commands follow noun/verb/flags structure:
+```
+sts [noun] [verb] [flags]
+```
+Example: `sts context save --api-url URL --api-token TOKEN`
+
+### Key Components
+
+- **Entry point**: `main.go` - Sets up DI container, logging, error handling
+- **Commands**: `cmd/` - Each subdirectory is a command group (monitor/, settings/, etc.)
+- **DI Container**: `internal/di/Deps` - Dependency injection for testability
+- **API Clients**: `generated/stackstate_api/` and `generated/stackstate_admin_api/` - Auto-generated from OpenAPI
+- **Output**: `internal/printer/Printer` - All output must go through this interface
+- **Errors**: `internal/common/CLIError` - Custom error type with exit codes and usage hints
+
+### Code Generation
+
+OpenAPI clients are generated from external specs:
+- Version pinned in `stackstate_openapi/openapi_version`
+- Custom templates in `stackstate_openapi/template/`
+- Generated code in `generated/` - do not edit manually
+
+## Command Development Rules
+
+From CMD_DEVELOPMENT.md - critical rules for consistency:
+
+### Output
+- Always use `Printer` for stdout/stderr output
+- Every command must support both human-readable and JSON output (`-o json`)
+- Use logger for debug/verbose output, not Printer
+
+### Errors
+- Return `CLIError` from commands, don't print errors directly
+- Set `ShowUsage=true` for input/parsing errors
+- Set `ShowUsage=false` for API/technical errors
+
+### Help Text Requirements
+- `Use:` - Skeleton usage. Show required flags directly, mutually exclusive flags in `{}` with `|`
+- `Short:` - One sentence, no period, starts with verb
+- `Long:` - Full description with period
+- `Example:` - Copy-pasteable examples with `#` comments
+
+### Naming
+- Nouns plural if pertaining to a set of entities
+- Reuse verbs: `apply`, `list`, `describe`, `export`
+- Flag shorthands must be consistent across all commands (e.g., `-f` always means `--file`)
+
+## CLI Help Documentation Specialist
+
+**CRITICAL AGENT**: This agent manages cobra.Command help text according to ADR 001 and ADR 002.
+
+### Policy Overview
+Per ADR 001: CLI `--help` output is the **authoritative source** for command documentation. External docs provide overviews only. This means help text must be self-sufficient, consistent, and include practical examples.
+
+### Use Field Rules
+- **Noun-level commands**: `Use: "context"` (command appended automatically)
+- **Noun-verb commands**: `Use: "save --url URL {--api-token TOKEN | --service-token TOKEN}"`
+- **Required flags**: Show without brackets: `--url URL`
+- **Mutually exclusive required**: Group in `{}` with `|`: `{--api-token TOKEN | --service-token TOKEN}`
+- **Mutually exclusive optional**: Group in `[]` with `|`: `[--format JSON | --format YAML]`
+- **Flag values**: Use UPPER-CASE placeholders: `URL`, `TOKEN`, `FILE`
+
+### Short Field Rules
+- Start with **imperative verb** (Save, List, Delete, Show, Set, Validate)
+- Describe what the command does, not how
+- Use articles ("a", "the") appropriately
+- Maximum one sentence
+- **No period** at the end
+- Must add context beyond just command name
+
+Examples:
+- ✅ `"Save a connection context to the CLI configuration"`
+- ❌ `"Save a context"`
+- ✅ `"List all configured connection contexts"`
+- ❌ `"List contexts"`
+
+### Long Field Rules
+- Start with upper case, end with period
+- Can be multiple sentences
+- **Must add value** beyond Short - explain what the entity is, when to use, or outcome
+- Avoid excessive abbreviations
+- Provide context about the domain concept
+
+Examples:
+- ✅ `"Save a connection context to the CLI configuration file. A context stores the URL and authentication credentials for a SUSE Observability server, allowing you to switch between different servers or environments."`
+- ❌ `"Save a context."`
+
+### Example Field Rules
+- Use backtick-quoted multiline strings (not string concatenation)
+- Each example starts with `#` comment describing what it does
+- Comments: lowercase start, no period, imperative verb
+- Provide 2-3 examples covering common scenarios
+- Examples must be realistic and runnable
+- Cover different flag combinations when applicable
+
+Format:
+```go
+Example: `# save a context with an API token
+sts context save --name production --url https://suse-observability.example.com --api-token xxxx-xxxx
+
+# save a context with a service token for CI/CD
+sts context save --name ci-pipeline --url https://suse-observability.example.com --service-token xxxx-xxxx`
+```
+
+### Flag Description Rules
+- Start with upper case, no period at the end
+- Describe what the flag does, not implementation details
+- Include default value mention if non-obvious
+
+### Quality Checklist
+For every cobra.Command:
+- [ ] `Use` shows required flags and mutex groups correctly
+- [ ] `Short` starts with verb, no period, adds context beyond command name
+- [ ] `Long` adds value beyond `Short`, ends with period, explains domain concepts
+- [ ] `Example` has 2-3 realistic, copy-pasteable examples with lowercase comments
+- [ ] Flag descriptions are clear and properly capitalized
+- [ ] Uses "SUSE Observability" (not "StackState") in descriptions
+- [ ] No string concatenation - uses backtick multiline strings
+
+### When to Invoke This Agent
+- Creating new commands
+- Modifying existing command help text
+- Code reviews involving cobra.Command changes
+- Ensuring consistency across all CLI help documentation
+
+## Testing Patterns
+
+Commands are tested using mock DI container:
+
+```go
+func TestCommandName(t *testing.T) {
+    cli := di.NewMockDeps(t)
+    // Setup mocks
+    // Execute command
+    // Assert results
+}
+```
+
+Test utilities in `internal/di/mock_deps.go` and `internal/di/command_test_util.go`.
+
+## CI/CD
+
+- Linting: golangci-lint v2.3.1 (see `.golangci.yml`)
+- Tests run on every PR
+- Releases via GoReleaser on version tags (`v*`)

cmd/agent.go

@@ -9,8 +9,8 @@ import (
 func AgentCommand(deps *di.Deps) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "agent",
-		Short: "Manage the StackState agents",
-		Long:  "Manage the StackState agents.",
+		Short: "Manage SUSE Observability agents and their registrations",
+		Long:  `Manage SUSE Observability agents. Agents collect and send topology, telemetry, and traces data from monitored systems to SUSE Observability.`,
 	}
 
 	cmd.AddCommand(agent.ListCommand(deps))

cmd/agent/agent_list.go

@@ -16,9 +16,14 @@ import (
 func ListCommand(deps *di.Deps) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list",
-		Short: "List all registered agents",
-		Long:  "List all registered agents.",
-		RunE:  deps.CmdRunEWithApi(RunListCommand),
+		Short: "List all registered agents with their lease status",
+		Long:  `List all registered agents showing their lease status (active, limited, stale), registration time, hardware info, and node budget. Displays totals for each lease status.`,
+		Example: `# list all agents
+sts agent list
+
+# list agents in JSON format for scripting
+sts agent list -o json`,
+		RunE: deps.CmdRunEWithApi(RunListCommand),
 	}
 
 	return cmd

cmd/context.go

@@ -9,8 +9,8 @@ import (
 func ContextCommand(cli *di.Deps) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "context",
-		Short: "Manage StackState contexts",
-		Long:  "Manage connections to different StackState servers.",
+		Short: "Manage CLI connection contexts for SUSE Observability servers",
+		Long:  `Manage CLI connection contexts. A context stores the URL and authentication credentials for a SUSE Observability server, allowing you to switch between different servers or environments without re-entering connection details.`,
 	}
 
 	cmd.AddCommand(context.SaveCommand(cli))

cmd/context/common.go

@@ -23,7 +23,7 @@ func PrintConnectionSuccess(pr printer.Printer, apiUrl string, serverInfo *stack
 	} else {
 		// Fallback to serverInfo.Version if platformVersion is not present (an updated client could interact with a server not supporting PlatformVersion yet).
 		pr.Success(
-			fmt.Sprintf("Connection verified to %s (StackState version: %s)",
+			fmt.Sprintf("Connection verified to %s (SUSE Observability version: %s)",
 				apiUrl,
 				client.VersionToString(serverInfo.Version),
 			),

cmd/context/context_delete.go

@@ -16,10 +16,12 @@ type DeleteArgs struct {
 func DeleteCommand(cli *di.Deps) *cobra.Command {
 	args := &DeleteArgs{}
 	cmd := &cobra.Command{
-		Use:   "delete",
-		Short: "Delete a context",
-		Long:  "Delete a context from the local config file.",
-		RunE:  cli.CmdRunEWithConfig(RunContextDeleteCommand(args)),
+		Use:   "delete --name NAME",
+		Short: "Delete a saved context from the CLI configuration",
+		Long:  "Delete a connection context from the CLI configuration file. The currently active context cannot be deleted; switch to a different context first.",
+		Example: `# delete an unused context
+sts context delete --name old-staging`,
+		RunE: cli.CmdRunEWithConfig(RunContextDeleteCommand(args)),
 	}
 
 	common.AddRequiredNameFlagVar(cmd, &args.Name, "Name of the context")

cmd/context/context_list.go

@@ -11,9 +11,14 @@ import (
 func ListCommand(deps *di.Deps) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "list",
-		Short: "List available contexts",
-		Long:  "List available contexts in the config file.",
-		RunE:  deps.CmdRunEWithConfig(RunContextListCommand),
+		Short: "List all configured connection contexts",
+		Long:  "List all connection contexts saved in the CLI configuration file, showing the context name and server URL for each.",
+		Example: `# list all contexts
+sts context list
+
+# list contexts in JSON format
+sts context list -o json`,
+		RunE: deps.CmdRunEWithConfig(RunContextListCommand),
 	}
 
 	return cmd

cmd/context/context_save.go

@@ -30,10 +30,18 @@ type SaveArgs struct {
 func SaveCommand(cli *di.Deps) *cobra.Command {
 	args := &SaveArgs{}
 	cmd := &cobra.Command{
-		Use:   "save",
-		Short: "Save a context",
-		Long:  "Save a context to the local config file.",
-		RunE:  cli.CmdRunE(RunContextSaveCommand(args)),
+		Use:   "save --url URL {--api-token TOKEN | --service-token TOKEN}",
+		Short: "Save a connection context to the CLI configuration",
+		Long:  `Save a connection context to the CLI configuration file. The context stores the server URL and authentication credentials. After saving, this context becomes the current active context.`,
+		Example: `# save a context with an API token
+sts context save --name production --url https://stackstate.example.com --api-token xxxx-xxxx
+
+# save a context with a service token for CI/CD pipelines
+sts context save --name ci --url https://stackstate.example.com --service-token xxxx-xxxx
+
+# save a context with a custom CA certificate
+sts context save --name production --url https://stackstate.example.com --api-token xxxx-xxxx --ca-cert /path/to/ca.crt`,
+		RunE: cli.CmdRunE(RunContextSaveCommand(args)),
 	}
 
 	common.AddNameFlagVarVal(cmd, &args.Name, "default", "Name of the context")

cmd/context/context_set.go

@@ -16,10 +16,15 @@ type SetArgs struct {
 func SetCommand(cli *di.Deps) *cobra.Command {
 	args := &SetArgs{}
 	cmd := &cobra.Command{
-		Use:   "set",
-		Short: "Set the current context",
-		Long:  "Set the current context.",
-		RunE:  cli.CmdRunEWithConfig(RunContextSetCommand(args, cli)),
+		Use:   "set --name NAME",
+		Short: "Set the active context to use for CLI commands",
+		Long:  "Set the active connection context. All subsequent CLI commands will use this context's server URL and credentials.",
+		Example: `# switch to the production context
+sts context set --name production
+
+# switch to a different environment
+sts context set --name staging`,
+		RunE: cli.CmdRunEWithConfig(RunContextSetCommand(args, cli)),
 	}
 
 	common.AddRequiredNameFlagVar(cmd, &args.Name, "Name of the context")

cmd/context/context_show.go

@@ -10,9 +10,14 @@ import (
 func ShowCommand(deps *di.Deps) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "show",
-		Short: "Show the current context",
-		Long:  "Show the current context.",
-		RunE:  deps.CmdRunEWithConfig(RunContextShowCommand),
+		Short: "Display the currently active context",
+		Long:  "Display the name of the currently active connection context. Use 'sts context list' to see all available contexts.",
+		Example: `# show the current context name
+sts context show
+
+# show current context details in JSON format
+sts context show -o json`,
+		RunE: deps.CmdRunEWithConfig(RunContextShowCommand),
 	}
 
 	return cmd