diff --git a/cmd/cue/cmd/cmd.go b/cmd/cue/cmd/cmd.go
index 05756cb..1d21973 100644
--- a/cmd/cue/cmd/cmd.go
+++ b/cmd/cue/cmd/cmd.go
@@ -233,7 +233,7 @@
 	}
 
 	cmd.Flags().SetInterspersed(false)
-	cmd.Flags().StringArrayP(string(flagTags), "t", nil,
+	cmd.Flags().StringArrayP(string(flagInject), "t", nil,
 		"set the value of a tagged field")
 
 	return cmd
diff --git a/cmd/cue/cmd/common.go b/cmd/cue/cmd/common.go
index acbbb96..56a0def 100644
--- a/cmd/cue/cmd/common.go
+++ b/cmd/cue/cmd/common.go
@@ -365,7 +365,7 @@
 	if builds == nil {
 		return nil, errors.Newf(token.NoPos, "invalid args")
 	}
-	decorateInstances(cmd, flagTags.StringArray(cmd), builds)
+	decorateInstances(cmd, flagInject.StringArray(cmd), builds)
 
 	p = &buildPlan{cfg: cfg, cmd: cmd, forceOrphanProcessing: cfg.loadCfg.DataFiles}
 
diff --git a/cmd/cue/cmd/def.go b/cmd/cue/cmd/def.go
index e5a252b..11927c2 100644
--- a/cmd/cue/cmd/def.go
+++ b/cmd/cue/cmd/def.go
@@ -43,7 +43,7 @@
 	cmd.Flags().BoolP(string(flagAttributes), "A", false,
 		"display field attributes")
 
-	cmd.Flags().StringArrayP(string(flagTags), "t", nil,
+	cmd.Flags().StringArrayP(string(flagInject), "t", nil,
 		"set the value of a tagged field")
 
 	// TODO: Option to include comments in output.
diff --git a/cmd/cue/cmd/eval.go b/cmd/cue/cmd/eval.go
index 910bd22..081571c 100644
--- a/cmd/cue/cmd/eval.go
+++ b/cmd/cue/cmd/eval.go
@@ -72,7 +72,7 @@
 	cmd.Flags().BoolP(string(flagAll), "a", false,
 		"show optional and hidden fields")
 
-	cmd.Flags().StringArrayP(string(flagTags), "t", nil,
+	cmd.Flags().StringArrayP(string(flagInject), "t", nil,
 		"set the value of a tagged field")
 
 	// TODO: Option to include comments in output.
diff --git a/cmd/cue/cmd/export.go b/cmd/cue/cmd/export.go
index 1815778..b53ab3c 100644
--- a/cmd/cue/cmd/export.go
+++ b/cmd/cue/cmd/export.go
@@ -97,7 +97,7 @@
 
 	cmd.Flags().StringArrayP(string(flagExpression), "e", nil, "export this expression only")
 
-	cmd.Flags().StringArrayP(string(flagTags), "t", nil,
+	cmd.Flags().StringArrayP(string(flagInject), "t", nil,
 		"set the value of a tagged field")
 
 	return cmd
diff --git a/cmd/cue/cmd/flags.go b/cmd/cue/cmd/flags.go
index 43095e1..69d3af3 100644
--- a/cmd/cue/cmd/flags.go
+++ b/cmd/cue/cmd/flags.go
@@ -30,7 +30,7 @@
 	flagIgnore    flagName = "ignore"
 	flagSimplify  flagName = "simplify"
 	flagPackage   flagName = "package"
-	flagTags      flagName = "tags"
+	flagInject    flagName = "inject"
 
 	flagExpression flagName = "expression"
 	flagSchema     flagName = "schema"
diff --git a/cmd/cue/cmd/help.go b/cmd/cue/cmd/help.go
index 49584be..68e4d21 100644
--- a/cmd/cue/cmd/help.go
+++ b/cmd/cue/cmd/help.go
@@ -19,7 +19,7 @@
 )
 
 // TODO: intersperse the examples at the end of the texts in the
-// body of text to make things more concerte for the user early on?
+// body of text to make things more concrete for the user early on?
 // The current approach works will if users just print the text without
 // "more" or "less", in which case the examples show more prominently.
 // The user can then scroll up to get a more in-depth explanation. But is
@@ -30,6 +30,7 @@
 		inputsHelp,
 		flagsHelp,
 		filetypeHelp,
+		injectHelp,
 	}
 }
 
@@ -254,6 +255,51 @@
 `,
 }
 
+var injectHelp = &cobra.Command{
+	Use:   "injection",
+	Short: "inject values from the command line",
+	Long: `Many of the cue commands allow injecting values
+from the command line using the --inject/-t flag.
+
+The injection mechanism allows values to be injected into fields
+that are marked with a "tag" attribute. For any field of the form
+
+   field: x @tag(key)
+
+an "--inject key=value" flag will modify the field to
+
+   field: x & "value"
+
+By default, the injected value is treated as a string.
+Alternatively, the "type" option allows a value to be interpreted
+as an int, number, or bool. For instance, for a field
+
+   field: x @tag(key,type=int)
+
+the flag "-t key=2" modifies the field to
+
+   field: x & 2
+
+Valid values for type are "int", "number", "bool", and "string".
+
+A tag attribute can also define shorthand values, which can be
+injected into the fields without having to specify the key. For
+instance, for
+
+   environment: string @tag(env,short=prod|staging)
+
+"-t prod" sets the environment field to the value "prod". It is
+still possible to specify "-t env=prod" in this case.
+
+Use the usual CUE constraints to limit the possible values of a
+field. For instance
+
+   environment: "prod" | "staging" @tag(env,short=prod|staging)
+
+ensures the user may only specify "prod" or "staging".
+`,
+}
+
 // TODO: tags
 // - doc/nodoc
 // - attr/noattr
@@ -263,7 +309,4 @@
 // - textpb
 // - binpb
 
-// TODO: document
-// <tag>['='<value>]{'+'<tag>['='<value>]}':'
-
 // TODO: cue.mod help topic
diff --git a/cmd/cue/cmd/root.go b/cmd/cue/cmd/root.go
index 7a66c33..96bec80 100644
--- a/cmd/cue/cmd/root.go
+++ b/cmd/cue/cmd/root.go
@@ -254,7 +254,7 @@
 	if err != nil {
 		return nil, err
 	}
-	tags, err := cmd.cmd.Flags().GetStringArray(string(flagTags))
+	tags, err := cmd.cmd.Flags().GetStringArray(string(flagInject))
 	if err != nil {
 		return nil, err
 	}
@@ -303,7 +303,7 @@
 				if err != nil {
 					return err
 				}
-				tags, err = cmd.cmd.Flags().GetStringArray(string(flagTags))
+				tags, err = cmd.cmd.Flags().GetStringArray(string(flagInject))
 				if err != nil {
 					return err
 				}
diff --git a/cmd/cue/cmd/testdata/script/help_cmd.txt b/cmd/cue/cmd/testdata/script/help_cmd.txt
index a1165fb..3a2db1c 100644
--- a/cmd/cue/cmd/testdata/script/help_cmd.txt
+++ b/cmd/cue/cmd/testdata/script/help_cmd.txt
@@ -221,8 +221,8 @@
   hello       say hello to someone
 
 Flags:
-  -h, --help               help for cmd
-  -t, --tags stringArray   set the value of a tagged field
+  -h, --help                 help for cmd
+  -t, --inject stringArray   set the value of a tagged field
 
 Global Flags:
   -E, --all-errors   print all available errors
diff --git a/cmd/cue/cmd/vet.go b/cmd/cue/cmd/vet.go
index 12ea5a4..1c26f42 100644
--- a/cmd/cue/cmd/vet.go
+++ b/cmd/cue/cmd/vet.go
@@ -74,7 +74,7 @@
 	cmd.Flags().BoolP(string(flagConcrete), "c", false,
 		"require the evaluation to be concrete")
 
-	cmd.Flags().StringArrayP(string(flagTags), "t", nil,
+	cmd.Flags().StringArrayP(string(flagInject), "t", nil,
 		"set the value of a tagged field")
 
 	return cmd