docs: improve long messages and render cli documentation

cmd/clidoc/main.go

@@ -0,0 +1,26 @@
+package main
+
+import (
+	"fmt"
+	"github.com/ory/kratos/cmd/remote"
+	"github.com/spf13/cobra"
+	"os"
+
+	"github.com/ory/x/clidoc"
+
+	"github.com/ory/kratos/cmd/identities"
+	"github.com/ory/kratos/cmd/jsonnet"
+)
+
+func main() {
+	rootCmd := &cobra.Command{ Use: "kratos" }
+	identities.RegisterCommandRecursive(rootCmd)
+	jsonnet.RegisterCommandRecursive(rootCmd)
+	remote.RegisterCommandRecursive(rootCmd)
+
+	if err := clidoc.Generate(rootCmd, os.Args[1:]); err != nil {
+		_, _ = fmt.Fprintf(os.Stderr, "%+v", err)
+		os.Exit(1)
+	}
+	fmt.Println("All files have been generated and updated.")
+}

cmd/identities/definitions.go

@@ -89,3 +89,7 @@ func (c *outputIdentityCollection) Table() [][]string {
 func (c *outputIdentityCollection) Interface() interface{} {
 	return c.identities
 }
+
+func (c *outputIdentityCollection) Len() int {
+	return len(c.identities)
+}

cmd/identities/delete.go

@@ -5,15 +5,24 @@ import (
 	"fmt"
 	"os"
 
+	"github.com/ory/kratos/internal/clihelpers"
+
 	"github.com/spf13/cobra"
 
 	"github.com/ory/kratos/cmd/cliclient"
 	"github.com/ory/kratos/internal/httpclient/client/admin"
 )
 
 var deleteCmd = &cobra.Command{
-	Use:  "delete",
+	Use:   "delete <id-0 [id-1 ...]>",
 	Short: "Delete identities by ID",
+	Long: fmt.Sprintf(`This command deletes one or more identities by ID. To delete an identity by some selector, e.g. the recovery email address, use the list command in combination with jq.
+Example: delete the identity with the recovery email address "foo@bar.com":
+
+kratos identities delete $(kratos identities list --format json | jq -r 'map(select(.recovery_addresses[].value == "foo@bar.com")) | .[].id')
+
+%s
+`, clihelpers.WarningJQIsComplicated),
 	Args: cobra.MinimumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		c := cliclient.NewClient(cmd)

cmd/identities/get.go

@@ -1,29 +1,45 @@
 package identities
 
 import (
-	"context"
+	"fmt"
+	"time"
+
+	"github.com/ory/kratos/internal/clihelpers"
+	"github.com/ory/kratos/internal/httpclient/models"
 
 	"github.com/spf13/cobra"
 
 	"github.com/ory/kratos/cmd/cliclient"
-	"github.com/ory/kratos/internal/clihelpers"
 	"github.com/ory/kratos/internal/httpclient/client/admin"
 	"github.com/ory/x/cmdx"
 )
 
 var getCmd = &cobra.Command{
-	Use:  "get <id>",
-	Short: "Get an identity by ID",
-	Args: cobra.ExactArgs(1),
+	Use:   "get <id-0 [id-1 ...]>",
+	Short: "Get one or more identities by ID",
+	Long: fmt.Sprintf(`This command gets all the details about an identity. To get an identity by some selector, e.g. the recovery email address, use the list command in combination with jq.
+Example: get the identities with the recovery email address at the domain "ory.sh":
+
+kratos identities get $(kratos identities list --format json | jq -r 'map(select(.recovery_addresses[].value | endswith("@ory.sh"))) | .[].id')
+
+%s
+`, clihelpers.WarningJQIsComplicated),
+	Args: cobra.MinimumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		c := cliclient.NewClient(cmd)
 
-		resp, err := c.Admin.GetIdentity(&admin.GetIdentityParams{
-			ID:      args[0],
-			Context: context.Background(),
-		})
-		cmdx.Must(err, "Could not get identity \"%s\": %s", args[0], err)
+		identities := make([]*models.Identity, 0, len(args))
+		for _, id := range args {
+			resp, err := c.Admin.GetIdentity(admin.NewGetIdentityParamsWithTimeout(time.Second).WithID(id))
+			cmdx.Must(err, "Could not get identity \"%s\": %s", args[0], err)
+
+			identities = append(identities, resp.Payload)
+		}
 
-		clihelpers.PrintRow(cmd, (*outputIdentity)(resp.Payload))
+		if len(identities) == 1 {
+			clihelpers.PrintRow(cmd, (*outputIdentity)(identities[0]))
+			return
+		}
+		clihelpers.PrintCollection(cmd, &outputIdentityCollection{identities})
 	},
 }

cmd/identities/import.go

@@ -19,10 +19,10 @@ import (
 
 // putCmd represents the import command
 var putCmd = &cobra.Command{
-	Use: "import <file.json [file-2.json [file-3.json] ...]>",
+	Use:   "import <file.json [file-2.json [file-3.json] ...]>",
 	Short: "Import identities from files or STD_IN",
-	Long: "Import identities from files or STD_IN. Files are expected to each contain a single identity. The validity of files can be tested beforehand using the `validate` command.",
-	Run: importIdentities,
+	Long:  "Import identities from files or STD_IN. Files are expected to each contain a single identity. The validity of files can be tested beforehand using `... identities validate`.",
+	Run:   importIdentities,
 }
 
 func importIdentities(cmd *cobra.Command, args []string) {

cmd/identities/list.go

@@ -15,9 +15,9 @@ import (
 )
 
 var listCmd = &cobra.Command{
-	Use: "list [<page> <per-page>]",
+	Use:   "list [<page> <per-page>]",
 	Short: "List identities",
-	Long: "List identities (paginated)",
+	Long:  "List identities (paginated)",
 	Args: func(cmd *cobra.Command, args []string) error {
 		// zero or exactly two args
 		if len(args) != 0 && len(args) != 2 {

cmd/identities/patch.go

@@ -7,9 +7,9 @@ import (
 )
 
 var patchCmd = &cobra.Command{
-	Use:  "patch <file.json [file-2.json [file-3.json] ...]>",
+	Use:   "patch <file.json [file-2.json [file-3.json] ...]>",
 	Short: "Patch identities by ID (not yet implemented)",
-	Args: cobra.MinimumNArgs(1),
+	Args:  cobra.MinimumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		// TODO
 		fmt.Println("not yet implemented")

cmd/identities/root.go

@@ -10,7 +10,7 @@ import (
 
 // identitiesCmd represents the identity command
 var identitiesCmd = &cobra.Command{
-	Use: "identities",
+	Use:   "identities",
 	Short: "Tools to interact with remote identities",
 }
 

cmd/identities/validate.go

@@ -21,9 +21,9 @@ import (
 )
 
 var validateCmd = &cobra.Command{
-	Use:  "validate  <file.json [file-2.json [file-3.json] ...]>",
+	Use:   "validate  <file.json [file-2.json [file-3.json] ...]>",
 	Short: "Validate local identity files",
-	Args: cobra.MinimumNArgs(1),
+	Args:  cobra.MinimumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {
 		c := cliclient.NewClient(cmd)
 
@@ -59,7 +59,7 @@ func validateIdentity(src string, fc []byte, c *client.OryKratos) {
 
 	cmdx.Must(err, "%s: Could not open the identity schema: %s", src, err)
 
-	s, err := schemaCompiler.Compile("api.swagger.json#/definitions/CreateIdentityRequestPayload")
+	s, err := schemaCompiler.Compile("api.swagger.json#/definitions/CreateIdentity")
 	cmdx.Must(err, "%s: Could not compile the identity schema: %s", src, err)
 	// force additional properties to false because swagger does not render this key
 	s.AdditionalProperties = false

docs/docs/cli/kratos-identities-delete.md

@@ -0,0 +1,47 @@
+---
+id: kratos-identities-delete
+title: kratos identities delete
+description: kratos identities delete Delete identities by ID
+---
+
+<!--
+This file is auto-generated.
+
+To improve this file please make your change against the appropriate "./cmd/*.go" file.
+-->
+## kratos identities delete
+
+Delete identities by ID
+
+### Synopsis
+
+This command deletes one or more identities by ID. To delete an identity by some selector, e.g. the recovery email address, use the list command in combination with jq.
+Example: delete the identity with the recovery email address "foo@bar.com":
+
+kratos identities delete $(kratos identities list --format json | jq -r 'map(select(.recovery_addresses[].value == "foo@bar.com")) | .[].id')
+
+I have to admit, this is not easy if you don't speak jq fluently. What about opening an issue and telling us what predefined selectors you want to have? https://github.com/ory/kratos/issues/new/choose
+
+
+```
+kratos identities delete <id-0 [id-1 ...]> [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for delete
+```
+
+### Options inherited from parent commands
+
+```
+  -e, --endpoint string   The upstream admin endpoint URL. Alternatively set using the KRATOS_ADMIN_ENDPOINT environmental variable.
+  -f, --format string     Set the output format. One of table, json, and json-pretty.
+  -q, --quiet             Prints only IDs, one per line. Takes precedence over --format.
+```
+
+### SEE ALSO
+
+* [kratos identities](kratos-identities)	 - Tools to interact with remote identities
+

docs/docs/cli/kratos-identities-get.md

@@ -0,0 +1,47 @@
+---
+id: kratos-identities-get
+title: kratos identities get
+description: kratos identities get Get one or more identities by ID
+---
+
+<!--
+This file is auto-generated.
+
+To improve this file please make your change against the appropriate "./cmd/*.go" file.
+-->
+## kratos identities get
+
+Get one or more identities by ID
+
+### Synopsis
+
+This command gets all the details about an identity. To get an identity by some selector, e.g. the recovery email address, use the list command in combination with jq.
+Example: get the identities with the recovery email address at the domain "ory.sh":
+
+kratos identities get $(kratos identities list --format json | jq -r 'map(select(.recovery_addresses[].value | endswith("@ory.sh"))) | .[].id')
+
+I have to admit, this is not easy if you don't speak jq fluently. What about opening an issue and telling us what predefined selectors you want to have? https://github.com/ory/kratos/issues/new/choose
+
+
+```
+kratos identities get <id-0 [id-1 ...]> [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for get
+```
+
+### Options inherited from parent commands
+
+```
+  -e, --endpoint string   The upstream admin endpoint URL. Alternatively set using the KRATOS_ADMIN_ENDPOINT environmental variable.
+  -f, --format string     Set the output format. One of table, json, and json-pretty.
+  -q, --quiet             Prints only IDs, one per line. Takes precedence over --format.
+```
+
+### SEE ALSO
+
+* [kratos identities](kratos-identities)	 - Tools to interact with remote identities
+

docs/docs/cli/kratos-identities-import.md

@@ -0,0 +1,41 @@
+---
+id: kratos-identities-import
+title: kratos identities import
+description: kratos identities import Import identities from files or STD_IN
+---
+
+<!--
+This file is auto-generated.
+
+To improve this file please make your change against the appropriate "./cmd/*.go" file.
+-->
+## kratos identities import
+
+Import identities from files or STD_IN
+
+### Synopsis
+
+Import identities from files or STD_IN. Files are expected to each contain a single identity. The validity of files can be tested beforehand using `... identities validate`.
+
+```
+kratos identities import <file.json [file-2.json [file-3.json] ...]> [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for import
+```
+
+### Options inherited from parent commands
+
+```
+  -e, --endpoint string   The upstream admin endpoint URL. Alternatively set using the KRATOS_ADMIN_ENDPOINT environmental variable.
+  -f, --format string     Set the output format. One of table, json, and json-pretty.
+  -q, --quiet             Prints only IDs, one per line. Takes precedence over --format.
+```
+
+### SEE ALSO
+
+* [kratos identities](kratos-identities)	 - Tools to interact with remote identities
+

docs/docs/cli/kratos-identities-list.md

@@ -0,0 +1,41 @@
+---
+id: kratos-identities-list
+title: kratos identities list
+description: kratos identities list List identities
+---
+
+<!--
+This file is auto-generated.
+
+To improve this file please make your change against the appropriate "./cmd/*.go" file.
+-->
+## kratos identities list
+
+List identities
+
+### Synopsis
+
+List identities (paginated)
+
+```
+kratos identities list [<page> <per-page>] [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for list
+```
+
+### Options inherited from parent commands
+
+```
+  -e, --endpoint string   The upstream admin endpoint URL. Alternatively set using the KRATOS_ADMIN_ENDPOINT environmental variable.
+  -f, --format string     Set the output format. One of table, json, and json-pretty.
+  -q, --quiet             Prints only IDs, one per line. Takes precedence over --format.
+```
+
+### SEE ALSO
+
+* [kratos identities](kratos-identities)	 - Tools to interact with remote identities
+