From 10aed927f9318ad87f3e3ae6b86fd052dfeab7e8 Mon Sep 17 00:00:00 2001
From: Zac Bergquist <zac.bergquist@goteleport.com>
Date: Mon, 10 Oct 2022 16:28:01 -0600
Subject: [PATCH] docs: add CLI section for tctl alert create (#16976)

---
 docs/pages/reference/cli.mdx      | 38 +++++++++++++++++++++++++++++++
 tool/tctl/common/alert_command.go |  2 +-
 2 files changed, 39 insertions(+), 1 deletion(-)

diff --git a/docs/pages/reference/cli.mdx b/docs/pages/reference/cli.mdx
index c7071c8a02f..369a1322702 100644
--- a/docs/pages/reference/cli.mdx
+++ b/docs/pages/reference/cli.mdx
@@ -1973,6 +1973,44 @@ $ tctl status \
     --identity=identity.pem
 ```
 
+### tctl alerts create
+
+Creates cluster alerts. Cluster alerts can be displayed to Teleport users
+in the web UI or upon logging via `tsh`.
+
+```code
+$ tctl alerts create [<flags>] <message>
+```
+
+#### Arguments
+
+- `<message>`: The message for the alert to display
+
+#### Flags
+
+| Name | Default Value(s) | Allowed Value(s) | Description |
+| - | - | - | - |
+| `--severity` | `low` | `low`, `medium`, `high` | Alert severity |
+| `--ttl` | none | Any duration | Optional expiry for alert (alert does not expire if no TTL is specified) |
+| `--labels` | none | any | A list of labels to attach to the alert. |
+
+While any labels can be applied to an alert, there are several internal labels that can be used to configure
+the behavior of alerts:
+
+- `teleport.internal/alert-on-login: yes`: ensures that the alert is displayed to users upon login
+- `teleport.internal/alert-permit-all: yes`: ensures that the alert is displayed to all users
+
+If no labels are specified, `tctl` will automatically add both of these labels.
+
+#### Examples
+
+```code
+$ tctl alerts create \
+    --severity=low \
+    --ttl=4h \
+    "The system is under maintenance, functionality may be limited."
+```
+
 ### tctl top
 
 Reports diagnostic information.
diff --git a/tool/tctl/common/alert_command.go b/tool/tctl/common/alert_command.go
index 0b363937eee..f26d843f3be 100644
--- a/tool/tctl/common/alert_command.go
+++ b/tool/tctl/common/alert_command.go
@@ -62,7 +62,7 @@ func (c *AlertCommand) Initialize(app *kingpin.Application, config *service.Conf
 	c.alertCreate.Arg("message", "Alert body message").Required().StringVar(&c.message)
 	c.alertCreate.Flag("ttl", "Time duration after which the alert expires.").DurationVar(&c.ttl)
 	c.alertCreate.Flag("severity", "Severity of the alert (low, medium, or high)").Default("low").EnumVar(&c.severity, "low", "medium", "high")
-	c.alertCreate.Flag("labels", labelHelp).StringVar(&c.labels)
+	c.alertCreate.Flag("labels", "List of labels to attach to the alert. For example: key1=value1,key2=value2").StringVar(&c.labels)
 }
 
 // TryRun takes the CLI command as an argument (like "alerts ls") and executes it.