Partially onboard folder command (alpha)

docs/stackit_alpha.md

@@ -41,5 +41,6 @@ stackit alpha [flags]
 ### SEE ALSO
 
 * [stackit](./stackit.md)	 - Manage STACKIT resources using the command line
+* [stackit alpha folder](./stackit_alpha_folder.md)	 - Manages the lifecycle of folders.
 * [stackit alpha vpc](./stackit_alpha_vpc.md)	 - Manages vpcs
 

docs/stackit_alpha_folder.md

@@ -0,0 +1,36 @@
+## stackit alpha folder
+
+Manages the lifecycle of folders.
+
+### Synopsis
+
+Manages the lifecycle of folders.
+A folder provides a structure for organizing projects within an organization.
+
+```
+stackit alpha folder [flags]
+```
+
+### Options
+
+```
+  -h, --help   Help for "stackit alpha folder"
+```
+
+### Options inherited from parent commands
+
+```
+  -y, --assume-yes             If set, skips all confirmation prompts
+      --async                  If set, runs the command asynchronously
+  -o, --output-format string   Output format, (one of: [json, pretty, none, yaml])
+  -p, --project-id string      Project ID
+      --region string          Target region for region-specific requests
+      --verbosity string       Verbosity of the CLI, (one of: [debug, info, warning, error]) (default "info")
+```
+
+### SEE ALSO
+
+* [stackit alpha](./stackit_alpha.md)	 - Contains alpha STACKIT CLI commands
+* [stackit alpha folder describe](./stackit_alpha_folder_describe.md)	 - Shows details of a STACKIT folder
+* [stackit alpha folder list](./stackit_alpha_folder_list.md)	 - Lists STACKIT folders
+

docs/stackit_alpha_folder_describe.md

@@ -0,0 +1,47 @@
+## stackit alpha folder describe
+
+Shows details of a STACKIT folder
+
+### Synopsis
+
+Shows details of a STACKIT folder.
+
+```
+stackit alpha folder describe [flags]
+```
+
+### Examples
+
+```
+  Get the details of the configured STACKIT folder
+  $ stackit folder describe
+
+  Get the details of a STACKIT folder by explicitly providing the container ID
+  $ stackit folder describe xxx
+
+  Get the details of the configured STACKIT folder, including details of the parent resources
+  $ stackit folder describe --include-parents
+```
+
+### Options
+
+```
+  -h, --help              Help for "stackit alpha folder describe"
+      --include-parents   When true, the details of the parent resources will be included in the output
+```
+
+### Options inherited from parent commands
+
+```
+  -y, --assume-yes             If set, skips all confirmation prompts
+      --async                  If set, runs the command asynchronously
+  -o, --output-format string   Output format, (one of: [json, pretty, none, yaml])
+  -p, --project-id string      Project ID
+      --region string          Target region for region-specific requests
+      --verbosity string       Verbosity of the CLI, (one of: [debug, info, warning, error]) (default "info")
+```
+
+### SEE ALSO
+
+* [stackit alpha folder](./stackit_alpha_folder.md)	 - Manages the lifecycle of folders.
+

docs/stackit_alpha_folder_list.md

@@ -0,0 +1,55 @@
+## stackit alpha folder list
+
+Lists STACKIT folders
+
+### Synopsis
+
+Lists all STACKIT folders that match certain criteria.
+
+```
+stackit alpha folder list [flags]
+```
+
+### Examples
+
+```
+  List all STACKIT folders that are children of the configured project
+  $ stackit folder list
+
+  List all STACKIT folders that are children of a specific parent
+  $ stackit folder list --parent-id xxx
+
+  List all STACKIT folders that match the given project IDs, located under the same parent resource
+  $ stackit folder list --project-id-like xxx,yyy,zzz
+
+  List all STACKIT folders that a certain user is a member of
+  $ stackit folder list --member example@email.com
+```
+
+### Options
+
+```
+      --creation-time-after string   Filter by creation timestamp, in a date-time with the RFC3339 layout format, e.g. 2023-01-01T00:00:00Z. The list of folders that were created after the given timestamp will be shown
+  -h, --help                         Help for "stackit alpha folder list"
+      --limit int                    Maximum number of entries to list
+      --member string                Filter by member. The list of folders of which the member is part of will be shown
+      --page-size int                Number of items fetched in each API call. Does not affect the number of items in the command output (default 50)
+      --parent-id string             Filter by parent identifier
+      --project-id-like strings      Filter by project identifier. Multiple project IDs can be provided, but they need to belong to the same parent resource (default [])
+```
+
+### Options inherited from parent commands
+
+```
+  -y, --assume-yes             If set, skips all confirmation prompts
+      --async                  If set, runs the command asynchronously
+  -o, --output-format string   Output format, (one of: [json, pretty, none, yaml])
+  -p, --project-id string      Project ID
+      --region string          Target region for region-specific requests
+      --verbosity string       Verbosity of the CLI, (one of: [debug, info, warning, error]) (default "info")
+```
+
+### SEE ALSO
+
+* [stackit alpha folder](./stackit_alpha_folder.md)	 - Manages the lifecycle of folders.
+

internal/cmd/alpha/alpha.go

