docs: add examples to some commands (#572)

Author: miparnisari

docs/zed.md

@@ -40,16 +40,16 @@ func registerContextCmd(rootCmd *cobra.Command) {
 	}
 
 	contextRemoveCmd := &cobra.Command{
-		Use:               "remove <system>",
-		Short:             "Removes a context",
+		Use:               "remove <name>",
+		Short:             "Removes a context by name",
 		Aliases:           []string{"rm"},
 		Args:              commands.ValidationWrapper(cobra.ExactArgs(1)),
 		ValidArgsFunction: ContextGet,
 		RunE:              contextRemoveCmdFunc,
 	}
 
 	contextUseCmd := &cobra.Command{
-		Use:               "use <system>",
+		Use:               "use <name>",
 		Short:             "Sets a context as the current context",
 		Args:              commands.ValidationWrapper(cobra.MaximumNArgs(1)),
 		ValidArgsFunction: ContextGet,

internal/cmd/context.go

@@ -77,14 +77,14 @@ func RegisterPermissionCmd(rootCmd *cobra.Command) *cobra.Command {
 
 	checkBulkCmd := &cobra.Command{
 		Use:   "bulk <resource:id#permission@subject:id> <resource:id#permission@subject:id> ...",
-		Short: "Check permissions in bulk exist for resource-subject pairs",
+		Short: "Check permissions in bulk exist for resource-permission-subject triplets",
 		Args:  ValidationWrapper(cobra.MinimumNArgs(1)),
 		RunE:  checkBulkCmdFunc,
 	}
 
 	checkCmd := &cobra.Command{
 		Use:               "check <resource:id> <permission> <subject:id>",
-		Short:             "Check that a permission exists for a subject",
+		Short:             "Check if a subject has permission on a resource",
 		Args:              ValidationWrapper(cobra.ExactArgs(3)),
 		ValidArgsFunction: GetArgs(ResourceID, Permission, SubjectID),
 		RunE:              checkCmdFunc,
@@ -100,15 +100,15 @@ func RegisterPermissionCmd(rootCmd *cobra.Command) *cobra.Command {
 
 	lookupResourcesCmd := &cobra.Command{
 		Use:               "lookup-resources <type> <permission> <subject:id>",
-		Short:             "Enumerates the resources of a given type for which the subject has permission",
+		Short:             "Enumerates the resources of a given type for which a subject has permission",
 		Args:              ValidationWrapper(cobra.ExactArgs(3)),
 		ValidArgsFunction: GetArgs(ResourceType, Permission, SubjectID),
 		RunE:              lookupResourcesCmdFunc,
 	}
 
 	lookupCmd := &cobra.Command{
 		Use:               "lookup <type> <permission> <subject:id>",
-		Short:             "Enumerates the resources of a given type for which the subject has permission",
+		Short:             "Enumerates the resources of a given type for which a subject has permission",
 		Args:              ValidationWrapper(cobra.ExactArgs(3)),
 		ValidArgsFunction: GetArgs(ResourceType, Permission, SubjectID),
 		RunE:              lookupResourcesCmdFunc,

internal/commands/permission.go

@@ -26,13 +26,6 @@ import (
 	"github.com/authzed/zed/internal/console"
 )
 
-const readCmdHelpLong = `Enumerates relationships matching the provided pattern.
-
-To filter returned relationships using a resource ID prefix, append a '%' to the resource ID:
-
-zed relationship read some-type:some-prefix-%
-`
-
 func RegisterRelationshipCmd(rootCmd *cobra.Command) *cobra.Command {
 	relationshipCmd := &cobra.Command{
 		Use:   "relationship <subcommand>",
@@ -45,6 +38,10 @@ func RegisterRelationshipCmd(rootCmd *cobra.Command) *cobra.Command {
 		Args:              ValidationWrapper(StdinOrExactArgs(3)),
 		ValidArgsFunction: GetArgs(ResourceID, Permission, SubjectTypeWithOptionalRelation),
 		RunE:              writeRelationshipCmdFunc(v1.RelationshipUpdate_OPERATION_CREATE, os.Stdin),
+		Example: `
+  zed relationship create document:budget view user:anne --expiration-time "2025-12-31T23:59:59Z"
+  zed relationship create document:budget view user:anne --caveat ip_address:'{"ip": "192.168.0.1"}
+`,
 	}
 
 	touchCmd := &cobra.Command{
@@ -53,6 +50,10 @@ func RegisterRelationshipCmd(rootCmd *cobra.Command) *cobra.Command {
 		Args:              ValidationWrapper(StdinOrExactArgs(3)),
 		ValidArgsFunction: GetArgs(ResourceID, Permission, SubjectTypeWithOptionalRelation),
 		RunE:              writeRelationshipCmdFunc(v1.RelationshipUpdate_OPERATION_TOUCH, os.Stdin),
+		Example: `
+  zed relationship touch document:budget view user:anne --expiration-time "2025-12-31T23:59:59Z"
+  zed relationship touch document:budget view user:anne --caveat ip_address:'{"ip": "192.168.0.1"}
+`,
 	}
 
 	deleteCmd := &cobra.Command{
@@ -66,10 +67,13 @@ func RegisterRelationshipCmd(rootCmd *cobra.Command) *cobra.Command {
 	readCmd := &cobra.Command{
 		Use:               "read <resource_type:optional_resource_id> <optional_relation> <optional_subject_type:optional_subject_id#optional_subject_relation>",
 		Short:             "Enumerates relationships matching the provided pattern",
-		Long:              readCmdHelpLong,
 		Args:              ValidationWrapper(cobra.RangeArgs(1, 3)),
 		ValidArgsFunction: GetArgs(ResourceID, Permission, SubjectTypeWithOptionalRelation),
 		RunE:              readRelationships,
+		Example: `
+  # To filter returned relationships using a resource ID prefix, append a '%' to the resource ID.
+  zed relationship read document:finance-%
+`,
 	}
 
 	bulkDeleteCmd := &cobra.Command{

internal/commands/relationship.go

@@ -1,5 +1,4 @@
 //go:build !wasm
-// +build !wasm
 
 package commands