Add command description + experimental warning

clicommand/tool_keygen.go

@@ -27,7 +27,20 @@ type KeygenConfig struct {
 
 var KeygenCommand = cli.Command{
 	Name:  "keygen",
-	Usage: "Generate a new key pair, used to sign and verify jobs",
+	Usage: "Generate a new JWS key pair, used for signing and verifying jobs in Buildkite",
+	Description: `Usage:
+
+    buildkite-agent tool keygen [options...]
+
+Description:
+
+This (experimental!) command generates a new JWS key pair, used for signing and verifying jobs in Buildkite.
+The key pair is written to two files, a private keyset and a public keyset. The private keyset should be used
+as for signing, and the public for verification. The keysets are written in JWKS format.
+
+For information about signing jobs in buildkite, see: <PUT A LINK HERE YA DINGO>
+
+For more information about JWS, see https://tools.ietf.org/html/rfc7515 and for information about JWKS, see https://tools.ietf.org/html/rfc7517`,
 	Flags: []cli.Flag{
 		cli.StringFlag{
 			Name:   "alg",
@@ -61,6 +74,8 @@ var KeygenCommand = cli.Command{
 		_, cfg, l, _, done := setupLoggerAndConfig[KeygenConfig](context.Background(), c)
 		defer done()
 
+		l.Warn("Pipeline signing is experimental and the user interface might change! Also it might not work, it might sign the pipeline only partially, or it might eat your pet dog. You have been warned!")
+
 		sigAlg := jwa.SignatureAlgorithm(cfg.Alg)
 
 		if !slices.Contains(ValidSigningAlgorithms, sigAlg) {