Skip to content

docs(update): name the lock holder before the upgrade, not after #856

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ffroliva merged 2 commits into from
Sep 17, 2026
Merged

docs(update): name the lock holder before the upgrade, not after #856

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
73447d8
docs(update): name the lock holder before the upgrade, not after
ffroliva Sep 16, 2026
91ff33d
docs(update): distinguish the benign launcher lock, and warn where th…
ffroliva Sep 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions docs/MCP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -356,6 +356,12 @@ unauthenticated, which is the local single-user default.
> `gflow serve` — it currently runs the MCP/SSE server only. See the
> [CHANGELOG](../CHANGELOG.md) for the roadmap.

> **However you register it, that server then gates your upgrades.** Every client
> above starts a long-lived `gflow mcp run` — one per session — and on Windows it
> holds the install open, so a package manager can abort part-way through
> `gflow update` and leave the environment broken. Stop the servers first:
> [USAGE § `gflow update`](USAGE.md#gflow-update).

---

## 5. Security & Anti-Bot Mitigations
Expand Down
28 changes: 25 additions & 3 deletions docs/USAGE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1455,6 +1455,7 @@ that privacy setting, so missing names are expected, not a defect.
## `gflow update`

Upgrade gflow-cli in place, through the package manager that installed it.
**Stop every other `gflow` process first** — see below.

```text
gflow update [--check] [--json]
Expand Down Expand Up @@ -1519,9 +1520,30 @@ points at the venv's python — so `gflow update` reports it as upgraded with a
note quoting the manager's exit code; the next update from another shell
refreshes the launcher.

Restart any running `gflow serve` / MCP server afterwards; a long-lived process
keeps the old code until it restarts. There is deliberately no MCP twin of this
command: a server must not replace its own code underneath itself.
**Stop every other `gflow` process BEFORE you upgrade — not after.** The launcher
lock just above is the benign case: it is the `gflow.exe` *you* are running, and
the upgrade lands anyway. A **different** gflow, holding the install's contents
open, is not — there the manager can abort part-way and leave the environment
broken. The holder reported so far is **`gflow mcp run`**: an editor with gflow
registered as an MCP server starts one per session, and they outlive the command
that started them. Reported with a reproduction in
[#848](https://github.com/ffroliva/gflow-cli/issues/848#issuecomment-5704903340):
`uv tool install --force` failed with *"Access is denied"* on
`…\uv\tools\gflow-cli\Scripts` and left the install answering
`No module named 'gflow_cli'` until those processes were stopped and the install
re-run.

Close the editor sessions (or stop the servers) first. On Windows,
`tasklist | findstr gflow` lists image names only — a server registered as
`uv run gflow …` shows up as `uv.exe`, not `gflow.exe`; elsewhere
`pgrep -fa gflow` prints the command line it matched, so you can see what you
are about to stop. `gflow update` cannot run this check for you: it is itself
one of those processes. If an upgrade does abort anyway, the exit-11 **forced
reinstall** above is the repair — run it from a shell with no gflow running.

Restart any running `gflow serve` / MCP server afterwards too; a long-lived
process keeps the old code until it restarts. There is deliberately no MCP twin
of this command: a server must not replace its own code underneath itself.

Every command also prints an **update banner** on stderr (a one-line notice when
stderr is not a terminal) when a newer release is known — see
Expand Down
6 changes: 6 additions & 0 deletions website/docs/MCP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -356,6 +356,12 @@ unauthenticated, which is the local single-user default.
> `gflow serve` — it currently runs the MCP/SSE server only. See the
> [CHANGELOG](../CHANGELOG.md) for the roadmap.

> **However you register it, that server then gates your upgrades.** Every client
> above starts a long-lived `gflow mcp run` — one per session — and on Windows it
> holds the install open, so a package manager can abort part-way through
> `gflow update` and leave the environment broken. Stop the servers first:
> [USAGE § `gflow update`](USAGE.md#gflow-update).

---

## 5. Security & Anti-Bot Mitigations
Expand Down
28 changes: 25 additions & 3 deletions website/docs/USAGE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1455,6 +1455,7 @@ that privacy setting, so missing names are expected, not a defect.
## `gflow update`

Upgrade gflow-cli in place, through the package manager that installed it.
**Stop every other `gflow` process first** — see below.

```text
gflow update [--check] [--json]
Expand Down Expand Up @@ -1519,9 +1520,30 @@ points at the venv's python — so `gflow update` reports it as upgraded with a
note quoting the manager's exit code; the next update from another shell
refreshes the launcher.

Restart any running `gflow serve` / MCP server afterwards; a long-lived process
keeps the old code until it restarts. There is deliberately no MCP twin of this
command: a server must not replace its own code underneath itself.
**Stop every other `gflow` process BEFORE you upgrade — not after.** The launcher
lock just above is the benign case: it is the `gflow.exe` *you* are running, and
the upgrade lands anyway. A **different** gflow, holding the install's contents
open, is not — there the manager can abort part-way and leave the environment
broken. The holder reported so far is **`gflow mcp run`**: an editor with gflow
registered as an MCP server starts one per session, and they outlive the command
that started them. Reported with a reproduction in
[#848](https://github.com/ffroliva/gflow-cli/issues/848#issuecomment-5704903340):
`uv tool install --force` failed with *"Access is denied"* on
`…\uv\tools\gflow-cli\Scripts` and left the install answering
`No module named 'gflow_cli'` until those processes were stopped and the install
re-run.

Close the editor sessions (or stop the servers) first. On Windows,
`tasklist | findstr gflow` lists image names only — a server registered as
`uv run gflow …` shows up as `uv.exe`, not `gflow.exe`; elsewhere
`pgrep -fa gflow` prints the command line it matched, so you can see what you
are about to stop. `gflow update` cannot run this check for you: it is itself
one of those processes. If an upgrade does abort anyway, the exit-11 **forced
reinstall** above is the repair — run it from a shell with no gflow running.

Restart any running `gflow serve` / MCP server afterwards too; a long-lived
process keeps the old code until it restarts. There is deliberately no MCP twin
of this command: a server must not replace its own code underneath itself.

Every command also prints an **update banner** on stderr (a one-line notice when
stderr is not a terminal) when a newer release is known — see
Expand Down