Skip to content

Commit 275a3a7

Browse files
adombeckadombeck
authored
Add authctl docs (#1179)
Generate authctl docs via cobra. UDENG-8760
2 parents 7dd4884 + 0f1e87b commit 275a3a7

26 files changed

Lines changed: 372 additions & 69 deletions

‎cmd/authctl/group/set-gid.go‎

Lines changed: 8 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -20,22 +20,19 @@ var setGIDCmd = &cobra.Command{
2020
Short: "Set the GID of a group managed by authd",
2121
Long: `Set the GID of a group managed by authd to the specified value.
2222
23-
The new GID value must be unique and non-negative.
23+
The new GID must be unique and non-negative. The command must be run as root.
2424
25-
When a group's GID is changed, any users whose primary group is set to this group
26-
will have their primary group GID updated. The home directories of these users and
27-
files within them owned by the group will be updated to the new GID.
25+
When a group's GID is changed, any users whose primary group is set to this
26+
group will have the GID of their primary group updated. The home directories of
27+
these users, and any files within these directories that are owned by the group,
28+
will be updated to the new GID.
2829
2930
Files outside users' home directories are not updated and must be changed
3031
manually. Note that changing a GID can be unsafe if files on the system are
3132
still owned by the original GID: those files may become accessible to a
32-
different group that is later assigned that GID.
33-
34-
This command requires root privileges.
35-
36-
Examples:
37-
authctl group set-gid staff 30000
38-
authctl group set-gid developers 40000`,
33+
different group that is later assigned that GID.`,
34+
Example: ` # Set the GID of group "staff" to 30000
35+
authctl group set-gid staff 30000`,
3936
Args: cobra.ExactArgs(2),
4037
ValidArgsFunction: completion.Groups,
4138
RunE: func(cmd *cobra.Command, args []string) error {

‎cmd/authctl/group/set-gid_test.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ func TestSetGIDCommand(t *testing.T) {
5757
expectedExitCode: int(codes.Unknown),
5858
},
5959
"Error_when_gid_is_negative": {
60-
args: []string{"set-gid", "group1", "-1000"},
60+
args: []string{"set-gid", "group1", "--", "-1000"},
6161
expectedExitCode: 1,
6262
},
6363
"Error_when_authd_is_unavailable": {

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

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1 @@
1-
Usage:
2-
authctl group set-gid <name> <gid> [flags]
3-
4-
Flags:
5-
-h, --help help for set-gid
6-
7-
unknown shorthand flag: '1' in -1000
1+
failed to parse GID "-1000": invalid syntax

‎cmd/authctl/internal/docgen/main.go‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
// Package main generates CLI reference documentation.
2+
package main
3+
4+
import (
5+
"flag"
6+
"fmt"
7+
"log"
8+
"os"
9+
"path/filepath"
10+
"strings"
11+
12+
"github.com/canonical/authd/cmd/authctl/root"
13+
"github.com/spf13/cobra/doc"
14+
)
15+
16+
func main() {
17+
out := flag.String("out", "./docs/cli", "output directory")
18+
format := flag.String("format", "markdown", "markdown|man|rest")
19+
front := flag.Bool("frontmatter", false, "prepend simple YAML front matter to markdown")
20+
flag.Parse()
21+
22+
if err := os.MkdirAll(*out, 0o750); err != nil {
23+
log.Fatal(err)
24+
}
25+
26+
rootCmd := root.RootCmd
27+
rootCmd.DisableAutoGenTag = true // stable, reproducible files (no timestamp footer)
28+
29+
switch *format {
30+
case "markdown":
31+
if *front {
32+
prep := func(filename string) string {
33+
base := filepath.Base(filename)
34+
name := strings.TrimSuffix(base, filepath.Ext(base))
35+
title := strings.ReplaceAll(name, "_", " ")
36+
return fmt.Sprintf("---\ntitle: %q\nslug: %q\ndescription: \"CLI reference for %s\"\n---\n\n", title, name, title)
37+
}
38+
link := func(name string) string { return strings.ToLower(name) }
39+
if err := doc.GenMarkdownTreeCustom(rootCmd, *out, prep, link); err != nil {
40+
log.Fatal(err)
41+
}
42+
} else {
43+
if err := doc.GenMarkdownTree(rootCmd, *out); err != nil {
44+
log.Fatal(err)
45+
}
46+
}
47+
case "man":
48+
hdr := &doc.GenManHeader{Title: strings.ToUpper(rootCmd.Name()), Section: "1"}
49+
if err := doc.GenManTree(rootCmd, hdr, *out); err != nil {
50+
log.Fatal(err)
51+
}
52+
case "rest":
53+
if err := doc.GenReSTTree(rootCmd, *out); err != nil {
54+
log.Fatal(err)
55+
}
56+
default:
57+
log.Fatalf("unknown format: %s", *format)
58+
}
59+
}

‎cmd/authctl/main.go‎

Lines changed: 2 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -4,43 +4,14 @@ package main
44
import (
55
"os"
66

7-
"github.com/canonical/authd/cmd/authctl/group"
87
"github.com/canonical/authd/cmd/authctl/internal/log"
9-
"github.com/canonical/authd/cmd/authctl/user"
10-
"github.com/spf13/cobra"
8+
"github.com/canonical/authd/cmd/authctl/root"
119
"google.golang.org/grpc/codes"
1210
"google.golang.org/grpc/status"
1311
)
1412

15-
var rootCmd = &cobra.Command{
16-
Use: "authctl",
17-
Short: "CLI tool to interact with authd",
18-
Long: "authctl is a command-line tool to interact with the authd service for user and group management.",
19-
PersistentPreRun: func(cmd *cobra.Command, args []string) {
20-
// The command was successfully parsed, so we don't want cobra to print usage information on error.
21-
cmd.SilenceUsage = true
22-
},
23-
CompletionOptions: cobra.CompletionOptions{
24-
HiddenDefaultCmd: true,
25-
},
26-
// We handle errors ourselves
27-
SilenceErrors: true,
28-
Args: cobra.NoArgs,
29-
RunE: func(cmd *cobra.Command, args []string) error { return cmd.Usage() },
30-
}
31-
32-
func init() {
33-
// Disable command sorting by name. This makes cobra print the commands in the
34-
// order they are added to the root command and adds the `help` and `completion`
35-
// commands at the end.
36-
cobra.EnableCommandSorting = false
37-
38-
rootCmd.AddCommand(user.UserCmd)
39-
rootCmd.AddCommand(group.GroupCmd)
40-
}
41-
4213
func main() {
43-
if err := rootCmd.Execute(); err != nil {
14+
if err := root.RootCmd.Execute(); err != nil {
4415
s, ok := status.FromError(err)
4516
if !ok {
4617
// If the error is not a gRPC status, we print it as is.

‎cmd/authctl/root/root.go‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
// Package root contains the root command for authctl.
2+
package root
3+
4+
import (
5+
"github.com/canonical/authd/cmd/authctl/group"
6+
"github.com/canonical/authd/cmd/authctl/user"
7+
"github.com/spf13/cobra"
8+
)
9+
10+
// RootCmd is the root command for authctl.
11+
var RootCmd = &cobra.Command{
12+
Use: "authctl",
13+
Short: "CLI tool to interact with authd",
14+
Long: "authctl is a command-line tool to interact with the authd service for user and group management.",
15+
PersistentPreRun: func(cmd *cobra.Command, args []string) {
16+
// The command was successfully parsed, so we don't want cobra to print usage information on error.
17+
cmd.SilenceUsage = true
18+
},
19+
CompletionOptions: cobra.CompletionOptions{
20+
HiddenDefaultCmd: true,
21+
},
22+
// Avoid the "Auto generated by spf13/cobra" line in the generated markdown docs
23+
DisableAutoGenTag: true,
24+
// We handle errors ourselves
25+
SilenceErrors: true,
26+
Args: cobra.NoArgs,
27+
RunE: func(cmd *cobra.Command, args []string) error { return cmd.Usage() },
28+
}
29+
30+
func init() {
31+
// Disable command sorting by name. This makes cobra print the commands in the
32+
// order they are added to the root command and adds the `help` and `completion`
33+
// commands at the end.
34+
cobra.EnableCommandSorting = false
35+
36+
RootCmd.AddCommand(user.UserCmd)
37+
RootCmd.AddCommand(group.GroupCmd)
38+
}

‎cmd/authctl/user/lock.go‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@ import (
1313
var lockCmd = &cobra.Command{
1414
Use: "lock <user>",
1515
Short: "Lock (disable) a user managed by authd",
16+
Long: `Lock a user so that they cannot log in.`,
1617
Args: cobra.ExactArgs(1),
1718
ValidArgsFunction: completion.Users,
1819
RunE: func(cmd *cobra.Command, args []string) error {

‎cmd/authctl/user/set-uid.go‎

Lines changed: 6 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -20,21 +20,17 @@ var setUIDCmd = &cobra.Command{
2020
Short: "Set the UID of a user managed by authd",
2121
Long: `Set the UID of a user managed by authd to the specified value.
2222
23-
The new UID value must be unique and non-negative.
23+
The new UID must be unique and non-negative. The command must be run as root.
2424
25-
The user's home directory and any files within it owned by the user will
26-
automatically have their ownership updated to the new UID.
25+
The ownership of the user's home directory, and any files within the directory
26+
that the user owns, will automatically be updated to the new UID.
2727
2828
Files outside the user's home directory are not updated and must be changed
2929
manually. Note that changing a UID can be unsafe if files on the system are
3030
still owned by the original UID: those files may become accessible to a
31-
different account that is later assigned that UID.
32-
33-
This command requires root privileges.
34-
35-
Examples:
36-
authctl user set-uid john 15000
37-
authctl user set-uid alice 20000`,
31+
different account that is later assigned that UID.`,
32+
Example: ` # Set the UID of user "alice" to 15000
33+
authctl user set-uid alice 15000`,
3834
Args: cobra.ExactArgs(2),
3935
ValidArgsFunction: setUIDCompletionFunc,
4036
RunE: func(cmd *cobra.Command, args []string) error {

‎cmd/authctl/user/set-uid_test.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -57,7 +57,7 @@ func TestSetUIDCommand(t *testing.T) {
5757
expectedExitCode: int(codes.Unknown),
5858
},
5959
"Error_when_uid_is_negative": {
60-
args: []string{"set-uid", "user1", "-1000"},
60+
args: []string{"set-uid", "user1", "--", "-1000"},
6161
expectedExitCode: 1,
6262
},
6363
"Error_when_authd_is_unavailable": {

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

Lines changed: 1 addition & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1 @@
1-
Usage:
2-
authctl user set-uid <name> <uid> [flags]
3-
4-
Flags:
5-
-h, --help help for set-uid
6-
7-
unknown shorthand flag: '1' in -1000
1+
failed to parse UID "-1000": invalid syntax

0 commit comments

Comments
 (0)