veyron/lib/cmdline: Avoid repeatedly printing default help.
The previous behavior of "help ..." would repeatedly list and
print the default help for each command and subcommand. This
leads to cluttered output, especially when using -style=godoc to
generate package doc for each tool. The new behavior fixes this.
Also added package doc for every binary using the cmdline
package, and fixed some minor typos. Note that the "long"
description of each root command should be of the form "The foo
tool ..." so that the generated godoc is idiomatic.
Change-Id: Ided6ed61f569a6902a780bc552691885574b72a8
diff --git a/lib/cmdline/cmdline.go b/lib/cmdline/cmdline.go
index dcc5aee..afaf485 100644
--- a/lib/cmdline/cmdline.go
+++ b/lib/cmdline/cmdline.go
@@ -68,6 +68,9 @@
// specified in both sets, the command's own flag wins.
parseFlags *flag.FlagSet
+ // Is this the default help command provided by the framework?
+ isDefaultHelp bool
+
// TODO(toddw): If necessary we can add alias support, e.g. for abbreviations.
// Alias map[string]string
}
@@ -171,6 +174,9 @@
if len(cmd.Children) > 0 {
fmt.Fprintf(w, "\nThe %s commands are:\n", cmd.Name)
for _, child := range cmd.Children {
+ if !firstCall && child.isDefaultHelp {
+ continue // don't repeatedly list default help command
+ }
fmt.Fprintf(w, " %-11s %s\n", child.Name, child.Short)
}
}
@@ -211,16 +217,16 @@
Help displays usage descriptions for this command, or usage descriptions for
sub-commands.
`,
- ArgsName: "<command>",
+ ArgsName: "[command ...]",
ArgsLong: `
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
`,
Run: func(cmd *Command, args []string) error {
// Help applies to its parent - e.g. "foo help" applies to the foo command.
return runHelp(cmd.parent, args, helpStyle)
},
+ isDefaultHelp: true,
}
help.Flags.Var(&helpStyle, "style", `The formatting style for help output, either "text" or "godoc".`)
return help
@@ -259,6 +265,9 @@
fmt.Fprintln(cmd.stdout)
}
for _, child := range cmd.Children {
+ if !firstCall && child.isDefaultHelp {
+ continue // don't repeatedly print default help command
+ }
recursiveHelp(child, style, false)
}
}
diff --git a/lib/cmdline/cmdline_test.go b/lib/cmdline/cmdline_test.go
index e9c471b..f4a424c 100644
--- a/lib/cmdline/cmdline_test.go
+++ b/lib/cmdline/cmdline_test.go
@@ -239,11 +239,10 @@
sub-commands.
Usage:
- onecmd help [flags] <command>
+ onecmd help [flags] [command ...]
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
The help flags are:
-style=text: The formatting style for help output, either "text" or "godoc".
@@ -279,11 +278,10 @@
sub-commands.
Usage:
- onecmd help [flags] <command>
+ onecmd help [flags] [command ...]
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
The help flags are:
-style=text: The formatting style for help output, either "text" or "godoc".
@@ -455,11 +453,10 @@
sub-commands.
Usage:
- multi help [flags] <command>
+ multi help [flags] [command ...]
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
The help flags are:
-style=text: The formatting style for help output, either "text" or "godoc".
@@ -730,7 +727,6 @@
The echoprog commands are:
echo Print strings on stdout
echoopt Print strings on stdout, with opts
- help Display help for commands
The echoprog flags are:
-extra=false: Print an extra arg
@@ -752,19 +748,6 @@
The echoopt flags are:
-n=false: Do not output trailing newline
================================================================================
-Help displays usage descriptions for this command, or usage descriptions for
-sub-commands.
-
-Usage:
- toplevelprog echoprog help [flags] <command>
-
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
-
-The help flags are:
- -style=text: The formatting style for help output, either "text" or "godoc".
-================================================================================
Hello prints any strings passed in to stdout preceded by "Hello".
Usage:
@@ -776,11 +759,10 @@
sub-commands.
Usage:
- toplevelprog help [flags] <command>
+ toplevelprog help [flags] [command ...]
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
The help flags are:
-style=text: The formatting style for help output, either "text" or "godoc".
@@ -847,11 +829,10 @@
sub-commands.
Usage:
- toplevelprog echoprog help [flags] <command>
+ toplevelprog echoprog help [flags] [command ...]
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
The help flags are:
-style=text: The formatting style for help output, either "text" or "godoc".
@@ -1158,7 +1139,6 @@
hello21 Print strings on stdout preceded by "Hello"
prog3 Set of hello commands
hello22 Print strings on stdout preceded by "Hello"
- help Display help for commands
================================================================================
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1175,7 +1155,6 @@
The prog3 commands are:
hello31 Print strings on stdout preceded by "Hello"
hello32 Print strings on stdout preceded by "Hello"
- help Display help for commands
================================================================================
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1191,19 +1170,6 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Help displays usage descriptions for this command, or usage descriptions for
-sub-commands.
-
-Usage:
- prog1 prog2 prog3 help [flags] <command>
-
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
-
-The help flags are:
- -style=text: The formatting style for help output, either "text" or "godoc".
-================================================================================
Hello prints any strings passed in to stdout preceded by "Hello".
Usage:
@@ -1215,24 +1181,10 @@
sub-commands.
Usage:
- prog1 prog2 help [flags] <command>
+ prog1 help [flags] [command ...]
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
-
-The help flags are:
- -style=text: The formatting style for help output, either "text" or "godoc".
-================================================================================
-Help displays usage descriptions for this command, or usage descriptions for
-sub-commands.
-
-Usage:
- prog1 help [flags] <command>
-
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
The help flags are:
-style=text: The formatting style for help output, either "text" or "godoc".
@@ -1271,7 +1223,6 @@
The prog3 commands are:
hello31 Print strings on stdout preceded by "Hello"
hello32 Print strings on stdout preceded by "Hello"
- help Display help for commands
================================================================================
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1287,19 +1238,6 @@
[strings] are arbitrary strings that will be printed.
================================================================================
-Help displays usage descriptions for this command, or usage descriptions for
-sub-commands.
-
-Usage:
- prog1 prog2 prog3 help [flags] <command>
-
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
-
-The help flags are:
- -style=text: The formatting style for help output, either "text" or "godoc".
-================================================================================
Hello prints any strings passed in to stdout preceded by "Hello".
Usage:
@@ -1311,11 +1249,10 @@
sub-commands.
Usage:
- prog1 prog2 help [flags] <command>
+ prog1 prog2 help [flags] [command ...]
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
The help flags are:
-style=text: The formatting style for help output, either "text" or "godoc".
@@ -1356,11 +1293,10 @@
sub-commands.
Usage:
- prog1 prog2 prog3 help [flags] <command>
+ prog1 prog2 prog3 help [flags] [command ...]
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
The help flags are:
-style=text: The formatting style for help output, either "text" or "godoc".
@@ -1401,11 +1337,10 @@
sub-commands.
Usage:
- prog1 prog2 prog3 help [flags] <command>
+ prog1 prog2 prog3 help [flags] [command ...]
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
The help flags are:
-style=text: The formatting style for help output, either "text" or "godoc".
@@ -1458,7 +1393,6 @@
hello21 Print strings on stdout preceded by "Hello"
prog3 Set of hello commands
hello22 Print strings on stdout preceded by "Hello"
- help Display help for commands
Prog1 Prog2 Hello21
@@ -1479,7 +1413,6 @@
The prog3 commands are:
hello31 Print strings on stdout preceded by "Hello"
hello32 Print strings on stdout preceded by "Hello"
- help Display help for commands
Prog1 Prog2 Prog3 Hello31
@@ -1499,21 +1432,6 @@
[strings] are arbitrary strings that will be printed.
-Prog1 Prog2 Prog3 Help
-
-Help displays usage descriptions for this command, or usage descriptions for
-sub-commands.
-
-Usage:
- prog1 prog2 prog3 help [flags] <command>
-
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
-
-The help flags are:
- -style=text: The formatting style for help output, either "text" or "godoc".
-
Prog1 Prog2 Hello22
Hello prints any strings passed in to stdout preceded by "Hello".
@@ -1523,32 +1441,16 @@
[strings] are arbitrary strings that will be printed.
-Prog1 Prog2 Help
-
-Help displays usage descriptions for this command, or usage descriptions for
-sub-commands.
-
-Usage:
- prog1 prog2 help [flags] <command>
-
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
-
-The help flags are:
- -style=text: The formatting style for help output, either "text" or "godoc".
-
Prog1 Help
Help displays usage descriptions for this command, or usage descriptions for
sub-commands.
Usage:
- prog1 help [flags] <command>
+ prog1 help [flags] [command ...]
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
The help flags are:
-style=text: The formatting style for help output, either "text" or "godoc".
@@ -1653,11 +1555,10 @@
sub-commands.
Usage:
- cmdargs help [flags] <command>
+ cmdargs help [flags] [command ...]
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
The help flags are:
-style=text: The formatting style for help output, either "text" or "godoc".
@@ -1818,11 +1719,10 @@
sub-commands.
Usage:
- cmdrun help [flags] <command>
+ cmdrun help [flags] [command ...]
-<command> is an optional sequence of commands to display detailed per-command
-usage. The special-case "help ..." recursively displays help for this command
-and all sub-commands.
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
The help flags are:
-style=text: The formatting style for help output, either "text" or "godoc".
diff --git a/tools/application/impl/impl.go b/tools/application/impl/impl.go
index 8af0a9f..a029ee8 100644
--- a/tools/application/impl/impl.go
+++ b/tools/application/impl/impl.go
@@ -220,9 +220,12 @@
func Root() *cmdline.Command {
return &cmdline.Command{
- Name: "application",
- Short: "Command-line tool for interacting with the veyron application repository",
- Long: "Command-line tool for interacting with the veyron application repository",
+ Name: "application",
+ Short: "Tool for interacting with the veyron application repository",
+ Long: `
+The application tool facilitates interaction with the veyron application
+repository.
+`,
Children: []*cmdline.Command{cmdMatch, cmdPut, cmdRemove, cmdEdit},
}
}
diff --git a/tools/application/main.go b/tools/application/main.go
index a9ec584..2bcd6f3 100644
--- a/tools/application/main.go
+++ b/tools/application/main.go
@@ -1,3 +1,85 @@
+// Below is the output from $(application help -style=godoc ...)
+
+/*
+The application tool facilitates interaction with the veyron application
+repository.
+
+Usage:
+ application <command>
+
+The application commands are:
+ match Shows the first matching envelope that matches the given profiles.
+ put Add the given envelope to the application for the given profiles.
+ remove removes the application envelope for the given profile.
+ edit edits the application envelope for the given profile.
+ help Display help for commands
+
+The global flags are:
+ -alsologtostderr=true: log to standard error as well as files
+ -log_backtrace_at=:0: when logging hits line file:N, emit a stack trace
+ -log_dir=: if non-empty, write log files to this directory
+ -logtostderr=false: log to standard error instead of files
+ -max_stack_buf_size=4292608: max size in bytes of the buffer to use for logging stack traces
+ -stderrthreshold=2: logs at or above this threshold go to stderr
+ -v=0: log level for V logs
+ -vmodule=: comma-separated list of pattern=N settings for file-filtered logging
+ -vv=0: log level for V logs
+
+Application Match
+
+Shows the first matching envelope that matches the given profiles.
+
+Usage:
+ application match <application> <profiles>
+
+<application> is the full name of the application.
+<profiles> is a comma-separated list of profiles.
+
+Application Put
+
+Add the given envelope to the application for the given profiles.
+
+Usage:
+ application put <application> <profiles> <envelope>
+
+<application> is the full name of the application.
+<profiles> is a comma-separated list of profiles.
+<envelope> is the file that contains a JSON-encoded envelope.
+
+Application Remove
+
+removes the application envelope for the given profile.
+
+Usage:
+ application remove <application> <profile>
+
+<application> is the full name of the application.
+<profile> is a profile.
+
+Application Edit
+
+edits the application envelope for the given profile.
+
+Usage:
+ application edit <application> <profile>
+
+<application> is the full name of the application.
+<profile> is a profile.
+
+Application Help
+
+Help displays usage descriptions for this command, or usage descriptions for
+sub-commands.
+
+Usage:
+ application help [flags] [command ...]
+
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
+
+The help flags are:
+ -style=text: The formatting style for help output, either "text" or "godoc".
+*/
package main
import (
diff --git a/tools/binary/impl/impl.go b/tools/binary/impl/impl.go
index b5a1cec..d43ebd3 100644
--- a/tools/binary/impl/impl.go
+++ b/tools/binary/impl/impl.go
@@ -84,9 +84,11 @@
func Root() *cmdline.Command {
return &cmdline.Command{
- Name: "binary",
- Short: "Command-line tool for interacting with the veyron binary repository",
- Long: "Command-line tool for interacting with the veyron binary repository",
+ Name: "binary",
+ Short: "Tool for interacting with the veyron binary repository",
+ Long: `
+The binary tool facilitates interaction with the veyron binary repository.
+`,
Children: []*cmdline.Command{cmdDelete, cmdDownload, cmdUpload},
}
}
diff --git a/tools/binary/main.go b/tools/binary/main.go
index b512f32..a206d11 100644
--- a/tools/binary/main.go
+++ b/tools/binary/main.go
@@ -1,3 +1,73 @@
+// Below is the output from $(binary help -style=godoc ...)
+
+/*
+The binary tool facilitates interaction with the veyron binary repository.
+
+Usage:
+ binary <command>
+
+The binary commands are:
+ delete Delete binary
+ download Download binary
+ upload Upload binary
+ help Display help for commands
+
+The global flags are:
+ -alsologtostderr=true: log to standard error as well as files
+ -log_backtrace_at=:0: when logging hits line file:N, emit a stack trace
+ -log_dir=: if non-empty, write log files to this directory
+ -logtostderr=false: log to standard error instead of files
+ -max_stack_buf_size=4292608: max size in bytes of the buffer to use for logging stack traces
+ -stderrthreshold=2: logs at or above this threshold go to stderr
+ -v=0: log level for V logs
+ -vmodule=: comma-separated list of pattern=N settings for file-filtered logging
+ -vv=0: log level for V logs
+
+Binary Delete
+
+Delete connects to the binary repository and deletes the specified binary
+
+Usage:
+ binary delete <von>
+
+<von> is the veyron object name of the binary to delete
+
+Binary Download
+
+Download connects to the binary repository, downloads the specified binary, and
+writes it to a file.
+
+Usage:
+ binary download <von> <filename>
+
+<von> is the veyron object name of the binary to download
+<filename> is the name of the file where the binary will be written
+
+Binary Upload
+
+Upload connects to the binary repository and uploads the binary of the specified
+file. When successful, it writes the name of the new binary to stdout.
+
+Usage:
+ binary upload <von> <filename>
+
+<von> is the veyron object name of the binary to upload
+<filename> is the name of the file to upload
+
+Binary Help
+
+Help displays usage descriptions for this command, or usage descriptions for
+sub-commands.
+
+Usage:
+ binary help [flags] [command ...]
+
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
+
+The help flags are:
+ -style=text: The formatting style for help output, either "text" or "godoc".
+*/
package main
import (
diff --git a/tools/build/impl/impl.go b/tools/build/impl/impl.go
index e9e0714..6126bfc 100644
--- a/tools/build/impl/impl.go
+++ b/tools/build/impl/impl.go
@@ -28,9 +28,11 @@
}
var cmdRoot = &cmdline.Command{
- Name: "build",
- Short: "Command-line tool for interacting with the veyron build server",
- Long: "Command-line tool for interacting with the veyron build server.",
+ Name: "build",
+ Short: "Tool for interacting with the veyron build server",
+ Long: `
+The build tool tool facilitates interaction with the veyron build server.
+`,
Children: []*cmdline.Command{cmdBuild},
}
diff --git a/tools/build/main.go b/tools/build/main.go
index 5da2faf..696e982 100644
--- a/tools/build/main.go
+++ b/tools/build/main.go
@@ -1,3 +1,61 @@
+// Below is the output from $(build help -style=godoc ...)
+
+/*
+The build tool tool facilitates interaction with the veyron build server.
+
+Usage:
+ build <command>
+
+The build commands are:
+ build Build veyron Go packages
+ help Display help for commands
+
+The global flags are:
+ -alsologtostderr=true: log to standard error as well as files
+ -log_backtrace_at=:0: when logging hits line file:N, emit a stack trace
+ -log_dir=: if non-empty, write log files to this directory
+ -logtostderr=false: log to standard error instead of files
+ -max_stack_buf_size=4292608: max size in bytes of the buffer to use for logging stack traces
+ -stderrthreshold=2: logs at or above this threshold go to stderr
+ -v=0: log level for V logs
+ -vmodule=: comma-separated list of pattern=N settings for file-filtered logging
+ -vv=0: log level for V logs
+
+Build Build
+
+Build veyron Go packages using a remote build server. The command
+collects all source code files that are not part of the Go standard
+library that the target packages depend on, sends them to a build
+server, and receives the built binaries.
+
+Usage:
+ build build [flags] <name> <packages>
+
+<name> is a veyron object name of a build server
+<packages> is a list of packages to build, specified as arguments for
+each command. The format is similar to the go tool. In its simplest
+form each package is an import path; e.g. "veyron/tools/build". A
+package that ends with "..." does a wildcard match against all
+packages with that prefix.
+
+The build flags are:
+ -arch=amd64: Target architecture.
+ -os=linux: Target operating system.
+
+Build Help
+
+Help displays usage descriptions for this command, or usage descriptions for
+sub-commands.
+
+Usage:
+ build help [flags] [command ...]
+
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
+
+The help flags are:
+ -style=text: The formatting style for help output, either "text" or "godoc".
+*/
package main
import (
diff --git a/tools/identity/main.go b/tools/identity/main.go
index 9ddc3f6..35b5379 100644
--- a/tools/identity/main.go
+++ b/tools/identity/main.go
@@ -1,3 +1,120 @@
+// Below is the output from $(identity help -style=godoc ...)
+
+/*
+The identity tool helps create and manage keys and blessings that are used for
+identification in veyron.
+
+Usage:
+ identity <command>
+
+The identity commands are:
+ print Print out information about the provided identity
+ generate Generate an identity with a newly minted private key
+ bless Bless another identity with your own
+ seekblessing Seek a blessing from the default veyron identity provider
+ help Display help for commands
+
+The global flags are:
+ -alsologtostderr=true: log to standard error as well as files
+ -log_backtrace_at=:0: when logging hits line file:N, emit a stack trace
+ -log_dir=: if non-empty, write log files to this directory
+ -logtostderr=false: log to standard error instead of files
+ -max_stack_buf_size=4292608: max size in bytes of the buffer to use for logging stack traces
+ -stderrthreshold=2: logs at or above this threshold go to stderr
+ -v=0: log level for V logs
+ -vmodule=: comma-separated list of pattern=N settings for file-filtered logging
+ -vv=0: log level for V logs
+
+Identity Print
+
+Print dumps out information about the identity encoded in the provided file,
+or if no filename is provided, then the identity that would be used by binaries
+started in the same environment.
+
+Usage:
+ identity print [<file>]
+
+<file> is the path to a file containing a base64-encoded, VOM encoded identity,
+typically obtained from this tool. - is used for STDIN and an empty string
+implies the identity encoded in the environment.
+
+Identity Generate
+
+Generate a new private key and create an identity that binds <name> to
+this key.
+
+Since the generated identity has a newly minted key, it will be typically
+unusable at other veyron services as those services have placed no trust
+in this key. In such cases, you likely want to seek a blessing for this
+generated identity using the 'bless' command.
+
+Usage:
+ identity generate [<name>]
+
+<name> is the name to bind the newly minted private key to. If not specified,
+a name will be generated based on the hostname of the machine and the name of
+the user running this command.
+
+Identity Bless
+
+Bless uses the identity of the tool (either from an environment variable or
+explicitly specified using --with) to bless another identity encoded in a
+file (or STDIN). No caveats are applied to this blessing other than expiration,
+which is specified with --for.
+
+The output consists of a base64-vom encoded security.PrivateID or security.PublicID,
+depending on what was provided as input.
+
+For example, if the tool has an identity veyron/user/device, then
+bless /tmp/blessee batman
+will generate a blessing with the name veyron/user/device/batman
+
+The identity of the tool can be specified with the --with flag:
+bless --with /tmp/id /tmp/blessee batman
+
+Usage:
+ identity bless [flags] <file> <name>
+
+<file> is the name of the file containing a base64-vom encoded security.PublicID
+or security.PrivateID
+
+<name> is the name to use for the blessing.
+
+The bless flags are:
+ -for=8760h0m0s: Expiry time of blessing (defaults to 1 year)
+ -with=: Path to file containing identity to bless with (or - for STDIN)
+
+Identity Seekblessing
+
+Seeks a blessing from a default, hardcoded Veyron identity provider which
+requires the caller to first authenticate with Google using OAuth. Simply
+run the command to see what happens.
+
+The blessing is sought for the identity that this tool is using. An alternative
+can be provided with the --for flag.
+
+Usage:
+ identity seekblessing [flags]
+
+The seekblessing flags are:
+ -clientid=761523829214-4ms7bae18ef47j6590u9ncs19ffuo7b3.apps.googleusercontent.com: OAuth client ID used to make OAuth request for an authorization code
+ -for=: Path to file containing identity to bless (or - for STDIN)
+ -from=/proxy.envyor.com:8101/identity/veyron-test/google: Object name of Veyron service running the identity.OAuthBlesser service to seek blessings from
+
+Identity Help
+
+Help displays usage descriptions for this command, or usage descriptions for
+sub-commands.
+
+Usage:
+ identity help [flags] [command ...]
+
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
+
+The help flags are:
+ -style=text: The formatting style for help output, either "text" or "godoc".
+*/
package main
import (
@@ -257,7 +374,7 @@
(&cmdline.Command{
Name: "identity",
- Short: "Create an manage veyron identities",
+ Short: "Create and manage veyron identities",
Long: `
The identity tool helps create and manage keys and blessings that are used for
identification in veyron.
diff --git a/tools/mounttable/impl/impl.go b/tools/mounttable/impl/impl.go
index 5d67326..0bec3fe 100644
--- a/tools/mounttable/impl/impl.go
+++ b/tools/mounttable/impl/impl.go
@@ -171,9 +171,11 @@
func Root() *cmdline.Command {
return &cmdline.Command{
- Name: "mounttable",
- Short: "Command-line tool for interacting with a Veyron mount table",
- Long: "Command-line tool for interacting with a Veyron mount table",
+ Name: "mounttable",
+ Short: "Tool for interacting with a Veyron mount table",
+ Long: `
+The mounttable tool facilitates interaction with a Veyron mount table.
+`,
Children: []*cmdline.Command{cmdGlob, cmdMount, cmdUnmount, cmdResolveStep},
}
}
diff --git a/tools/mounttable/main.go b/tools/mounttable/main.go
index 7f2c385..80216f1 100644
--- a/tools/mounttable/main.go
+++ b/tools/mounttable/main.go
@@ -1,3 +1,85 @@
+// Below is the output from $(mounttable help -style=godoc ...)
+
+/*
+The mounttable tool facilitates interaction with a Veyron mount table.
+
+Usage:
+ mounttable <command>
+
+The mounttable commands are:
+ glob returns all matching entries in the mount table
+ mount Mounts a server <name> onto a mount table
+ unmount removes server <name> from the mount table
+ resolvestep takes the next step in resolving a name.
+ help Display help for commands
+
+The global flags are:
+ -alsologtostderr=true: log to standard error as well as files
+ -log_backtrace_at=:0: when logging hits line file:N, emit a stack trace
+ -log_dir=: if non-empty, write log files to this directory
+ -logtostderr=false: log to standard error instead of files
+ -max_stack_buf_size=4292608: max size in bytes of the buffer to use for logging stack traces
+ -stderrthreshold=2: logs at or above this threshold go to stderr
+ -v=0: log level for V logs
+ -vmodule=: comma-separated list of pattern=N settings for file-filtered logging
+ -vv=0: log level for V logs
+
+Mounttable Glob
+
+returns all matching entries in the mount table
+
+Usage:
+ mounttable glob <mount name> <pattern>
+
+<mount name> is a mount name on a mount table.
+<pattern> is a glob pattern that is matched against all the entries below the
+specified mount name.
+
+Mounttable Mount
+
+Mounts a server <name> onto a mount table
+
+Usage:
+ mounttable mount <mount name> <name> <ttl>
+
+<mount name> is a mount name on a mount table.
+<name> is the rooted object name of the server.
+<ttl> is the TTL of the new entry. It is a decimal number followed by a unit
+suffix (s, m, h). A value of 0s represents an infinite duration.
+
+Mounttable Unmount
+
+removes server <name> from the mount table
+
+Usage:
+ mounttable unmount <mount name> <name>
+
+<mount name> is a mount name on a mount table.
+<name> is the rooted object name of the server.
+
+Mounttable Resolvestep
+
+takes the next step in resolving a name.
+
+Usage:
+ mounttable resolvestep <mount name>
+
+<mount name> is a mount name on a mount table.
+
+Mounttable Help
+
+Help displays usage descriptions for this command, or usage descriptions for
+sub-commands.
+
+Usage:
+ mounttable help [flags] [command ...]
+
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
+
+The help flags are:
+ -style=text: The formatting style for help output, either "text" or "godoc".
+*/
package main
import (
diff --git a/tools/namespace/impl/impl.go b/tools/namespace/impl/impl.go
index d8fe9a9..2d80389 100644
--- a/tools/namespace/impl/impl.go
+++ b/tools/namespace/impl/impl.go
@@ -198,9 +198,9 @@
func Root() *cmdline.Command {
return &cmdline.Command{
Name: "namespace",
- Short: "Command-line tool for interacting with the Veyron namespace",
+ Short: "Tool for interacting with the Veyron namespace",
Long: `
-Command-line tool for interacting with the Veyron namespace.
+The namespace tool facilitates interaction with the Veyron namespace.
The namespace roots are set from environment variables that have a name
starting with NAMESPACE_ROOT, e.g. NAMESPACE_ROOT, NAMESPACE_ROOT_2,
diff --git a/tools/namespace/main.go b/tools/namespace/main.go
index 9fcf1cf..babf6ca 100644
--- a/tools/namespace/main.go
+++ b/tools/namespace/main.go
@@ -1,4 +1,108 @@
-// A command-line tool to interface with the veyron namespace.
+// Below is the output from $(namespace help -style=godoc ...)
+
+/*
+The namespace tool facilitates interaction with the Veyron namespace.
+
+The namespace roots are set from environment variables that have a name
+starting with NAMESPACE_ROOT, e.g. NAMESPACE_ROOT, NAMESPACE_ROOT_2,
+NAMESPACE_ROOT_GOOGLE, etc.
+
+Usage:
+ namespace <command>
+
+The namespace commands are:
+ glob Returns all matching entries from the namespace
+ mount Adds a server to the namespace
+ unmount Removes a server from the namespace
+ resolve Translates a object name to its object address(es)
+ resolvetomt Finds the address of the mounttable that holds an object name
+ unresolve Returns the rooted object names for the given object name
+ help Display help for commands
+
+The global flags are:
+ -alsologtostderr=true: log to standard error as well as files
+ -log_backtrace_at=:0: when logging hits line file:N, emit a stack trace
+ -log_dir=: if non-empty, write log files to this directory
+ -logtostderr=false: log to standard error instead of files
+ -max_stack_buf_size=4292608: max size in bytes of the buffer to use for logging stack traces
+ -stderrthreshold=2: logs at or above this threshold go to stderr
+ -v=0: log level for V logs
+ -vmodule=: comma-separated list of pattern=N settings for file-filtered logging
+ -vv=0: log level for V logs
+
+Namespace Glob
+
+Returns all matching entries from the namespace.
+
+Usage:
+ namespace glob <pattern>
+
+<pattern> is a glob pattern that is matched against all the names below the
+specified mount name.
+
+Namespace Mount
+
+Adds server <server> to the namespace with name <name>.
+
+Usage:
+ namespace mount <name> <server> <ttl>
+
+<name> is the name to add to the namespace.
+<server> is the object address of the server to add.
+<ttl> is the TTL of the new entry. It is a decimal number followed by a unit
+suffix (s, m, h). A value of 0s represents an infinite duration.
+
+Namespace Unmount
+
+Removes server <server> with name <name> from the namespace.
+
+Usage:
+ namespace unmount <name> <server>
+
+<name> is the name to remove from the namespace.
+<server> is the object address of the server to remove.
+
+Namespace Resolve
+
+Translates a object name to its object address(es).
+
+Usage:
+ namespace resolve <name>
+
+<name> is the name to resolve.
+
+Namespace Resolvetomt
+
+Finds the address of the mounttable that holds an object name.
+
+Usage:
+ namespace resolvetomt <name>
+
+<name> is the name to resolve.
+
+Namespace Unresolve
+
+Returns the rooted object names for the given object name.
+
+Usage:
+ namespace unresolve <name>
+
+<name> is the object name to unresolve.
+
+Namespace Help
+
+Help displays usage descriptions for this command, or usage descriptions for
+sub-commands.
+
+Usage:
+ namespace help [flags] [command ...]
+
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
+
+The help flags are:
+ -style=text: The formatting style for help output, either "text" or "godoc".
+*/
package main
import (
diff --git a/tools/profile/impl/impl.go b/tools/profile/impl/impl.go
index 4413896..a0c0868 100644
--- a/tools/profile/impl/impl.go
+++ b/tools/profile/impl/impl.go
@@ -162,9 +162,11 @@
func Root() *cmdline.Command {
return &cmdline.Command{
- Name: "profile",
- Short: "Command-line tool for interacting with the veyron profile repository",
- Long: "Command-line tool for interacting with the veyron profile repository",
+ Name: "profile",
+ Short: "Tool for interacting with the veyron profile repository",
+ Long: `
+The profile tool facilitates interaction with the veyron profile repository.
+`,
Children: []*cmdline.Command{cmdLabel, cmdDescription, cmdSpecification, cmdPut, cmdRemove},
}
}
diff --git a/tools/profile/main.go b/tools/profile/main.go
index bd2531a..f6cf6d2 100644
--- a/tools/profile/main.go
+++ b/tools/profile/main.go
@@ -1,3 +1,89 @@
+// Below is the output from $(profile help -style=godoc ...)
+
+/*
+The profile tool facilitates interaction with the veyron profile repository.
+
+Usage:
+ profile <command>
+
+The profile commands are:
+ label Shows a human-readable profile key for the profile.
+ description Shows a human-readable profile description for the profile.
+ spec Shows the specification of the profile.
+ put Sets a placeholder specification for the profile.
+ remove removes the profile specification for the profile.
+ help Display help for commands
+
+The global flags are:
+ -alsologtostderr=true: log to standard error as well as files
+ -log_backtrace_at=:0: when logging hits line file:N, emit a stack trace
+ -log_dir=: if non-empty, write log files to this directory
+ -logtostderr=false: log to standard error instead of files
+ -max_stack_buf_size=4292608: max size in bytes of the buffer to use for logging stack traces
+ -stderrthreshold=2: logs at or above this threshold go to stderr
+ -v=0: log level for V logs
+ -vmodule=: comma-separated list of pattern=N settings for file-filtered logging
+ -vv=0: log level for V logs
+
+Profile Label
+
+Shows a human-readable profile key for the profile.
+
+Usage:
+ profile label <profile>
+
+<profile> is the full name of the profile.
+
+Profile Description
+
+Shows a human-readable profile description for the profile.
+
+Usage:
+ profile description <profile>
+
+<profile> is the full name of the profile.
+
+Profile Spec
+
+Shows the specification of the profile.
+
+Usage:
+ profile spec <profile>
+
+<profile> is the full name of the profile.
+
+Profile Put
+
+Sets a placeholder specification for the profile.
+
+Usage:
+ profile put <profile>
+
+<profile> is the full name of the profile.
+
+Profile Remove
+
+removes the profile specification for the profile.
+
+Usage:
+ profile remove <profile>
+
+<profile> is the full name of the profile.
+
+Profile Help
+
+Help displays usage descriptions for this command, or usage descriptions for
+sub-commands.
+
+Usage:
+ profile help [flags] [command ...]
+
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
+
+The help flags are:
+ -style=text: The formatting style for help output, either "text" or "godoc".
+*/
package main
import (
diff --git a/tools/vrpc/impl/impl.go b/tools/vrpc/impl/impl.go
index 05483e9..39a71ae 100644
--- a/tools/vrpc/impl/impl.go
+++ b/tools/vrpc/impl/impl.go
@@ -195,7 +195,7 @@
func Root() *cmdline.Command {
return &cmdline.Command{
Name: "vrpc",
- Short: "Command-line tool for interacting with Veyron RPC servers.",
+ Short: "Tool for interacting with Veyron RPC servers.",
Long: `
The vrpc tool enables interacting with Veyron RPC servers. In particular,
it can be used to 1) find out what API a Veyron RPC server exports and
diff --git a/tools/vrpc/main.go b/tools/vrpc/main.go
index be42ae3..db4e2ba 100644
--- a/tools/vrpc/main.go
+++ b/tools/vrpc/main.go
@@ -1,3 +1,74 @@
+// Below is the output from $(vrpc help -style=godoc ...)
+
+/*
+The vrpc tool enables interacting with Veyron RPC servers. In particular,
+it can be used to 1) find out what API a Veyron RPC server exports and
+2) send requests to a Veyron RPC server.
+
+Usage:
+ vrpc <command>
+
+The vrpc commands are:
+ describe Describe the API of an Veyron RPC server
+ invoke Invoke a method of an Veyron RPC server
+ help Display help for commands
+
+The global flags are:
+ -alsologtostderr=true: log to standard error as well as files
+ -log_backtrace_at=:0: when logging hits line file:N, emit a stack trace
+ -log_dir=: if non-empty, write log files to this directory
+ -logtostderr=false: log to standard error instead of files
+ -max_stack_buf_size=4292608: max size in bytes of the buffer to use for logging stack traces
+ -stderrthreshold=2: logs at or above this threshold go to stderr
+ -v=0: log level for V logs
+ -vmodule=: comma-separated list of pattern=N settings for file-filtered logging
+ -vv=0: log level for V logs
+
+Vrpc Describe
+
+Describe connects to the Veyron RPC server identified by <server>, finds out what
+its API is, and outputs a succint summary of this API to the standard output.
+
+Usage:
+ vrpc describe <server>
+
+<server> identifies the Veyron RPC server. It can either be the object address of
+the server or an Object name in which case the vrpc will use Veyron's name
+resolution to match this name to an end-point.
+
+Vrpc Invoke
+
+Invoke connects to the Veyron RPC server identified by <server>, invokes the method
+identified by <method>, supplying the arguments identified by <args>, and outputs
+the results of the invocation to the standard output.
+
+Usage:
+ vrpc invoke <server> <method> <args>
+
+<server> identifies the Veyron RPC server. It can either be the object address of
+the server or an Object name in which case the vrpc will use Veyron's name
+resolution to match this name to an end-point.
+
+<method> identifies the name of the method to be invoked.
+
+<args> identifies the arguments of the method to be invoked. It should be a list
+of values in a VOM JSON format that can be reflected to the correct type
+using Go's reflection.
+
+Vrpc Help
+
+Help displays usage descriptions for this command, or usage descriptions for
+sub-commands.
+
+Usage:
+ vrpc help [flags] [command ...]
+
+[command ...] is an optional sequence of commands to display detailed usage.
+The special-case "help ..." recursively displays help for all commands.
+
+The help flags are:
+ -style=text: The formatting style for help output, either "text" or "godoc".
+*/
package main
import (
