cmd: allow branding

This change allows users that build their own executable or "spin" of
OPA to give it a name, and have it reference itself properly in help
texts.

It's a vanity thing, but I think some people would appreciate it, hat
tip to the international association of pedants.

Signed-off-by: Stephan Renatus <[email protected]>
Co-authored-by: kevinstyra <[email protected]>

Author: kevinstyra

build/generate-cli-docs/generate.go

@@ -13,7 +13,7 @@ import (
 )
 
 func main() {
-	command := cmd.RootCommand
+	command := cmd.Command(nil, "opa")
 	command.Use = "opa [command]"
 	command.DisableAutoGenTag = true
 

build/generate-man/generate.go

@@ -23,7 +23,7 @@ func main() {
 		log.Fatal(err)
 	}
 
-	cmd := cmd.RootCommand
+	cmd := cmd.Command(nil, "OPA")
 	cmd.Use = "opa [command]"
 	cmd.DisableAutoGenTag = true
 

cmd/bench.go

@@ -63,7 +63,9 @@ func newBenchmarkEvalParams() benchmarkCommandParams {
 	}
 }
 
-func init() {
+func initBench(root *cobra.Command, brand string) {
+	executable := root.Name()
+
 	params := newBenchmarkEvalParams()
 
 	benchCommand := &cobra.Command{
@@ -76,9 +78,10 @@ evaluation will be repeated a number of times and performance results will be re
 
 Example with bundle and input data:
 
-	opa bench -b ./policy-bundle -i input.json 'data.authz.allow'
+	` + executable + ` bench -b ./policy-bundle -i input.json 'data.authz.allow'
 
-To run benchmarks against a running OPA server to evaluate server overhead use the --e2e flag.
+To run benchmarks against a running ` + brand + ` server to evaluate server overhead use the --e2e flag.
+To enable more detailed analysis use the --metrics and --benchmem flags.
 
 The optional "gobench" output format conforms to the Go Benchmark Data Format.
 `,
@@ -130,13 +133,13 @@ The optional "gobench" output format conforms to the Go Benchmark Data Format.
 	addCountFlag(benchCommand.Flags(), &params.count, "benchmark")
 	addBenchmemFlag(benchCommand.Flags(), &params.benchMem, true)
 
-	addE2EFlag(benchCommand.Flags(), &params.e2e, false)
+	addE2EFlag(benchCommand.Flags(), &params.e2e, false, brand)
 	addConfigFileFlag(benchCommand.Flags(), &params.configFile)
 
 	benchCommand.Flags().IntVar(&params.gracefulShutdownPeriod, "shutdown-grace-period", 10, "set the time (in seconds) that the server will wait to gracefully shut down. This flag is valid in 'e2e' mode only.")
 	benchCommand.Flags().IntVar(&params.shutdownWaitPeriod, "shutdown-wait-period", 0, "set the time (in seconds) that the server will wait before initiating shutdown. This flag is valid in 'e2e' mode only.")
 
-	RootCommand.AddCommand(benchCommand)
+	root.AddCommand(benchCommand)
 }
 
 type benchRunner interface {

cmd/build.go

@@ -69,34 +69,35 @@ func (p *buildParams) regoVersion() ast.RegoVersion {
 	return ast.DefaultRegoVersion
 }
 
-func init() {
+func initBuild(root *cobra.Command, brand string) {
+	executable := root.Name()
 
 	buildParams := newBuildParams()
 
 	var buildCommand = &cobra.Command{
 		Use:   "build <path> [<path> [...]]",
-		Short: "Build an OPA bundle",
-		Long: `Build an OPA bundle.
+		Short: `Build an ` + brand + ` bundle`,
+		Long: `Build an ` + brand + ` bundle.
 
-The 'build' command packages OPA policy and data files into bundles. Bundles are
+The 'build' command packages ` + brand + ` policy and data files into bundles. Bundles are
 gzipped tarballs containing policies and data. Paths referring to directories are
 loaded recursively.
 
     $ ls
     example.rego
 
-    $ opa build -b .
+    $ ` + executable + ` build -b .
 
-You can load bundles into OPA on the command-line:
+You can load bundles into ` + brand + ` on the command-line:
 
     $ ls
     bundle.tar.gz example.rego
 
-    $ opa run bundle.tar.gz
+    $ ` + executable + ` run bundle.tar.gz
 
-You can also configure OPA to download bundles from remote HTTP endpoints:
+You can also configure ` + brand + ` to download bundles from remote HTTP endpoints:
 
-    $ opa run --server \
+    $ ` + executable + ` run --server \
         --set bundles.example.resource=bundle.tar.gz \
         --set services.example.url=http://localhost:8080
 
@@ -136,9 +137,9 @@ The 'build' command supports targets (specified by -t):
             original policy or data files.
 
     plan    The plan target emits a bundle containing a plan, i.e., an intermediate
-            representation compiled from the input files for each specified entrypoint.
-            This is for further processing, OPA cannot evaluate a "plan bundle" like it
-            can evaluate a wasm or rego bundle.
+			representation compiled from the input files for each specified entrypoint.
+			This is for further processing, ` + brand + ` cannot evaluate a "plan bundle" like it
+			can evaluate a wasm or rego bundle.
 
 The -e flag tells the 'build' command which documents (entrypoints) will be queried by 
 the software asking for policy decisions, so that it can focus optimization efforts and 
@@ -161,7 +162,7 @@ https://www.openpolicyagent.org/docs/latest/management-bundles/#signing.
 
 Example:
 
-    $ opa build --verification-key /path/to/public_key.pem --signing-key /path/to/private_key.pem --bundle foo
+    $ ` + executable + ` build --verification-key /path/to/public_key.pem --signing-key /path/to/private_key.pem --bundle foo
 
 Where foo has the following structure:
 
@@ -196,7 +197,7 @@ see https://www.openpolicyagent.org/docs/latest/management-bundles/#signature-fo
 Capabilities
 ------------
 
-The 'build' command can validate policies against a configurable set of OPA capabilities.
+The 'build' command can validate policies against a configurable set of ` + brand + ` capabilities.
 The capabilities define the built-in functions and other language features that policies
 may depend on. For example, the following capabilities file only permits the policy to
 depend on the "plus" built-in function ('+'):
@@ -224,12 +225,12 @@ depend on the "plus" built-in function ('+'):
         ]
     }
 
-Capabilities can be used to validate policies against a specific version of OPA.
-The OPA repository contains a set of capabilities files for each OPA release. For example,
+Capabilities can be used to validate policies against a specific version of ` + brand + `.
+The ` + brand + ` repository contains a set of capabilities files for each ` + brand + ` release. For example,
 the following command builds a directory of policies ('./policies') and validates them
-against OPA v0.22.0:
+against ` + brand + ` v0.22.0:
 
-    opa build ./policies --capabilities v0.22.0
+    ` + executable + ` build ./policies --capabilities v0.22.0
 `,
 		PreRunE: func(Cmd *cobra.Command, args []string) error {
 			if len(args) == 0 {
@@ -279,7 +280,7 @@ against OPA v0.22.0:
 	addV0CompatibleFlag(buildCommand.Flags(), &buildParams.v0Compatible, false)
 	addV1CompatibleFlag(buildCommand.Flags(), &buildParams.v1Compatible, false)
 
-	RootCommand.AddCommand(buildCommand)
+	root.AddCommand(buildCommand)
 }
 
 func dobuild(params buildParams, args []string) error {

cmd/capabilities.go

@@ -28,20 +28,21 @@ func (p *capabilitiesParams) regoVersion() ast.RegoVersion {
 	return ast.DefaultRegoVersion
 }
 
-func init() {
+func initCapabilities(root *cobra.Command, brand string) {
+	executable := root.Name()
 
 	capabilitiesParams := capabilitiesParams{}
 
 	var capabilitiesCommand = &cobra.Command{
 		Use:   "capabilities",
-		Short: "Print the capabilities of OPA",
-		Long: `Show capabilities for OPA.
+		Short: "Print the capabilities of " + brand,
+		Long: `Show capabilities for ` + brand + `.
 
-The 'capabilities' command prints the OPA capabilities, prior to and including the version of OPA used.
+The 'capabilities' command prints the ` + brand + ` capabilities, prior to and including the version of ` + brand + ` used.
 
 Print a list of all existing capabilities version names
 
-    $ opa capabilities
+    $ ` + executable + ` capabilities
     v0.17.0
     v0.17.1
     ...
@@ -52,7 +53,7 @@ Print a list of all existing capabilities version names
 
 Print the capabilities of the current version
 
-    $ opa capabilities --current
+    $ ` + executable + ` capabilities --current
     {
         "builtins": [...],
         "future_keywords": [...],
@@ -61,7 +62,7 @@ Print the capabilities of the current version
 
 Print the capabilities of a specific version
 
-    $ opa capabilities --version v0.32.1
+    $ ` + executable + ` capabilities --version v0.32.1
     {
         "builtins": [...],
         "future_keywords": null,
@@ -70,7 +71,7 @@ Print the capabilities of a specific version
 
 Print the capabilities of a capabilities file
 
-    $ opa capabilities --file ./capabilities/v0.32.1.json
+    $ ` + executable + ` capabilities --file ./capabilities/v0.32.1.json
     {
         "builtins": [...],
         "future_keywords": null,
@@ -98,7 +99,7 @@ Print the capabilities of a capabilities file
 	capabilitiesCommand.Flags().StringVar(&capabilitiesParams.file, "file", "", "print capabilities defined by a file")
 	addV0CompatibleFlag(capabilitiesCommand.Flags(), &capabilitiesParams.v0Compatible, false)
 
-	RootCommand.AddCommand(capabilitiesCommand)
+	root.AddCommand(capabilitiesCommand)
 }
 
 func doCapabilities(params capabilitiesParams) (string, error) {

cmd/check.go

@@ -173,7 +173,7 @@ func outputErrors(format string, err error) {
 	}
 }
 
-func init() {
+func initCheck(root *cobra.Command, _ string) {
 	checkParams := newCheckParams()
 
 	checkCommand := &cobra.Command{
@@ -215,5 +215,6 @@ and exit with a non-zero exit code.`,
 		"check for Rego v0 and v1 compatibility (policies must be compatible with both Rego versions)")
 	addV0CompatibleFlag(checkCommand.Flags(), &checkParams.v0Compatible, false)
 	addV1CompatibleFlag(checkCommand.Flags(), &checkParams.v1Compatible, false)
-	RootCommand.AddCommand(checkCommand)
+
+	root.AddCommand(checkCommand)
 }

cmd/commands.go

@@ -5,15 +5,45 @@
 package cmd
 
 import (
-	"os"
-	"path"
-
 	"github.com/spf13/cobra"
+
+	iversion "github.com/open-policy-agent/opa/internal/version"
 )
 
-// RootCommand is the base CLI command that all subcommands are added to.
-var RootCommand = &cobra.Command{
-	Use:   path.Base(os.Args[0]),
-	Short: "Open Policy Agent (OPA)",
-	Long:  "An open source project to policy-enable your service.",
+// UserAgent lets you override the OPA UA sent with all the HTTP requests.
+// It's another vanity thing -- if you build your own version of OPA, you
+// may want to adjust this.
+// NOTE(sr): Caution: Please consider this experimental, I have the hunch
+// that we'll find a better way to make this adjustment in the future.
+func UserAgent(agent string) {
+	iversion.UserAgent = agent
+}
+
+func Command(rootCommand *cobra.Command, brand string) *cobra.Command {
+	// rootCommand is the base CLI command that all subcommands are added to.
+	if rootCommand == nil {
+		rootCommand = &cobra.Command{
+			Use:   "opa",
+			Short: "Open Policy Agent (OPA)",
+			Long:  "An open source project to policy-enable your service.",
+		}
+	}
+
+	initBench(rootCommand, brand)
+	initBuild(rootCommand, brand)
+	initCapabilities(rootCommand, brand)
+	initCheck(rootCommand, brand)
+	initDeps(rootCommand, brand)
+	initEval(rootCommand, brand)
+	initExec(rootCommand, brand)
+	initFmt(rootCommand, brand)
+	initInspect(rootCommand, brand)
+	initOracle(rootCommand, brand)
+	initParse(rootCommand, brand)
+	initRefactor(rootCommand, brand)
+	initRun(rootCommand, brand)
+	initSign(rootCommand, brand)
+	initTest(rootCommand, brand)
+	initVersion(rootCommand, brand)
+	return rootCommand
 }

cmd/deps.go

@@ -50,7 +50,9 @@ func newDepsCommandParams() depsCommandParams {
 	}
 }
 
-func init() {
+func initDeps(root *cobra.Command, _ string) {
+	executable := root.Name()
+
 	params := newDepsCommandParams()
 
 	depsCommand := &cobra.Command{
@@ -72,9 +74,9 @@ Given a policy like this:
 	is_admin if "admin" in input.user.roles
 
 To evaluate the dependencies of a simple query (e.g. data.policy.allow),
-we'd run opa deps like demonstrated below:
+we'd run ` + executable + ` deps like demonstrated below:
 
-	$ opa deps --data policy.rego data.policy.allow
+	$ ` + executable + ` deps --data policy.rego data.policy.allow
 	+------------------+----------------------+
 	|  BASE DOCUMENTS  |  VIRTUAL DOCUMENTS   |
 	+------------------+----------------------+
@@ -109,7 +111,7 @@ data.policy.is_admin.
 	addOutputFormat(depsCommand.Flags(), params.outputFormat)
 	addV1CompatibleFlag(depsCommand.Flags(), &params.v1Compatible, false)
 
-	RootCommand.AddCommand(depsCommand)
+	root.AddCommand(depsCommand)
 }
 
 func deps(args []string, params depsCommandParams, w io.Writer) error {

cmd/eval.go

@@ -187,7 +187,9 @@ func (r regoError) Unwrap() error {
 	return r.wrapped
 }
 
-func init() {
+func initEval(root *cobra.Command, _ string) {
+	executable := root.Name()
+
 	params := newEvalCommandParams()
 
 	evalCommand := &cobra.Command{
@@ -198,15 +200,15 @@ func init() {
 
 To evaluate a simple query:
 
-    $ opa eval 'x := 1; y := 2; x < y'
+    $ ` + executable + ` eval 'x := 1; y := 2; x < y'
 
 To evaluate a query against JSON data:
 
-    $ opa eval --data data.json 'name := data.names[_]'
+    $ ` + executable + ` eval --data data.json 'name := data.names[_]'
 
 To evaluate a query against JSON data supplied with a file:// URL:
 
-    $ opa eval --data file:///path/to/file.json 'data'
+    $ ` + executable + ` eval --data file:///path/to/file.json 'data'
 
 
 File & Bundle Loading
@@ -216,7 +218,7 @@ The --bundle flag will load data files and Rego files contained
 in the bundle specified by the path. It can be either a
 compressed tar archive bundle file or a directory tree.
 
-    $ opa eval --bundle /some/path 'data'
+    $ ` + executable + ` eval --bundle /some/path 'data'
 
 Where /some/path contains:
 
@@ -269,8 +271,8 @@ Schema
 The -s/--schema flag provides one or more JSON Schemas used to validate references to the input or data documents.
 Loads a single JSON file, applying it to the input document; or all the schema files under the specified directory.
 
-    $ opa eval --data policy.rego --input input.json --schema schema.json
-    $ opa eval --data policy.rego --input input.json --schema schemas/
+    $ ` + executable + ` eval --data policy.rego --input input.json --schema schema.json
+    $ ` + executable + ` eval --data policy.rego --input input.json --schema schemas/
 
 Capabilities
 ------------
@@ -364,7 +366,7 @@ access.
 	addV1CompatibleFlag(evalCommand.Flags(), &params.v1Compatible, false)
 	addReadAstValuesFromStoreFlag(evalCommand.Flags(), &params.ReadAstValuesFromStore, false)
 
-	RootCommand.AddCommand(evalCommand)
+	root.AddCommand(evalCommand)
 }
 
 func eval(args []string, params evalCommandParams, w io.Writer) (bool, error) {