@@ -5,6 +5,7 @@ import (
 
 	"github.com/spf13/cobra"
 
+	"github.com/stackitcloud/stackit-cli/internal/cmd/alpha/folder"
 	"github.com/stackitcloud/stackit-cli/internal/cmd/alpha/vpc"
 	"github.com/stackitcloud/stackit-cli/internal/pkg/args"
 	"github.com/stackitcloud/stackit-cli/internal/pkg/examples"
@@ -35,5 +36,6 @@ func NewCmd(params *types.CmdParams) *cobra.Command {
 }
 
 func addSubcommands(cmd *cobra.Command, params *types.CmdParams) {
+	cmd.AddCommand(folder.NewCmd(params))
 	cmd.AddCommand(vpc.NewCmd(params))
 }

internal/cmd/alpha/folder/describe/describe.go

@@ -0,0 +1,144 @@
+package describe
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/stackitcloud/stackit-cli/internal/pkg/types"
+
+	"github.com/stackitcloud/stackit-cli/internal/pkg/args"
+	"github.com/stackitcloud/stackit-cli/internal/pkg/examples"
+	"github.com/stackitcloud/stackit-cli/internal/pkg/flags"
+	"github.com/stackitcloud/stackit-cli/internal/pkg/globalflags"
+	"github.com/stackitcloud/stackit-cli/internal/pkg/print"
+	"github.com/stackitcloud/stackit-cli/internal/pkg/services/resourcemanager/client"
+	"github.com/stackitcloud/stackit-cli/internal/pkg/tables"
+	"github.com/stackitcloud/stackit-cli/internal/pkg/utils"
+
+	"github.com/spf13/cobra"
+	resourcemanager "github.com/stackitcloud/stackit-sdk-go/services/resourcemanager/v0api"
+)
+
+const (
+	includeParentsFlag = "include-parents"
+
+	containerIdArg = "CONTAINER_ID"
+)
+
+type inputModel struct {
+	*globalflags.GlobalFlagModel
+	ArgContainerId string
+	IncludeParents bool
+}
+
+func NewCmd(params *types.CmdParams) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "describe",
+		Short: "Shows details of a STACKIT folder",
+		Long:  "Shows details of a STACKIT folder.",
+		Args:  args.SingleOptionalArg(containerIdArg, utils.ValidateUUID),
+		Example: examples.Build(
+			examples.NewExample(
+				`Get the details of the configured STACKIT folder`,
+				"$ stackit folder describe"),
+			examples.NewExample(
+				`Get the details of a STACKIT folder by explicitly providing the container ID`,
+				"$ stackit folder describe xxx"),
+			examples.NewExample(
+				`Get the details of the configured STACKIT folder, including details of the parent resources`,
+				"$ stackit folder describe --include-parents"),
+		),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			ctx := context.Background()
+			model, err := parseInput(params.Printer, cmd, args)
+			if err != nil {
+				return err
+			}
+
+			// Configure API client
+			apiClient, err := client.ConfigureClient(params.Printer, params.CliVersion)
+			if err != nil {
+				return err
+			}
+
+			// Call API
+			req := buildRequest(ctx, model, apiClient)
+			resp, err := req.Execute()
+			if err != nil {
+				return fmt.Errorf("read folder details: %w", err)
+			}
+
+			return outputResult(params.Printer, model.OutputFormat, resp)
+		},
+	}
+	configureFlags(cmd)
+	return cmd
+}
+
+func configureFlags(cmd *cobra.Command) {
+	cmd.Flags().Bool(includeParentsFlag, false, "When true, the details of the parent resources will be included in the output")
+}
+
+func parseInput(p *print.Printer, cmd *cobra.Command, inputArgs []string) (*inputModel, error) {
+	var containerId string
+	if len(inputArgs) > 0 {
+		containerId = inputArgs[0]
+	}
+
+	globalFlags := globalflags.Parse(p, cmd)
+	if globalFlags.ProjectId == "" && containerId == "" {
+		return nil, fmt.Errorf("container ID needs to be provided either as an argument or as a flag")
+	}
+
+	if containerId == "" {
+		containerId = globalFlags.ProjectId
+	}
+
+	model := inputModel{
+		GlobalFlagModel: globalFlags,
+		ArgContainerId:  containerId,
+		IncludeParents:  flags.FlagToBoolValue(p, cmd, includeParentsFlag),
+	}
+
+	p.DebugInputModel(model)
+	return &model, nil
+}
+
+func buildRequest(ctx context.Context, model *inputModel, apiClient *resourcemanager.APIClient) resourcemanager.ApiGetFolderDetailsRequest {
+	req := apiClient.DefaultAPI.GetFolderDetails(ctx, model.ArgContainerId)
+	req.IncludeParents(model.IncludeParents)
+	return req
+}
+
+func outputResult(p *print.Printer, outputFormat string, folder *resourcemanager.GetFolderDetailsResponse) error {
+	if folder == nil {
+		return fmt.Errorf("response not set")
+	}
+
+	return p.OutputResult(outputFormat, folder, func() error {
+		table := tables.NewTable()
+		table.AddRow("ID", folder.FolderId)
+		table.AddSeparator()
+		table.AddRow("NAME", folder.Name)
+		table.AddSeparator()
+		table.AddRow("CREATION", folder.CreationTime)
+		table.AddSeparator()
+		table.AddRow("CONTAINER ID", folder.ContainerId)
+		table.AddSeparator()
+		table.AddRow("PARENT ID", folder.Parent.Id)
+
+		var labels string
+		if folder.Labels != nil {
+			labels = utils.JoinStringMap(*folder.Labels, "=", ", ")
+		}
+		table.AddSeparator()
+		table.AddRow("LABELS", labels)
+
+		err := table.Display(p)
+		if err != nil {
+			return fmt.Errorf("render table: %w", err)
+		}
+
+		return nil
+	})
+}