consolidate docs

go/cmd/vtctld/cli/cli.go

@@ -28,8 +28,24 @@ import (
 var (
 	ts   *topo.Server
 	Main = &cobra.Command{
-		Use:     "vtctld",
-		Short:   "The Vitess cluster management daemon.",
+		Use:   "vtctld",
+		Short: "The Vitess cluster management daemon.",
+		Long: `vtctld provides web and gRPC interfaces to manage a single Vitess cluster.
+It is usually the first Vitess component to be started after a valid global topology service has been created.
+
+For the last several releases, vtctld has been transitioning to a newer gRPC service for well-typed cluster management requests.
+This is **required** to use programs such as vtadmin and vtctldclient, and The old API and service are deprecated and will be removed in a future release.
+To enable this newer service, include "grpc-vtctld" in the --service_map argument.
+This is demonstrated in the example usage below.`,
+		Example: `vtctld \
+	--topo_implementation etcd2 \
+	--topo_global_server_address localhost:2379 \
+	--topo_global_root /vitess/ \
+	--service_map 'grpc-vtctl,grpc-vtctld' \
+	--backup_storage_implementation file \
+	--file_backup_storage_root $VTDATAROOT/backups \
+	--port 15000 \
+	--grpc_port 15999`,
 		Args:    cobra.NoArgs,
 		Version: servenv.AppVersion.String(),
 		PreRunE: servenv.CobraPreRunE,

go/cmd/vtorc/cli/cli.go

@@ -31,8 +31,18 @@ import (
 var (
 	configFile string
 	Main       = &cobra.Command{
-		Use:     "vtorc",
-		Short:   "VTOrc is the automated fault detection and repair tool in Vitess.",
+		Use:   "vtorc",
+		Short: "VTOrc is the automated fault detection and repair tool in Vitess.",
+		Example: `vtorc \
+	--topo_implementation etcd2 \
+	--topo_global_server_address localhost:2379 \
+	--topo_global_root /vitess/global \
+	--log_dir $VTDATAROOT/tmp \
+	--port 15000 \
+	--recovery-period-block-duration "10m" \
+	--instance-poll-time "1s" \
+	--topo-information-refresh-duration "30s" \
+	--alsologtostderr`,
 		Args:    cobra.NoArgs,
 		Version: servenv.AppVersion.String(),
 		PreRunE: servenv.CobraPreRunE,

go/flags/endtoend/vtctld.txt

@@ -1,8 +1,25 @@
-The Vitess cluster management daemon.
+vtctld provides web and gRPC interfaces to manage a single Vitess cluster.
+It is usually the first Vitess component to be started after a valid global topology service has been created.
+
+For the last several releases, vtctld has been transitioning to a newer gRPC service for well-typed cluster management requests.
+This is **required** to use programs such as vtadmin and vtctldclient, and The old API and service are deprecated and will be removed in a future release.
+To enable this newer service, include "grpc-vtctld" in the --service_map argument.
+This is demonstrated in the example usage below.
 
 Usage:
   vtctld [flags]
 
+Examples:
+vtctld \
+	--topo_implementation etcd2 \
+	--topo_global_server_address localhost:2379 \
+	--topo_global_root /vitess/ \
+	--service_map 'grpc-vtctl,grpc-vtctld' \
+	--backup_storage_implementation file \
+	--file_backup_storage_root $VTDATAROOT/backups \
+	--port 15000 \
+	--grpc_port 15999
+
 Flags:
       --action_timeout duration                                          time to wait for an action before resorting to force (default 1m0s)
       --alsologtostderr                                                  log to standard error as well as files

go/flags/endtoend/vtorc.txt

@@ -3,6 +3,18 @@ VTOrc is the automated fault detection and repair tool in Vitess.
 Usage:
   vtorc [flags]
 
+Examples:
+vtorc \
+	--topo_implementation etcd2 \
+	--topo_global_server_address localhost:2379 \
+	--topo_global_root /vitess/global \
+	--log_dir $VTDATAROOT/tmp \
+	--port 15000 \
+	--recovery-period-block-duration "10m" \
+	--instance-poll-time "1s" \
+	--topo-information-refresh-duration "30s" \
+	--alsologtostderr
+
 Flags:
       --allow-emergency-reparent                                    Whether VTOrc should be allowed to run emergency reparent operation when it detects a dead primary (default true)
       --alsologtostderr                                             log to standard error as well as files