From 559dbfac7fd7d1eb5ce4c6373c9e265bc5948b18 Mon Sep 17 00:00:00 2001
From: Matthew Phillips <matthewphillips@cloudflare.com>
Date: Wed, 8 Jul 2026 16:22:56 -0400
Subject: [PATCH 1/3] Document astro dev --no-lock flag

---
 src/content/docs/en/reference/cli-reference.mdx | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx
index 154aaf7a9ae94..6cabc19bc1ec6 100644
--- a/src/content/docs/en/reference/cli-reference.mdx
+++ b/src/content/docs/en/reference/cli-reference.mdx
@@ -212,6 +212,18 @@ astro dev --background --force
 
 <ReadMore>See [Background mode for AI coding agents](/en/guides/build-with-ai/#background-mode) for more about automatic agent detection and the health endpoint.</ReadMore>
 
+#### `--no-lock`
+
+<p><Since v="7.1.0" /></p>
+
+Starts the dev server without checking or writing the lock file used to detect other running dev servers. This allows a new dev server to start alongside one that's already running for the same project, instead of erroring.
+
+```shell
+astro dev --no-lock --port 4322
+```
+
+The new server is not tracked by `astro dev stop`, `astro dev status`, or `astro dev logs`. `--no-lock` cannot be combined with `--background` (including when background mode is triggered automatically for an AI coding agent) or `--force`, since both rely on the lock file.
+
 <h3>Subcommands</h3>
 
 <p><Since v="7.0.0" /></p>

From 0c3f83c94084bc71889128b31c0fd36440c8bd0c Mon Sep 17 00:00:00 2001
From: Matthew Phillips <matthewphillips@cloudflare.com>
Date: Thu, 9 Jul 2026 11:46:53 -0400
Subject: [PATCH 2/3] Add --no-lock to astro dev help output listing

---
 src/content/docs/en/reference/cli-reference.mdx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx
index 6cabc19bc1ec6..5d1ab7bfdc0af 100644
--- a/src/content/docs/en/reference/cli-reference.mdx
+++ b/src/content/docs/en/reference/cli-reference.mdx
@@ -125,6 +125,7 @@ Flags
 --host <custom-address>  Expose on a network IP address at <custom-address>
                --open  Automatically open the app in the browser on server start
               --force  Clear the content layer cache, forcing a full rebuild.
+            --no-lock  Start the dev server even if another one is already running, without checking or writing the lock file.
           --help (-h)  See all available flags.
 ```
 

From 49098fcbcf9087d9b1f0be0e164103c809a5212c Mon Sep 17 00:00:00 2001
From: Matthew Phillips <matthewphillips@cloudflare.com>
Date: Fri, 10 Jul 2026 08:10:18 -0400
Subject: [PATCH 3/3] Update src/content/docs/en/reference/cli-reference.mdx

Co-authored-by: Armand Philippot <git@armand.philippot.eu>
---
 src/content/docs/en/reference/cli-reference.mdx | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/content/docs/en/reference/cli-reference.mdx b/src/content/docs/en/reference/cli-reference.mdx
index 5d1ab7bfdc0af..d7347750533dc 100644
--- a/src/content/docs/en/reference/cli-reference.mdx
+++ b/src/content/docs/en/reference/cli-reference.mdx
@@ -223,7 +223,9 @@ Starts the dev server without checking or writing the lock file used to detect o
 astro dev --no-lock --port 4322
 ```
 
-The new server is not tracked by `astro dev stop`, `astro dev status`, or `astro dev logs`. `--no-lock` cannot be combined with `--background` (including when background mode is triggered automatically for an AI coding agent) or `--force`, since both rely on the lock file.
+The new server is not tracked by `astro dev stop`, `astro dev status`, or `astro dev logs`.
+
+When combined with `--background` (including when triggered by an AI coding agent) or `--force`, an error is throwned, as both rely on the lock file.
 
 <h3>Subcommands</h3>