docs: document --flutter-version=fvm and =system

[eseidel]

Status

HOLD — this documents a feature that has not shipped yet. It should merge only after shorebirdtech/shorebird#3932 lands and is in a released CLI.

Description

Adds a "Match the Flutter version you already use" section to getting-started/flutter-version.mdx, covering the two --flutter-version aliases added in shorebirdtech/shorebird#3932:

• --flutter-version=fvm — uses the version fvm resolves for the project (from its .fvmrc).
• --flutter-version=system — uses the version reported by the flutter on your PATH.

The section makes the key point explicit, since it's the thing users are most likely to get wrong: Shorebird asks that Flutter which version it is, then builds with Shorebird's fork at the same version. It does not build with your fvm or system Flutter install, so the version still has to be one Shorebird supports, and patches are still built with the version used by the release.

Also notes that --flutter-version=fvm requires fvm on PATH and runs fvm flutter --version from the project directory.

Context: shorebirdtech/shorebird#1385 asked for fvm support "and/or at least docs on how they're supposed to work together" — this is the docs half.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SQV4ay9pqj2NUBhw72dLW8

---

Generated by Claude Code

[AbhishekDoshi26]

Reviewed against what actually shipped in shorebirdtech/shorebird#3932. The core explanation on this page is correct and is the thing users most need, but the HOLD still applies, and one claim about how fvm resolution works does not match the merged implementation.

I've pushed two commits to this branch: main merged in (it was 24 commits behind), and the cspell fix described below. CI should be green now.

The HOLD is still active: merged is not released

The description gates this on shorebirdtech/shorebird#3932 landing and being in a released CLI. Only the first half is true today:

shorebird#3932 merged	2026-09-17 17:23 UTC, as dea22a5
Latest CLI release	v1.6.122, published 2026-09-16 15:59 UTC
compare/v1.6.122...dea22a5	status: ahead, ahead_by: 1

So the release tag does not contain the commit. The feature is on main but in nobody's hands.

If this merges before v1.6.123 ships, a reader who copies the command gets the alias passed straight through to resolveFlutterRevision, which fails with:

Version fvm not found. Please open an issue to request a new version.
Use `shorebird flutter versions list` to list available versions.

That's a rough landing for someone who just read the docs telling them to type it. Happy to watch for the release and ping this PR when the tag actually contains dea22a5.

What I verified as correct

The paragraph at lines 123-126 is the most load-bearing part of the section, and it holds up against the merged code:

• system really does read the flutter on PATH. getSystemVersion() runs with useVendedFlutter: false. Worth noting this was exactly the bug in the earlier #3238 attempt, where _resolveExecutable rewrote flutter to Shorebird's own binary and made the flag a no-op. This PR's wording describes the fixed behavior.
• "It does not build with your fvm or system Flutter install" is right. The reported version goes through the normal version-to-revision lookup, so the build uses Shorebird's fork at that version.
• "the version has to be one Shorebird supports" is right, and #3932 went a little beyond its original scope to make it true: assertArgsAreValid now resolves the alias, so the minimumFlutterVersion check applies to fvm/system instead of silently skipping.
• --flutter-version is still release-only. patch_command.dart has no such option, so the existing note above this section stays accurate.

Spell-check (fixed on this branch)

fvmrc was flagged at flutter-version.mdx:116:60, and it was the only red check. I added it to the alphabetical words: list in .cspell.yaml:

  - frontmatter
  - fvmrc
  - gallego

fvm on its own already passes via the shared allowed dictionary, so only fvmrc needed adding. This mirrors what #3932 did to cspell.config.yaml in the shorebird repo. Verified locally: cspell, Vale, prettier, the component-label linter, and a full astro build with link validation all pass.

Still needs your attention

The :::note at lines 130-131 describes the fallback path as though it were the normal one, and omits the part users will actually feel. Details in the inline comment.

One optional addition: on success the CLI prints Using Flutter 3.32.4, as reported by `flutter --version`. A sentence pointing at that line would let users confirm the alias resolved to what they expected, which is handy when an .fvmrc isn't where they thought it was.

[AbhishekDoshi26]

This describes the fallback, not the normal path, and it leaves out the part users will actually notice.

What getFvmVersion() does in the merged #3932:

1. Runs fvm api project --path <root> first. Its comment is explicit that this "reads the project's .fvmrc without touching the Flutter install, so it answers immediately and can't trigger a download."
2. If the pinned value matches ^\d+\.\d+\.\d+$, it returns right there. fvm flutter --version never runs. This is the common case, a project pinned to a version number.
3. fvm flutter --version runs only when the project pins a channel (stable) or a fork ref, or when fvm is too old to have an api command.

Why it matters: step 3 is the expensive path. From the implementation comment, "That can install Flutter first, which is slow and prints nothing while it runs, so we say what we're waiting on." The CLI prints a progress message specifically because of this. Someone whose .fvmrc pins stable will sit through a silent multi-minute Flutter download, and right now the docs give no warning while describing that slow path as normal.

Fix:

:::note

`--flutter-version=fvm` requires `fvm` on your `PATH`. Shorebird asks fvm for the
version your project pins, which it reads from `.fvmrc` without running Flutter.

If your project pins a channel (like `stable`) or a fork instead of a version
number, Shorebird has to ask that Flutter which version it is, which means fvm
may download and install it first. That can take several minutes the first time.

:::

[AbhishekDoshi26]

Nit: the :::note about 20 lines above already says "Patches will always be built with the version of Flutter used by the release." This sentence is carrying it a second time.

Fix: trim the tail so the sentence ends on the point unique to this section:

Flutter install, so the usual rules still apply: the version has to be one
Shorebird supports.

[AbhishekDoshi26]

Optional, and only relevant once this is unblocked: it may be worth a sentence noting that these aliases need a CLI that has them.

Everything else on this page works on any recent CLI, so a reader on v1.6.122 who hits Version fvm not found has no way to tell from the page that their CLI is simply too old. A short "requires Shorebird vX.Y.Z or later" line, filled in once the release ships, would close that gap. The version table above sets the precedent for that style.