From c5a997cbdba994835a38b9c49e4eee800e56040b Mon Sep 17 00:00:00 2001
From: Jordan Pittman <jordan@cryptica.me>
Date: Thu, 19 Jun 2025 14:52:47 -0400
Subject: [PATCH] Document `--watch=always` in the CLI (#18337)

Closes https://github.com/tailwindlabs/tailwindcss.com/issues/1835

We had this in v3 as an undocumented option. We still have it in v4 but
it's not documented under the CLI usage but should be. This PR adds
this.

**before**
<img width="803" alt="Screenshot 2025-06-18 at 09 41 40"
src="https://github.com/user-attachments/assets/c3becf11-e31d-4355-9d23-bddd0b2fc4a6"
/>

**after**
<img width="1152" alt="Screenshot 2025-06-18 at 09 41 20"
src="https://github.com/user-attachments/assets/4f61a156-680d-4f39-b92d-7f0f63270689"
/>
---
 CHANGELOG.md                                          | 1 +
 packages/@tailwindcss-cli/src/commands/build/index.ts | 4 +++-
 packages/@tailwindcss-cli/src/commands/help/index.ts  | 6 +++++-
 packages/@tailwindcss-cli/src/utils/args.ts           | 1 +
 4 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6b1ffcd5d..a89bca360 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Add heuristic to skip candidate migrations inside `emit(…)` ([#18330](https://github.com/tailwindlabs/tailwindcss/pull/18330))
 - Extract candidates with variants in Clojure/ClojureScript keywords ([#18338](https://github.com/tailwindlabs/tailwindcss/pull/18338))
+- Document `--watch=always` in the CLI's usage ([#18337](https://github.com/tailwindlabs/tailwindcss/pull/18337))
 
 ## [4.1.10] - 2025-06-11
 
diff --git a/packages/@tailwindcss-cli/src/commands/build/index.ts b/packages/@tailwindcss-cli/src/commands/build/index.ts
index 8babb5654..206bf27fb 100644
--- a/packages/@tailwindcss-cli/src/commands/build/index.ts
+++ b/packages/@tailwindcss-cli/src/commands/build/index.ts
@@ -42,8 +42,10 @@ export function options() {
     },
     '--watch': {
       type: 'boolean | string',
-      description: 'Watch for changes and rebuild as needed',
+      description:
+        'Watch for changes and rebuild as needed, and use `always` to keep watching when stdin is closed',
       alias: '-w',
+      values: ['always'],
     },
     '--minify': {
       type: 'boolean',
diff --git a/packages/@tailwindcss-cli/src/commands/help/index.ts b/packages/@tailwindcss-cli/src/commands/help/index.ts
index 20ee78208..a28132062 100644
--- a/packages/@tailwindcss-cli/src/commands/help/index.ts
+++ b/packages/@tailwindcss-cli/src/commands/help/index.ts
@@ -112,7 +112,11 @@ export function help({
     // `alias` followed by `, ` and followed by the `flag`.
     let maxOptionLength = 0
 
-    for (let [flag, { alias }] of Object.entries(options)) {
+    for (let [flag, { alias, values }] of Object.entries(options)) {
+      if (values?.length) {
+        flag += `[=${values.join(', ')}]`
+      }
+
       // The option string, which is the combination of the alias and the flag
       // but already properly indented based on the other aliases to ensure
       // everything is aligned properly.
diff --git a/packages/@tailwindcss-cli/src/utils/args.ts b/packages/@tailwindcss-cli/src/utils/args.ts
index 1e4e153b8..1306aa2f2 100644
--- a/packages/@tailwindcss-cli/src/utils/args.ts
+++ b/packages/@tailwindcss-cli/src/utils/args.ts
@@ -7,6 +7,7 @@ export type Arg = {
     description: string
     alias?: `-${string}`
     default?: Types[keyof Types]
+    values?: string[]
   }
 }