Add authctl docs

cmd/authctl/group/set-gid.go

@@ -20,22 +20,19 @@ var setGIDCmd = &cobra.Command{
 	Short: "Set the GID of a group managed by authd",
 	Long: `Set the GID of a group managed by authd to the specified value.
 
-The new GID value must be unique and non-negative.
+The new GID must be unique and non-negative. The command must be run as root.
 
-When a group's GID is changed, any users whose primary group is set to this group
-will have their primary group GID updated. The home directories of these users and
-files within them owned by the group will be updated to the new GID.
+When a group's GID is changed, any users whose primary group is set to this
+group will have the GID of their primary group updated. The home directories of
+these users, and any files within these directories that are owned by the group,
+will be updated to the new GID.
 
 Files outside users' home directories are not updated and must be changed
 manually. Note that changing a GID can be unsafe if files on the system are
 still owned by the original GID: those files may become accessible to a
-different group that is later assigned that GID.
-
-This command requires root privileges.
-
-Examples:
-  authctl group set-gid staff 30000
-  authctl group set-gid developers 40000`,
+different group that is later assigned that GID.`,
+	Example: `  # Set the GID of group "staff" to 30000
+  authctl group set-gid staff 30000`,
 	Args:              cobra.ExactArgs(2),
 	ValidArgsFunction: completion.Groups,
 	RunE: func(cmd *cobra.Command, args []string) error {

cmd/authctl/group/set-gid_test.go

@@ -57,7 +57,7 @@ func TestSetGIDCommand(t *testing.T) {
 			expectedExitCode: int(codes.Unknown),
 		},
 		"Error_when_gid_is_negative": {
-			args:             []string{"set-gid", "group1", "-1000"},
+			args:             []string{"set-gid", "group1", "--", "-1000"},
 			expectedExitCode: 1,
 		},
 		"Error_when_authd_is_unavailable": {

cmd/authctl/group/testdata/golden/TestSetGIDCommand/Error_when_gid_is_negative

@@ -1,7 +1 @@
-Usage:
-  authctl group set-gid <name> <gid> [flags]
-
-Flags:
-  -h, --help   help for set-gid
-
-unknown shorthand flag: '1' in -1000
+failed to parse GID "-1000": invalid syntax

cmd/authctl/internal/docgen/main.go

@@ -0,0 +1,59 @@
+// Package main generates CLI reference documentation.
+package main
+
+import (
+	"flag"
+	"fmt"
+	"log"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/canonical/authd/cmd/authctl/root"
+	"github.com/spf13/cobra/doc"
+)
+
+func main() {
+	out := flag.String("out", "./docs/cli", "output directory")
+	format := flag.String("format", "markdown", "markdown|man|rest")
+	front := flag.Bool("frontmatter", false, "prepend simple YAML front matter to markdown")
+	flag.Parse()
+
+	if err := os.MkdirAll(*out, 0o750); err != nil {
+		log.Fatal(err)
+	}
+
+	rootCmd := root.RootCmd
+	rootCmd.DisableAutoGenTag = true // stable, reproducible files (no timestamp footer)
+
+	switch *format {
+	case "markdown":
+		if *front {
+			prep := func(filename string) string {
+				base := filepath.Base(filename)
+				name := strings.TrimSuffix(base, filepath.Ext(base))
+				title := strings.ReplaceAll(name, "_", " ")
+				return fmt.Sprintf("---\ntitle: %q\nslug: %q\ndescription: \"CLI reference for %s\"\n---\n\n", title, name, title)
+			}
+			link := func(name string) string { return strings.ToLower(name) }
+			if err := doc.GenMarkdownTreeCustom(rootCmd, *out, prep, link); err != nil {
+				log.Fatal(err)
+			}
+		} else {
+			if err := doc.GenMarkdownTree(rootCmd, *out); err != nil {
+				log.Fatal(err)
+			}
+		}
+	case "man":
+		hdr := &doc.GenManHeader{Title: strings.ToUpper(rootCmd.Name()), Section: "1"}
+		if err := doc.GenManTree(rootCmd, hdr, *out); err != nil {
+			log.Fatal(err)
+		}
+	case "rest":
+		if err := doc.GenReSTTree(rootCmd, *out); err != nil {
+			log.Fatal(err)
+		}
+	default:
+		log.Fatalf("unknown format: %s", *format)
+	}
+}

cmd/authctl/main.go

@@ -4,43 +4,14 @@ package main
 import (
 	"os"
 
-	"github.com/canonical/authd/cmd/authctl/group"
 	"github.com/canonical/authd/cmd/authctl/internal/log"
-	"github.com/canonical/authd/cmd/authctl/user"
-	"github.com/spf13/cobra"
+	"github.com/canonical/authd/cmd/authctl/root"
 	"google.golang.org/grpc/codes"
 	"google.golang.org/grpc/status"
 )
 
-var rootCmd = &cobra.Command{
-	Use:   "authctl",
-	Short: "CLI tool to interact with authd",
-	Long:  "authctl is a command-line tool to interact with the authd service for user and group management.",
-	PersistentPreRun: func(cmd *cobra.Command, args []string) {
-		// The command was successfully parsed, so we don't want cobra to print usage information on error.
-		cmd.SilenceUsage = true
-	},
-	CompletionOptions: cobra.CompletionOptions{
-		HiddenDefaultCmd: true,
-	},
-	// We handle errors ourselves
-	SilenceErrors: true,
-	Args:          cobra.NoArgs,
-	RunE:          func(cmd *cobra.Command, args []string) error { return cmd.Usage() },
-}
-
-func init() {
-	// Disable command sorting by name. This makes cobra print the commands in the
-	// order they are added to the root command and adds the `help` and `completion`
-	// commands at the end.
-	cobra.EnableCommandSorting = false
-
-	rootCmd.AddCommand(user.UserCmd)
-	rootCmd.AddCommand(group.GroupCmd)
-}
-
 func main() {
-	if err := rootCmd.Execute(); err != nil {
+	if err := root.RootCmd.Execute(); err != nil {
 		s, ok := status.FromError(err)
 		if !ok {
 			// If the error is not a gRPC status, we print it as is.

cmd/authctl/root/root.go

@@ -0,0 +1,38 @@
+// Package root contains the root command for authctl.
+package root
+
+import (
+	"github.com/canonical/authd/cmd/authctl/group"
+	"github.com/canonical/authd/cmd/authctl/user"
+	"github.com/spf13/cobra"
+)
+
+// RootCmd is the root command for authctl.
+var RootCmd = &cobra.Command{
+	Use:   "authctl",
+	Short: "CLI tool to interact with authd",
+	Long:  "authctl is a command-line tool to interact with the authd service for user and group management.",
+	PersistentPreRun: func(cmd *cobra.Command, args []string) {
+		// The command was successfully parsed, so we don't want cobra to print usage information on error.
+		cmd.SilenceUsage = true
+	},
+	CompletionOptions: cobra.CompletionOptions{
+		HiddenDefaultCmd: true,
+	},
+	// Avoid the "Auto generated by spf13/cobra" line in the generated markdown docs
+	DisableAutoGenTag: true,
+	// We handle errors ourselves
+	SilenceErrors: true,
+	Args:          cobra.NoArgs,
+	RunE:          func(cmd *cobra.Command, args []string) error { return cmd.Usage() },
+}
+
+func init() {
+	// Disable command sorting by name. This makes cobra print the commands in the
+	// order they are added to the root command and adds the `help` and `completion`
+	// commands at the end.
+	cobra.EnableCommandSorting = false
+
+	RootCmd.AddCommand(user.UserCmd)
+	RootCmd.AddCommand(group.GroupCmd)
+}

cmd/authctl/user/lock.go

@@ -13,6 +13,7 @@ import (
 var lockCmd = &cobra.Command{
 	Use:               "lock <user>",
 	Short:             "Lock (disable) a user managed by authd",
+	Long:              `Lock a user so that they cannot log in.`,
 	Args:              cobra.ExactArgs(1),
 	ValidArgsFunction: completion.Users,
 	RunE: func(cmd *cobra.Command, args []string) error {

cmd/authctl/user/set-uid.go

@@ -20,21 +20,17 @@ var setUIDCmd = &cobra.Command{
 	Short: "Set the UID of a user managed by authd",
 	Long: `Set the UID of a user managed by authd to the specified value.
 
-The new UID value must be unique and non-negative.
+The new UID must be unique and non-negative. The command must be run as root.
 
-The user's home directory and any files within it owned by the user will
-automatically have their ownership updated to the new UID.
+The ownership of the user's home directory, and any files within the directory
+that the user owns, will automatically be updated to the new UID.
 
 Files outside the user's home directory are not updated and must be changed
 manually. Note that changing a UID can be unsafe if files on the system are
 still owned by the original UID: those files may become accessible to a
-different account that is later assigned that UID.
-
-This command requires root privileges.
-
-Examples:
-  authctl user set-uid john 15000
-  authctl user set-uid alice 20000`,
+different account that is later assigned that UID.`,
+	Example: `  # Set the UID of user "alice" to 15000
+  authctl user set-uid alice 15000`,
 	Args:              cobra.ExactArgs(2),
 	ValidArgsFunction: setUIDCompletionFunc,
 	RunE: func(cmd *cobra.Command, args []string) error {

cmd/authctl/user/set-uid_test.go

@@ -57,7 +57,7 @@ func TestSetUIDCommand(t *testing.T) {
 			expectedExitCode: int(codes.Unknown),
 		},
 		"Error_when_uid_is_negative": {
-			args:             []string{"set-uid", "user1", "-1000"},
+			args:             []string{"set-uid", "user1", "--", "-1000"},
 			expectedExitCode: 1,
 		},
 		"Error_when_authd_is_unavailable": {

cmd/authctl/user/testdata/golden/TestSetUIDCommand/Error_when_uid_is_negative

@@ -1,7 +1 @@
-Usage:
-  authctl user set-uid <name> <uid> [flags]
-
-Flags:
-  -h, --help   help for set-uid
-
-unknown shorthand flag: '1' in -1000
+failed to parse UID "-1000": invalid syntax

cmd/authctl/user/unlock.go

@@ -13,6 +13,7 @@ import (
 var unlockCmd = &cobra.Command{
 	Use:               "unlock <user>",
 	Short:             "Unlock (enable) a user managed by authd",
+	Long:              `Unlock a locked user so that they can log in again.`,
 	Args:              cobra.ExactArgs(1),
 	ValidArgsFunction: completion.Users,
 	RunE: func(cmd *cobra.Command, args []string) error {

debian/rules

@@ -46,7 +46,7 @@ export AUTHD_SKIP_ROOT_TESTS := 1
 # Defines the targets to be built as part of dh_auto_build
 export DH_GOLANG_BUILDPKG := $(AUTHD_GO_PACKAGE)/... \
 	$(NULL)
-export DH_GOLANG_EXCLUDES := authd-oidc-brokers/
+export DH_GOLANG_EXCLUDES := authd-oidc-brokers/ cmd/authctl/internal/docgen/
 export DH_GOLANG_EXCLUDES_ALL := 1
 
 # We add the required backported version to the $PATH so that if it exists, then

docs/.custom_wordlist.txt

@@ -1,6 +1,7 @@
 alice
 amd
 auth
+authctl
 authd
 authd's
 biometric

docs/conf.py

@@ -373,3 +373,9 @@
     'starter-pack': ('https://canonical-example-product-documentation.readthedocs-hosted.com/en/latest', None),
     'sphinxcontrib-mermaid': ('https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest', None)
 }
+
+# Suppress warnings
+
+suppress_warnings = [
+    "myst.header", # Suppress warnings relating to headers of autogenerated Cobra docs
+]

docs/generate.go

@@ -0,0 +1,7 @@
+//go:build generate
+
+// TiCS: disabled // This is a helper file to generate the CLI documentation
+
+//go:generate sh -c "go run ../cmd/authctl/internal/docgen -format markdown -out reference/cli"
+
+package docs

docs/reference/cli/authctl.md

@@ -0,0 +1,23 @@
+## authctl
+
+CLI tool to interact with authd
+
+### Synopsis
+
+authctl is a command-line tool to interact with the authd service for user and group management.
+
+```
+authctl [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for authctl
+```
+
+### SEE ALSO
+
+* [authctl group](authctl_group.md)	 - Commands related to groups
+* [authctl user](authctl_user.md)	 - Commands related to users
+

docs/reference/cli/authctl_group.md

@@ -0,0 +1,19 @@
+## authctl group
+
+Commands related to groups
+
+```
+authctl group [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for group
+```
+
+### SEE ALSO
+
+* [authctl](authctl.md)	 - CLI tool to interact with authd
+* [authctl group set-gid](authctl_group_set-gid.md)	 - Set the GID of a group managed by authd
+

docs/reference/cli/authctl_group_set-gid.md

@@ -0,0 +1,41 @@
+## authctl group set-gid
+
+Set the GID of a group managed by authd
+
+### Synopsis
+
+Set the GID of a group managed by authd to the specified value.
+
+The new GID must be unique and non-negative. The command must be run as root.
+
+When a group's GID is changed, any users whose primary group is set to this
+group will have the GID of their primary group updated. The home directories of
+these users, and any files within these directories that are owned by the group,
+will be updated to the new GID.
+
+Files outside users' home directories are not updated and must be changed
+manually. Note that changing a GID can be unsafe if files on the system are
+still owned by the original GID: those files may become accessible to a
+different group that is later assigned that GID.
+
+```
+authctl group set-gid <name> <gid> [flags]
+```
+
+### Examples
+
+```
+  # Set the GID of group "staff" to 30000
+  authctl group set-gid staff 30000
+```
+
+### Options
+
+```
+  -h, --help   help for set-gid
+```
+
+### SEE ALSO
+
+* [authctl group](authctl_group.md)	 - Commands related to groups
+

docs/reference/cli/authctl_user.md

@@ -0,0 +1,21 @@
+## authctl user
+
+Commands related to users
+
+```
+authctl user [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for user
+```
+
+### SEE ALSO
+
+* [authctl](authctl.md)	 - CLI tool to interact with authd
+* [authctl user lock](authctl_user_lock.md)	 - Lock (disable) a user managed by authd
+* [authctl user set-uid](authctl_user_set-uid.md)	 - Set the UID of a user managed by authd
+* [authctl user unlock](authctl_user_unlock.md)	 - Unlock (enable) a user managed by authd
+