diff --git a/cmd/drone-agent/main.go b/cmd/drone-agent/main.go
index 28b75bb71..75aac17d9 100644
--- a/cmd/drone-agent/main.go
+++ b/cmd/drone-agent/main.go
@@ -40,12 +40,12 @@ func main() {
 		cli.StringFlag{
 			EnvVar: "DRONE_PASSWORD,DRONE_SECRET",
 			Name:   "password",
-			Usage:  "drone auth password",
+			Usage:  "server-agent shared password",
 		},
 		cli.BoolTFlag{
 			EnvVar: "DRONE_DEBUG",
 			Name:   "debug",
-			Usage:  "start the agent in debug mode",
+			Usage:  "enable agent debug mode",
 		},
 		cli.BoolFlag{
 			EnvVar: "DRONE_DEBUG_PRETTY",
@@ -60,36 +60,39 @@ func main() {
 		cli.StringFlag{
 			EnvVar: "DRONE_HOSTNAME,HOSTNAME",
 			Name:   "hostname",
+			Usage:  "agent hostname",
 		},
 		cli.StringFlag{
 			EnvVar: "DRONE_PLATFORM",
 			Name:   "platform",
+			Usage:  "restrict builds by platform conditions",
 			Value:  "linux/amd64",
 		},
 		cli.StringFlag{
 			EnvVar: "DRONE_FILTER",
 			Name:   "filter",
-			Usage:  "filter expression used to restrict builds by label",
+			Usage:  "filter expression to restrict builds by label",
 		},
 		cli.IntFlag{
 			EnvVar: "DRONE_MAX_PROCS",
 			Name:   "max-procs",
+			Usage:  "agent parallel builds",
 			Value:  1,
 		},
 		cli.BoolTFlag{
 			EnvVar: "DRONE_HEALTHCHECK",
 			Name:   "healthcheck",
-			Usage:  "enables the healthcheck endpoint",
+			Usage:  "enable healthcheck endpoint",
 		},
 		cli.DurationFlag{
 			EnvVar: "DRONE_KEEPALIVE_TIME",
 			Name:   "keepalive-time",
-			Usage:  "after a duration of this time if the agent doesn't see any activity it pings the server to see if the transport is still alive",
+			Usage:  "after a duration of this time of no activity, the agent pings the server to check if the transport is still alive",
 		},
 		cli.DurationFlag{
 			EnvVar: "DRONE_KEEPALIVE_TIMEOUT",
 			Name:   "keepalive-timeout",
-			Usage:  "after having pinged for keepalive check, the client waits for a duration of Timeout and if no activity is seen even after that the connection is closed.",
+			Usage:  "after pinging for a keepalive check, the agent waits for a duration of this time before closing the connection if no activity",
 			Value:  time.Second * 20,
 		},
 	}
diff --git a/cmd/drone-server/server.go b/cmd/drone-server/server.go
index a4efe2f52..7bb3fc9ce 100644
--- a/cmd/drone-server/server.go
+++ b/cmd/drone-server/server.go
@@ -38,12 +38,12 @@ var flags = []cli.Flag{
 	cli.BoolFlag{
 		EnvVar: "DRONE_DEBUG",
 		Name:   "debug",
-		Usage:  "start the server in debug mode",
+		Usage:  "enable server debug mode",
 	},
 	cli.StringFlag{
 		EnvVar: "DRONE_SERVER_HOST,DRONE_HOST",
 		Name:   "server-host",
-		Usage:  "server host",
+		Usage:  "server fully qualified url (<scheme>://<host>)",
 	},
 	cli.StringFlag{
 		EnvVar: "DRONE_SERVER_ADDR",
@@ -54,22 +54,22 @@ var flags = []cli.Flag{
 	cli.StringFlag{
 		EnvVar: "DRONE_SERVER_CERT",
 		Name:   "server-cert",
-		Usage:  "server ssl cert",
+		Usage:  "server ssl cert path",
 	},
 	cli.StringFlag{
 		EnvVar: "DRONE_SERVER_KEY",
 		Name:   "server-key",
-		Usage:  "server ssl key",
+		Usage:  "server ssl key path",
 	},
 	cli.BoolFlag{
 		EnvVar: "DRONE_LETS_ENCRYPT",
 		Name:   "lets-encrypt",
-		Usage:  "lets encrypt enabled",
+		Usage:  "enable let's encrypt",
 	},
 	cli.BoolFlag{
 		EnvVar: "DRONE_QUIC",
 		Name:   "quic",
-		Usage:  "start the server with quic enabled",
+		Usage:  "enable quic",
 	},
 	cli.StringFlag{
 		EnvVar: "DRONE_WWW",
@@ -90,7 +90,7 @@ var flags = []cli.Flag{
 	cli.BoolFlag{
 		EnvVar: "DRONE_OPEN",
 		Name:   "open",
-		Usage:  "open user registration",
+		Usage:  "enable open user registration",
 	},
 	cli.StringFlag{
 		EnvVar: "DRONE_REPO_CONFIG",
@@ -101,12 +101,13 @@ var flags = []cli.Flag{
 	cli.DurationFlag{
 		EnvVar: "DRONE_SESSION_EXPIRES",
 		Name:   "session-expires",
-		Usage:  "Set the session expiration time default 72h",
+		Usage:  "session expiration time",
 		Value:  time.Hour * 72,
 	},
 	cli.StringSliceFlag{
 		EnvVar: "DRONE_ESCALATE",
 		Name:   "escalate",
+		Usage:  "images to run in privileged mode",
 		Value: &cli.StringSlice{
 			"plugins/docker",
 			"plugins/gcr",
@@ -124,7 +125,7 @@ var flags = []cli.Flag{
 	cli.StringFlag{
 		EnvVar: "DRONE_AGENT_SECRET,DRONE_SECRET",
 		Name:   "agent-secret",
-		Usage:  "agent secret passcode",
+		Usage:  "server-agent shared password",
 	},
 	cli.StringFlag{
 		EnvVar: "DRONE_SECRET_ENDPOINT",
@@ -157,28 +158,34 @@ var flags = []cli.Flag{
 	// resource limit parameters
 	//
 	cli.Int64Flag{
-		Name:   "limit-mem-swap",
 		EnvVar: "DRONE_LIMIT_MEM_SWAP",
+		Name:   "limit-mem-swap",
+		Usage:  "maximum swappable memory allowed in bytes",
 	},
 	cli.Int64Flag{
-		Name:   "limit-mem",
 		EnvVar: "DRONE_LIMIT_MEM",
+		Name:   "limit-mem",
+		Usage:  "maximum memory allowed in bytes",
 	},
 	cli.Int64Flag{
-		Name:   "limit-shm-size",
 		EnvVar: "DRONE_LIMIT_SHM_SIZE",
+		Name:   "limit-shm-size",
+		Usage:  "docker compose /dev/shm allowed in bytes",
 	},
 	cli.Int64Flag{
-		Name:   "limit-cpu-quota",
 		EnvVar: "DRONE_LIMIT_CPU_QUOTA",
+		Name:   "limit-cpu-quota",
+		Usage:  "impose a cpu quota",
 	},
 	cli.Int64Flag{
-		Name:   "limit-cpu-shares",
 		EnvVar: "DRONE_LIMIT_CPU_SHARES",
+		Name:   "limit-cpu-shares",
+		Usage:  "change the cpu shares",
 	},
 	cli.StringFlag{
-		Name:   "limit-cpu-set",
 		EnvVar: "DRONE_LIMIT_CPU_SET",
+		Name:   "limit-cpu-set",
+		Usage:  "set the cpus allowed to execute containers",
 	},
 	//
 	// remote parameters