Merge pull request #4027 from hashicorp/f-common

New Command Line Groupings

api/nodes_test.go

@@ -270,6 +270,9 @@ func TestNodes_ToggleEligibility(t *testing.T) {
 	if out.SchedulingEligibility != structs.NodeSchedulingEligible {
 		t.Fatalf("bad eligibility: %v vs %v", out.SchedulingEligibility, structs.NodeSchedulingEligible)
 	}
+	if out.DrainStrategy != nil {
+		t.Fatalf("drain strategy should be unset")
+	}
 }
 
 func TestNodes_Allocations(t *testing.T) {

command/acl.go

@@ -12,11 +12,17 @@ type ACLCommand struct {
 
 func (f *ACLCommand) Help() string {
 	helpText := `
-Usage: nomad acl <subcommand> [options]
+Usage: nomad acl <subcommand> [options] [args]
 
-  Interact with ACL policies and tokens.
+  This command groups subcommands for interacting with ACL policies and tokens.
+  Users can bootstrap Nomad's ACL system, create policies that restrict access,
+  and generate tokens from those policies.
 
-  Run nomad acl <subcommand> with no arguments for help on that subcommand.
+  Bootstrap ACLs:
+
+      $ nomad acl bootstrap
+
+  Please see the individual subcommand help for detailed usage information.
 `
 	return strings.TrimSpace(helpText)
 }

command/acl_policy.go

@@ -1,13 +1,39 @@
 package command
 
-import "github.com/mitchellh/cli"
+import (
+	"strings"
+
+	"github.com/mitchellh/cli"
+)
 
 type ACLPolicyCommand struct {
 	Meta
 }
 
 func (f *ACLPolicyCommand) Help() string {
-	return "This command is accessed by using one of the subcommands below."
+	helpText := `
+Usage: nomad acl policy <subcommand> [options] [args]
+
+  This command groups subcommands for interacting with ACL policies. Nomad's ACL
+  system can be used to control access to data and APIs. ACL policies allow a
+  set of capabilities or actions to be granted or whitelisted. For a full guide
+  see: https://www.nomadproject.io/guides/acl.html
+
+  Create an ACL policy:
+
+      $ nomad acl policy apply <name> <policy-file>
+
+  List ACL policies:
+
+      $ nomad acl policy list
+
+  Inspect an ACL policy:
+
+      $ nomad acl policy info <policy>
+
+  Please see the individual subcommand help for detailed usage information.
+`
+	return strings.TrimSpace(helpText)
 }
 
 func (f *ACLPolicyCommand) Synopsis() string {

command/acl_token.go

@@ -1,13 +1,39 @@
 package command
 
-import "github.com/mitchellh/cli"
+import (
+	"strings"
+
+	"github.com/mitchellh/cli"
+)
 
 type ACLTokenCommand struct {
 	Meta
 }
 
 func (f *ACLTokenCommand) Help() string {
-	return "This command is accessed by using one of the subcommands below."
+	helpText := `
+Usage: nomad acl token <subcommand> [options] [args]
+
+  This command groups subcommands for interacting with ACL tokens. Nomad's ACL
+  system can be used to control access to data and APIs. ACL tokens are
+  associated with one or more ACL policies which grant specific capabilities.
+  For a full guide see: https://www.nomadproject.io/guides/acl.html
+
+  Create an ACL token:
+
+      $ nomad acl token create -name "my-token" -policy foo -policy bar
+
+  Lookup a token and display its associated policies:
+
+      $ nomad acl policy info <token_accessor_id>
+
+  Revoke an ACL token:
+
+      $ nomad acl policy delete <token_accessor_id>
+
+  Please see the individual subcommand help for detailed usage information.
+`
+	return strings.TrimSpace(helpText)
 }
 
 func (f *ACLTokenCommand) Synopsis() string {

command/alloc.go

@@ -0,0 +1,40 @@
+package command
+
+import (
+	"strings"
+
+	"github.com/mitchellh/cli"
+)
+
+type AllocCommand struct {
+	Meta
+}
+
+func (f *AllocCommand) Help() string {
+	helpText := `
+Usage: nomad alloc <subcommand> [options] [args]
+
+  This command groups subcommands for interacting with allocations. Users can
+  inspect the status, examine the filesystem or logs of an allocation.
+
+  Examine an allocations status:
+
+      $ nomad alloc status <alloc-id>
+
+  Stream a task's logs:
+
+      $ nomad alloc logs -f <alloc-id> <task>
+
+  Please see the individual subcommand help for detailed usage information.
+`
+
+	return strings.TrimSpace(helpText)
+}
+
+func (f *AllocCommand) Synopsis() string {
+	return "Interact with allocations"
+}
+
+func (f *AllocCommand) Run(args []string) int {
+	return cli.RunResultHelp
+}

command/fs.go → command/alloc_fs.go

@@ -27,13 +27,14 @@ const (
 	defaultTailLines int64 = 10
 )
 
-type FSCommand struct {
+type AllocFSCommand struct {
 	Meta
 }
 
-func (f *FSCommand) Help() string {
+func (f *AllocFSCommand) Help() string {
 	helpText := `
-Usage: nomad fs [options] <allocation> <path>
+Usage: nomad alloc fs [options] <allocation> <path>
+Alias: nomad fs
 
   fs displays either the contents of an allocation directory for the passed allocation,
   or displays the file at the given path. The path is relative to the root of the alloc
@@ -75,11 +76,11 @@ FS Specific Options:
 	return strings.TrimSpace(helpText)
 }
 
-func (f *FSCommand) Synopsis() string {
+func (f *AllocFSCommand) Synopsis() string {
 	return "Inspect the contents of an allocation directory"
 }
 
-func (c *FSCommand) AutocompleteFlags() complete.Flags {
+func (c *AllocFSCommand) AutocompleteFlags() complete.Flags {
 	return mergeAutocompleteFlags(c.Meta.AutocompleteFlags(FlagSetClient),
 		complete.Flags{
 			"-H":       complete.PredictNothing,
@@ -93,7 +94,7 @@ func (c *FSCommand) AutocompleteFlags() complete.Flags {
 		})
 }
 
-func (f *FSCommand) AutocompleteArgs() complete.Predictor {
+func (f *AllocFSCommand) AutocompleteArgs() complete.Predictor {
 	return complete.PredictFunc(func(a complete.Args) []string {
 		client, err := f.Meta.Client()
 		if err != nil {
@@ -108,11 +109,11 @@ func (f *FSCommand) AutocompleteArgs() complete.Predictor {
 	})
 }
 
-func (f *FSCommand) Run(args []string) int {
+func (f *AllocFSCommand) Run(args []string) int {
 	var verbose, machine, job, stat, tail, follow bool
 	var numLines, numBytes int64
 
-	flags := f.Meta.FlagSet("fs", FlagSetClient)
+	flags := f.Meta.FlagSet("alloc fs", FlagSetClient)
 	flags.Usage = func() { f.Ui.Output(f.Help()) }
 	flags.BoolVar(&verbose, "verbose", false, "")
 	flags.BoolVar(&machine, "H", false, "")
@@ -333,7 +334,7 @@ func (f *FSCommand) Run(args []string) int {
 
 // followFile outputs the contents of the file to stdout relative to the end of
 // the file. If numLines does not equal -1, then tail -n behavior is used.
-func (f *FSCommand) followFile(client *api.Client, alloc *api.Allocation,
+func (f *AllocFSCommand) followFile(client *api.Client, alloc *api.Allocation,
 	path, origin string, offset, numLines int64) (io.ReadCloser, error) {
 
 	cancel := make(chan struct{})

command/fs_test.go → command/alloc_fs_test.go

@@ -13,7 +13,7 @@ import (
 
 func TestFSCommand_Implements(t *testing.T) {
 	t.Parallel()
-	var _ cli.Command = &FSCommand{}
+	var _ cli.Command = &AllocFSCommand{}
 }
 
 func TestFSCommand_Fails(t *testing.T) {
@@ -22,7 +22,7 @@ func TestFSCommand_Fails(t *testing.T) {
 	defer srv.Shutdown()
 
 	ui := new(cli.MockUi)
-	cmd := &FSCommand{Meta: Meta{Ui: ui}}
+	cmd := &AllocFSCommand{Meta: Meta{Ui: ui}}
 
 	// Fails on lack of job ID
 	if code := cmd.Run([]string{"-job"}); code != 1 {
@@ -95,7 +95,7 @@ func TestFSCommand_AutocompleteArgs(t *testing.T) {
 	defer srv.Shutdown()
 
 	ui := new(cli.MockUi)
-	cmd := &FSCommand{Meta: Meta{Ui: ui, flagAddress: url}}
+	cmd := &AllocFSCommand{Meta: Meta{Ui: ui, flagAddress: url}}
 
 	// Create a fake alloc
 	state := srv.Agent.Server().State()

command/logs.go → command/alloc_logs.go

@@ -14,13 +14,14 @@ import (
 	"github.com/posener/complete"
 )
 
-type LogsCommand struct {
+type AllocLogsCommand struct {
 	Meta
 }
 
-func (l *LogsCommand) Help() string {
+func (l *AllocLogsCommand) Help() string {
 	helpText := `
-Usage: nomad logs [options] <allocation> <task>
+Usage: nomad alloc logs [options] <allocation> <task>
+Alias: nomad logs
 
   Streams the stdout/stderr of the given allocation and task.
 
@@ -57,11 +58,11 @@ Logs Specific Options:
 	return strings.TrimSpace(helpText)
 }
 
-func (l *LogsCommand) Synopsis() string {
+func (l *AllocLogsCommand) Synopsis() string {
 	return "Streams the logs of a task."
 }
 
-func (c *LogsCommand) AutocompleteFlags() complete.Flags {
+func (c *AllocLogsCommand) AutocompleteFlags() complete.Flags {
 	return mergeAutocompleteFlags(c.Meta.AutocompleteFlags(FlagSetClient),
 		complete.Flags{
 			"-stderr":  complete.PredictNothing,
@@ -74,7 +75,7 @@ func (c *LogsCommand) AutocompleteFlags() complete.Flags {
 		})
 }
 
-func (l *LogsCommand) AutocompleteArgs() complete.Predictor {
+func (l *AllocLogsCommand) AutocompleteArgs() complete.Predictor {
 	return complete.PredictFunc(func(a complete.Args) []string {
 		client, err := l.Meta.Client()
 		if err != nil {
@@ -89,11 +90,11 @@ func (l *LogsCommand) AutocompleteArgs() complete.Predictor {
 	})
 }
 
-func (l *LogsCommand) Run(args []string) int {
+func (l *AllocLogsCommand) Run(args []string) int {
 	var verbose, job, tail, stderr, follow bool
 	var numLines, numBytes int64
 
-	flags := l.Meta.FlagSet("logs", FlagSetClient)
+	flags := l.Meta.FlagSet("alloc logs", FlagSetClient)
 	flags.Usage = func() { l.Ui.Output(l.Help()) }
 	flags.BoolVar(&verbose, "verbose", false, "")
 	flags.BoolVar(&job, "job", false, "")
@@ -262,7 +263,7 @@ func (l *LogsCommand) Run(args []string) int {
 
 // followFile outputs the contents of the file to stdout relative to the end of
 // the file.
-func (l *LogsCommand) followFile(client *api.Client, alloc *api.Allocation,
+func (l *AllocLogsCommand) followFile(client *api.Client, alloc *api.Allocation,
 	follow bool, task, logType, origin string, offset int64) (io.ReadCloser, error) {
 
 	cancel := make(chan struct{})

command/logs_test.go → command/alloc_logs_test.go

@@ -13,7 +13,7 @@ import (
 
 func TestLogsCommand_Implements(t *testing.T) {
 	t.Parallel()
-	var _ cli.Command = &LogsCommand{}
+	var _ cli.Command = &AllocLogsCommand{}
 }
 
 func TestLogsCommand_Fails(t *testing.T) {
@@ -22,7 +22,7 @@ func TestLogsCommand_Fails(t *testing.T) {
 	defer srv.Shutdown()
 
 	ui := new(cli.MockUi)
-	cmd := &LogsCommand{Meta: Meta{Ui: ui}}
+	cmd := &AllocLogsCommand{Meta: Meta{Ui: ui}}
 
 	// Fails on misuse
 	if code := cmd.Run([]string{"some", "bad", "args"}); code != 1 {
@@ -77,7 +77,7 @@ func TestLogsCommand_AutocompleteArgs(t *testing.T) {
 	defer srv.Shutdown()
 
 	ui := new(cli.MockUi)
-	cmd := &LogsCommand{Meta: Meta{Ui: ui, flagAddress: url}}
+	cmd := &AllocLogsCommand{Meta: Meta{Ui: ui, flagAddress: url}}
 
 	// Create a fake alloc
 	state := srv.Agent.Server().State()

command/alloc_status.go

@@ -22,7 +22,7 @@ type AllocStatusCommand struct {
 
 func (c *AllocStatusCommand) Help() string {
 	helpText := `
-Usage: nomad alloc-status [options] <allocation>
+Usage: nomad alloc status [options] <allocation>
 
   Display information about existing allocations and its tasks. This command can
   be used to inspect the current status of an allocation, including its running
@@ -87,7 +87,7 @@ func (c *AllocStatusCommand) Run(args []string) int {
 	var short, displayStats, verbose, json bool
 	var tmpl string
 
-	flags := c.Meta.FlagSet("alloc-status", FlagSetClient)
+	flags := c.Meta.FlagSet("alloc status", FlagSetClient)
 	flags.Usage = func() { c.Ui.Output(c.Help()) }
 	flags.BoolVar(&short, "short", false, "")
 	flags.BoolVar(&verbose, "verbose", false, "")