docs: improve CLI documentation (#503)

cmd/check/root.go

@@ -24,8 +24,10 @@ func (o *checkOutput) String() string {
 
 func newCheckCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:  "check <subject> <relation> <namespace> <object>",
-		Args: cobra.ExactArgs(4),
+		Use:   "check <subject> <relation> <namespace> <object>",
+		Short: "Check whether a subject has a relation on an object",
+		Long:  "Check whether a subject has a relation on an object. This method resolves subject sets and subject set rewrites.",
+		Args:  cobra.ExactArgs(4),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			conn, err := client.GetReadConn(cmd)
 			if err != nil {

cmd/expand/root.go

@@ -17,8 +17,10 @@ const FlagMaxDepth = "max-depth"
 
 func NewExpandCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:  "expand <relation> <namespace> <object>",
-		Args: cobra.ExactArgs(3),
+		Use:   "expand <relation> <namespace> <object>",
+		Short: "Expand a subject set",
+		Long:  "Expand a subject set into a tree of subjects.",
+		Args:  cobra.ExactArgs(3),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			conn, err := client.GetReadConn(cmd)
 			if err != nil {

cmd/migrate/down.go

@@ -14,7 +14,11 @@ import (
 
 func newDownCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:  "down <steps>",
+		Use:   "down <steps>",
+		Short: "Migrate the database down",
+		Long: "Migrate the database down a specific amount of steps.\n" +
+			"Pass 0 steps to fully migrate down.\n" +
+			"This does not affect namespaces. Use `keto namespace migrate down` for migrating namespaces.",
 		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()

cmd/migrate/root.go

@@ -4,7 +4,10 @@ import "github.com/spf13/cobra"
 
 func newMigrateCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use: "migrate",
+		Use:   "migrate",
+		Short: "Commands to migrate the database",
+		Long: "Commands to migrate the database.\n" +
+			"This does not affect namespaces. Use `keto namespace migrate` for migrating namespaces.",
 	}
 	cmd.AddCommand(
 		newStatusCmd(),

cmd/migrate/status.go

@@ -11,7 +11,10 @@ import (
 
 func newStatusCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use: "status",
+		Use:   "status",
+		Short: "Get the current migration status",
+		Long: "Get the current migration status.\n" +
+			"This does not affect namespaces. Use `keto namespace migrate status` for migrating namespaces.",
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			ctx := cmd.Context()
 

cmd/migrate/up.go

@@ -24,7 +24,11 @@ func newUpCmd() *cobra.Command {
 	var allNamespaces bool
 
 	cmd := &cobra.Command{
-		Use: "up",
+		Use:   "up",
+		Short: "Migrate the database up",
+		Long: "Migrate the database up.\n" +
+			"This does not affect namespaces. Use `keto namespace migrate up` for migrating namespaces.",
+		Args: cobra.NoArgs,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			ctx := cmd.Context()
 

cmd/namespace/migrate_down.go

@@ -15,8 +15,10 @@ import (
 func NewMigrateDownCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "down <namespace-name> <steps>",
-		Short: "Migrate a namespace down.",
-		Args:  cobra.ExactArgs(2),
+		Short: "Migrate a namespace down",
+		Long: "Migrate a namespace down.\n" +
+			"Pass 0 steps to fully migrate down.",
+		Args: cobra.ExactArgs(2),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()
 

cmd/namespace/migrate_up.go

@@ -16,7 +16,8 @@ import (
 func NewMigrateUpCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "up <namespace-name>",
-		Short: "Migrate a namespace up.",
+		Short: "Migrate a namespace up",
+		Long:  "Migrate a namespace up to the most recent migration.",
 		Args:  cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			ctx := cmd.Context()

cmd/namespace/root.go

@@ -10,13 +10,15 @@ import (
 
 func NewNamespaceCmd() *cobra.Command {
 	return &cobra.Command{
-		Use: "namespace",
+		Use:   "namespace",
+		Short: "Read and manipulate namespaces",
 	}
 }
 
 func NewMigrateCmd() *cobra.Command {
 	return &cobra.Command{
-		Use: "migrate",
+		Use:   "migrate",
+		Short: "Migrate a namespace",
 	}
 }
 

cmd/namespace/validate.go

@@ -21,8 +21,8 @@ func NewValidateCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "validate <namespace.yml> [<namespace2.yml> ...]",
 		Args:  cobra.MinimumNArgs(1),
-		Short: "Validate a namespace file.",
-		Long:  "Validate a namespace file and get human readable errors.",
+		Short: "Validate namespace files",
+		Long:  "Validate one or more namespace yaml files and get human readable errors. Useful for debugging.",
 		RunE: func(cmd *cobra.Command, args []string) error {
 			for _, fn := range args {
 				_, err := validateNamespaceFile(cmd, fn)

cmd/relationtuple/create.go

@@ -19,7 +19,11 @@ import (
 
 func newCreateCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:  "create <relation-tuple.json> [<relation-tuple-dir>]",
+		Use:   "create <relation-tuple.json> [<relation-tuple-dir>]",
+		Short: "Create relation tuples from JSON files",
+		Long: "Create relation tuples from JSON files.\n" +
+			"A directory will be traversed and all relation tuples will be created.\n" +
+			"Pass the special filename `-` to read from STD_IN.",
 		Args: cobra.MinimumNArgs(1),
 		RunE: transactRelationTuples(acl.RelationTupleDelta_INSERT),
 	}

cmd/relationtuple/delete.go

@@ -13,7 +13,11 @@ import (
 
 func newDeleteCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:  "delete <relation-tuple.json> [<relation-tuple-dir>]",
+		Use:   "delete <relation-tuple.json> [<relation-tuple-dir>]",
+		Short: "Delete relation tuples defined in JSON files",
+		Long: "Delete relation tuples defined in the given JSON files.\n" +
+			"A directory will be traversed and all relation tuples will be deleted.\n" +
+			"Pass the special filename `-` to read from STD_IN.",
 		Args: cobra.MinimumNArgs(1),
 		RunE: transactRelationTuples(acl.RelationTupleDelta_DELETE),
 	}

cmd/relationtuple/get.go

@@ -63,7 +63,10 @@ func newGetCmd() *cobra.Command {
 	)
 
 	cmd := &cobra.Command{
-		Use:  "get <namespace>",
+		Use:   "get <namespace>",
+		Short: "Get relation tuples",
+		Long: "Get relation tuples matching the given partial tuple.\n" +
+			"Returns paginated results.",
 		Args: cobra.ExactArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			conn, err := client.GetReadConn(cmd)

cmd/relationtuple/parse.go

@@ -15,9 +15,11 @@ import (
 func newParseCmd() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "parse",
-		Short: "Parse human readable relation tuples.",
-		Long:  "Parse human readable relation tuples as used in the documentation. Supports various output formats. Especially useful for piping into other commands by using `--format json`.",
-		Args:  cobra.MinimumNArgs(1),
+		Short: "Parse human readable relation tuples",
+		Long: "Parse human readable relation tuples as used in the documentation.\n" +
+			"Supports various output formats. Especially useful for piping into other commands by using `--format json`.\n" +
+			"Ignores comments (starting with `//`) and blank lines.",
+		Args: cobra.MinimumNArgs(1),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			var rts []*relationtuple.InternalRelationTuple
 			for _, fn := range args {

cmd/relationtuple/root.go

@@ -11,7 +11,8 @@ import (
 
 func newRelationCmd() *cobra.Command {
 	return &cobra.Command{
-		Use: "relation-tuple",
+		Use:   "relation-tuple",
+		Short: "Read and manipulate relation tuples",
 	}
 }
 

cmd/root.go

@@ -44,7 +44,8 @@ import (
 // RootCmd represents the base command when called without any subcommands
 func NewRootCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use: "keto",
+		Use:   "keto",
+		Short: "Global and consistent permission and authorization server",
 	}
 
 	configx.RegisterConfigFlag(cmd.PersistentFlags(), []string{filepath.Join(userHomeDir(), "keto.yml")})

cmd/server/serve.go

@@ -21,22 +21,21 @@ import (
 	"github.com/spf13/cobra"
 
 	"github.com/ory/keto/internal/driver"
-	"github.com/ory/keto/internal/driver/config"
 )
 
 // serveCmd represents the serve command
 func newServe() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "serve",
-		Short: "Starts the server and serves the HTTP REST API",
-		Long: `This command opens a network port and listens to HTTP/2 API requests.
+		Short: "Starts the server and serves the HTTP REST and gRPC APIs",
+		Long: `This command opens the network ports and listens to HTTP and gRPC API requests.
 
 ## Configuration
 
 ORY Keto can be configured using environment variables as well as a configuration file. For more information
 on configuration options, open the configuration documentation:
 
->> https://github.com/ory/keto/blob/` + config.Version + `/docs/config.yaml <<`,
+>> https://www.ory.sh/keto/docs/reference/configuration <<`,
 		RunE: func(cmd *cobra.Command, args []string) error {
 			reg, err := driver.NewDefaultRegistry(cmd.Context(), cmd.Flags())
 			if err != nil {

cmd/status/root.go

@@ -27,7 +27,7 @@ func newStatusCmd() *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "status",
-		Short: "Get the status of the upstream Keto instance.",
+		Short: "Get the status of the upstream Keto instance",
 		Long:  "Get a status report about the upstream Keto instance. Can also block until the service is healthy.",
 		Args:  cobra.ExactArgs(0),
 		RunE: func(cmd *cobra.Command, args []string) error {

docs/docs/cli/keto-check.md

@@ -1,7 +1,7 @@
 ---
 id: keto-check
 title: keto check
-description: keto check
+description: keto check Check whether a subject has a relation on an object
 ---
 
 <!--
@@ -12,6 +12,13 @@ To improve this file please make your change against the appropriate "./cmd/*.go
 
 ## keto check
 
+Check whether a subject has a relation on an object
+
+### Synopsis
+
+Check whether a subject has a relation on an object. This method resolves
+subject sets and subject set rewrites.
+
 ```
 keto check <subject> <relation> <namespace> <object> [flags]
 ```
@@ -34,4 +41,4 @@ keto check <subject> <relation> <namespace> <object> [flags]
 
 ### SEE ALSO
 
-- [keto](keto) -
+- [keto](keto) - Global and consistent permission and authorization server

docs/docs/cli/keto-expand.md

@@ -1,7 +1,7 @@
 ---
 id: keto-expand
 title: keto expand
-description: keto expand
+description: keto expand Expand a subject set
 ---
 
 <!--
@@ -12,6 +12,12 @@ To improve this file please make your change against the appropriate "./cmd/*.go
 
 ## keto expand
 
+Expand a subject set
+
+### Synopsis
+
+Expand a subject set into a tree of subjects.
+
 ```
 keto expand <relation> <namespace> <object> [flags]
 ```
@@ -34,4 +40,4 @@ keto expand <relation> <namespace> <object> [flags]
 
 ### SEE ALSO
 
-- [keto](keto) -
+- [keto](keto) - Global and consistent permission and authorization server

docs/docs/cli/keto-migrate-down.md

@@ -1,7 +1,7 @@
 ---
 id: keto-migrate-down
 title: keto migrate down
-description: keto migrate down
+description: keto migrate down Migrate the database down
 ---
 
 <!--
@@ -12,6 +12,14 @@ To improve this file please make your change against the appropriate "./cmd/*.go
 
 ## keto migrate down
 
+Migrate the database down
+
+### Synopsis
+
+Migrate the database down a specific amount of steps. Pass 0 steps to fully
+migrate down. This does not affect namespaces. Use `keto namespace migrate down`
+for migrating namespaces.
+
 ```
 keto migrate down <steps> [flags]
 ```
@@ -33,4 +41,4 @@ keto migrate down <steps> [flags]
 
 ### SEE ALSO
 
-- [keto migrate](keto-migrate) -
+- [keto migrate](keto-migrate) - Commands to migrate the database

docs/docs/cli/keto-migrate-status.md

@@ -1,7 +1,7 @@
 ---
 id: keto-migrate-status
 title: keto migrate status
-description: keto migrate status
+description: keto migrate status Get the current migration status
 ---
 
 <!--
@@ -12,6 +12,13 @@ To improve this file please make your change against the appropriate "./cmd/*.go
 
 ## keto migrate status
 
+Get the current migration status
+
+### Synopsis
+
+Get the current migration status. This does not affect namespaces. Use
+`keto namespace migrate status` for migrating namespaces.
+
 ```
 keto migrate status [flags]
 ```
@@ -32,4 +39,4 @@ keto migrate status [flags]
 
 ### SEE ALSO
 
-- [keto migrate](keto-migrate) -
+- [keto migrate](keto-migrate) - Commands to migrate the database

docs/docs/cli/keto-migrate-up.md

@@ -1,7 +1,7 @@
 ---
 id: keto-migrate-up
 title: keto migrate up
-description: keto migrate up
+description: keto migrate up Migrate the database up
 ---
 
 <!--
@@ -12,6 +12,13 @@ To improve this file please make your change against the appropriate "./cmd/*.go
 
 ## keto migrate up
 
+Migrate the database up
+
+### Synopsis
+
+Migrate the database up. This does not affect namespaces. Use
+`keto namespace migrate up` for migrating namespaces.
+
 ```
 keto migrate up [flags]
 ```
@@ -34,4 +41,4 @@ keto migrate up [flags]
 
 ### SEE ALSO
 
-- [keto migrate](keto-migrate) -
+- [keto migrate](keto-migrate) - Commands to migrate the database