From cf93c3417252df08f940a0366c6a3bbac53492d6 Mon Sep 17 00:00:00 2001
From: david-fraley <67079030+david-fraley@users.noreply.github.com>
Date: Tue, 28 Oct 2025 10:15:57 -0500
Subject: [PATCH] docs: update coder_token_lifetime description to include
 units and examples (#20516)

---
 cli/testdata/coder_tokens_create_--help.golden | 4 +++-
 cli/tokens.go                                  | 2 +-
 docs/reference/cli/tokens_create.md            | 2 +-
 3 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/cli/testdata/coder_tokens_create_--help.golden b/cli/testdata/coder_tokens_create_--help.golden
index 6db7a07a27..19e9beac20 100644
--- a/cli/testdata/coder_tokens_create_--help.golden
+++ b/cli/testdata/coder_tokens_create_--help.golden
@@ -10,7 +10,9 @@ OPTIONS:
           Repeatable allow-list entry (<type>:<uuid>, e.g. workspace:1234-...).
 
       --lifetime string, $CODER_TOKEN_LIFETIME
-          Specify a duration for the lifetime of the token.
+          Duration for the token lifetime. Supports standard Go duration units
+          (ns, us, ms, s, m, h) plus d (days) and y (years). Examples: 8h, 30d,
+          1y, 1d12h30m.
 
   -n, --name string, $CODER_TOKEN_NAME
           Specify a human-readable name.
diff --git a/cli/tokens.go b/cli/tokens.go
index 1c1bcd78a2..9316f5de14 100644
--- a/cli/tokens.go
+++ b/cli/tokens.go
@@ -123,7 +123,7 @@ func (r *RootCmd) createToken() *serpent.Command {
 		{
 			Flag:        "lifetime",
 			Env:         "CODER_TOKEN_LIFETIME",
-			Description: "Specify a duration for the lifetime of the token.",
+			Description: "Duration for the token lifetime. Supports standard Go duration units (ns, us, ms, s, m, h) plus d (days) and y (years). Examples: 8h, 30d, 1y, 1d12h30m.",
 			Value:       serpent.StringOf(&tokenLifetime),
 		},
 		{
diff --git a/docs/reference/cli/tokens_create.md b/docs/reference/cli/tokens_create.md
index d5dd916a46..b15e58cd13 100644
--- a/docs/reference/cli/tokens_create.md
+++ b/docs/reference/cli/tokens_create.md
@@ -18,7 +18,7 @@ coder tokens create [flags]
 | Type        | <code>string</code>                |
 | Environment | <code>$CODER_TOKEN_LIFETIME</code> |
 
-Specify a duration for the lifetime of the token.
+Duration for the token lifetime. Supports standard Go duration units (ns, us, ms, s, m, h) plus d (days) and y (years). Examples: 8h, 30d, 1y, 1d12h30m.
 
 ### -n, --name