### Integration Example: List Installed Versions

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/json-api.md

Example of how to list all installed Flutter SDK versions using the FVM API and `jq`.

```bash
# List installed versions
fvm api list --compress | jq -r '.versions[].name'
```

--------------------------------

### Install Flutter SDK version

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/basic-commands.mdx

Downloads and caches a specific Flutter SDK version. Runs setup by default.

```bash
fvm install [version] [options]
```

```bash
# Install with setup (default behavior)
fvm install 3.19.0

# Skip setup for faster caching
fvm install 3.19.0 --no-setup

# Install from project config
fvm install
```

--------------------------------

### Test Installation Logic

Source: https://github.com/leoafarias/fvm/blob/main/scripts/README.md

Run these commands to validate installation behavior, including root user warnings.

```bash
# Test as regular user
./scripts/test-install.sh

# Test all scenarios (requires root)
sudo ./scripts/test-install.sh
```

--------------------------------

### fvm install

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/basic-commands.mdx

Downloads and caches a specified Flutter SDK version. By default, it runs setup to ensure the SDK is ready for use.

```APIDOC
## install

### Description
Downloads and caches a Flutter SDK version for future use. Runs setup by default to ensure SDK is ready to use.

### Method
CLI

### Endpoint
fvm install [version] [options]

### Parameters
#### Arguments
- **version** (string) - Optional - Flutter SDK version to install. If omitted, installs version from project configuration.

#### Options
- **-s, --setup** - Downloads SDK dependencies after install (default: true)
- **--no-setup** - Skip downloading SDK dependencies for faster caching
- **--skip-pub-get** - Skips dependency resolution

### Aliases
- `fvm i` - Short form

### Request Example
```bash
fvm install 3.19.0
fvm install 3.19.0 --no-setup
fvm install
```

### Output
Shows installed SDK versions and their paths.
```

--------------------------------

### Install Dependencies

Source: https://github.com/leoafarias/fvm/blob/main/AGENTS.md

Use this command to install project dependencies.

```bash
dart pub get
```

--------------------------------

### Integration Example: Get Current Project Version

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/json-api.md

Example of how to get the current project's pinned Flutter SDK version using the FVM API and `jq`.

```bash
# Get current project version
fvm api project --compress | jq -r '.project.pinnedVersion'
```

--------------------------------

### Install FVM Versions

Source: https://github.com/leoafarias/fvm/blob/main/internal/migration-manual-test-plan.md

Install the latest stable, a specific release version (e.g., 3.xx.y), and the latest beta version of FVM. These installations will populate the cache.

```bash
fvm install stable
fvm install 3.xx.y
fvm install beta
```

--------------------------------

### Spawn Command Example

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/running-flutter.mdx

An example of using the 'spawn' command to run 'flutter analyze' on the 'master' channel.

```bash
fvm spawn master analyze
```

--------------------------------

### Install FVM Latest Version (Script)

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/getting-started/installation.mdx

Installs the latest version of FVM using the official install script. This is the recommended method for most users.

```bash
curl -fsSL https://fvm.app/install.sh | bash
```

--------------------------------

### Check Versions of Git, Dart, and FVM

Source: https://github.com/leoafarias/fvm/blob/main/internal/migration-manual-test-plan.md

Verify that git, dart, and fvm are installed and accessible in the environment. This is a preflight check before starting the migration test.

```bash
git --version
 dart --version
 fvm --version
```

--------------------------------

### Install and use a Flutter fork version

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/basic-commands.mdx

Installs and switches to a Flutter SDK version from a configured fork. This allows using custom or specific branches of Flutter.

```bash
fvm install mycompany/stable
fvm install mycompany/3.19.0
fvm use mycompany/stable
```

--------------------------------

### Setup Integration Tests

Source: https://github.com/leoafarias/fvm/blob/main/AGENTS.md

Run this command to set up Flutter for integration tests.

```bash
dart run grinder test-setup
```

--------------------------------

### Install and Use FVM

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/getting-started/overview.md

Install FVM using Homebrew, then set a specific Flutter version for your project and run Flutter commands through FVM.

```bash
# Install FVM
brew install fvm

# Set Flutter version for a project
cd my_project
fvm use 3.19.0

# Run Flutter commands
fvm flutter doctor
```

--------------------------------

### GET fvm api list

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/json-api.md

Lists all installed Flutter SDK versions available locally.

```APIDOC
## GET fvm api list

### Description
Lists the installed Flutter SDK versions available locally.

### Method
GET

### Endpoint
fvm api list

### Parameters
#### Query Parameters
- **--compress** (flag) - Optional - Outputs JSON with no whitespace.
- **--skip-size-calculation** (flag) - Optional - Skips calculating the size of cached versions.

### Response
#### Success Response (200)
- **size** (string) - Total size of cached versions.
- **versions** (array) - List of installed Flutter SDK versions.

#### Response Example
{
  "size": "922.50 MB",
  "versions": [
    {
      "name": "3.19.0",
      "directory": "/path/to/fvm/versions/3.19.0",
      "isSetup": true
    }
  ]
}
```

--------------------------------

### Install FVM Specific Version (Script)

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/getting-started/installation.mdx

Installs a specific version of FVM by providing the version number to the install script. Replace `<version>` with the desired FVM version.

```bash
curl -fsSL https://fvm.app/install.sh | bash -s -- <version>
```

--------------------------------

### Install Specific FVM Version

Source: https://github.com/leoafarias/fvm/blob/main/scripts/install.md

Pass a version argument to the installation script to install a specific release of FVM.

```bash
curl -fsSL https://fvm.app/install.sh | bash -s 3.2.1
```

--------------------------------

### Troubleshoot FVM issues

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/workflows.mdx

Commands for verifying environment setup, reinstalling versions, and resetting global configuration.

```bash
# Check environment
fvm doctor

# Verify project setup
cd myproject
fvm doctor

# Force reinstall
fvm remove 3.19.0
fvm install 3.19.0

# Reset global config
fvm global --unlink
```

--------------------------------

### List Installed SDK Versions Payload

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/json-api.md

Example JSON payload for the `fvm api list` command, showing details of installed Flutter SDK versions.

```json
{
  "size": "922.50 MB",
  "versions": [
    {
      "name": "3.19.0",
      "directory": "/path/to/fvm/versions/3.19.0",
      "releaseFromChannel": null,
      "type": "release",
      "binPath": "/path/to/fvm/versions/3.19.0/bin",
      "hasOldBinPath": false,
      "dartBinPath": "/path/to/fvm/versions/3.19.0/bin",
      "dartExec": "/path/to/fvm/versions/3.19.0/bin/dart",
      "flutterExec": "/path/to/fvm/versions/3.19.0/bin/flutter",
      "flutterSdkVersion": "3.19.0",
      "dartSdkVersion": "3.5.1",
      "isSetup": true
    },
    ...
  ]
}
```

--------------------------------

### Install FVM using Homebrew

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/getting-started/installation.mdx

Installs FVM using the Homebrew package manager on macOS. Ensure Homebrew is installed before running this command.

```bash
brew install fvm
```

--------------------------------

### Install Flutter Version from Specific Channel

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/release-multiple-channels.md

Forces installation of a Flutter version from a specified channel (e.g., beta). Use this when you need to test or use a version from a non-stable channel.

```bash
fvm use 3.16.0@beta
```

--------------------------------

### Example of switching global Flutter versions

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/global-configuration.mdx

Demonstrates setting different channels as global and verifying the change with the flutter version command.

```bash
# Set beta channel as global
fvm global beta

# Check version
flutter --version # Will be beta release

# Set stable channel as global
fvm global stable

# Check version
flutter --version # Will be stable release
```

--------------------------------

### Run fvm_mcp from Source

Source: https://github.com/leoafarias/fvm/blob/main/fvm_mcp/README.md

Navigate to the fvm_mcp directory, install dependencies, and run the server using Dart.

```bash
cd fvm_mcp
dart pub get
dart run bin/fvm_mcp.dart
```

--------------------------------

### List Installed Flutter SDK Versions

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/json-api.md

Lists installed Flutter SDK versions. Use `--compress` for compact JSON output and `--skip-size-calculation` to omit cache size details.

```bash
fvm api list [--compress] [--skip-size-calculation]
```

--------------------------------

### Switch between SDK versions

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/workflows.mdx

Lists installed versions and switches the active SDK version for the current project.

```bash
# Check current version
fvm list

# Switch to different version
fvm use 3.16.0

# Force switch without validation
fvm use 3.16.0 --force
```

--------------------------------

### Install Flutter Version from Stable Channel

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/release-multiple-channels.md

Installs a Flutter version from the stable channel by default. Use this when you want the most stable release of a specific version.

```bash
fvm use 3.16.0
```

--------------------------------

### Install a specific Flutter version

Source: https://github.com/leoafarias/fvm/blob/main/example/README.md

Downloads and caches the specified Flutter version locally.

```bash
> fvm install 1.17.4
```

--------------------------------

### Install and Uninstall FVM via Shell

Source: https://github.com/leoafarias/fvm/blob/main/scripts/README.md

Use these commands to install the latest or specific versions of FVM, or to uninstall the tool.

```bash
# Install latest version
curl -fsSL https://fvm.app/install.sh | bash

# Install specific version
curl -fsSL https://fvm.app/install.sh | bash -s 3.2.1

# Uninstall FVM
./docs/public/install.sh --uninstall
```

--------------------------------

### Setup and Execution of FVM Smoke Test

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/manual-smoke-test.md

This script sets up a temporary directory, initializes a fake Flutter repository, and configures FVM for testing. It's designed to be run from the repository root.

```bash
set -euo pipefail

command -v expect >/dev/null || {
  echo "expect is required for the interactive Melos prompt check" >&2
  exit 1
}

FVM_REPO="$(pwd)"
ROOT="$(mktemp -d /tmp/fvm-branch-smoke.XXXXXX)"
MARKER="$ROOT/.fvm-smoke-root"
FAKE_REMOTE_WORK="$ROOT/flutter_seed"
FAKE_REMOTE_BARE="$ROOT/flutter_remote.git"
CACHE="$ROOT/fvm-cache"
GIT_CACHE="$ROOT/cache.git"
PROJECT="$ROOT/app"
HOME_DIR="$ROOT/home"

: > "$MARKER"

mkdir -p \
  "$FAKE_REMOTE_WORK/bin" \
  "$FAKE_REMOTE_WORK/bin/cache/dart-sdk/bin" \
  "$PROJECT/.vscode" \
  "$HOME_DIR"

cd "$FAKE_REMOTE_WORK"
git init -b stable >/dev/null
git config user.email smoke@fvm.app
git config user.name "FVM Smoke"

printf '3.99.0-smoke\n' > version
printf '#!/usr/bin/env sh\necho "Flutter smoke 3.99.0 on stable"\n' > bin/flutter
printf '#!/usr/bin/env sh\necho "Dart smoke 3.99.0"\n' > bin/dart
printf '#!/usr/bin/env sh\necho "Dart smoke 3.99.0"\n' > bin/cache/dart-sdk/bin/dart
chmod +x bin/flutter bin/dart bin/cache/dart-sdk/bin/dart

git add . >/dev/null
git commit -m 'seed fake flutter' >/dev/null
BASE_SHA="$(git rev-parse HEAD)"
git tag smoke-tag "$BASE_SHA"

git checkout --detach >/dev/null 2>&1
printf 'hidden-only\n' > hidden_ref_only
git add hidden_ref_only >/dev/null
git commit -m 'seed hidden-only ref' >/dev/null
HIDDEN_SHA="$(git rev-parse HEAD)"
git update-ref refs/pull/1/head "$HIDDEN_SHA"
git checkout stable >/dev/null 2>&1

git clone --bare "$FAKE_REMOTE_WORK" "$FAKE_REMOTE_BARE" >/dev/null 2>&1
git --git-dir="$FAKE_REMOTE_BARE" symbolic-ref HEAD refs/heads/stable
git --git-dir="$FAKE_REMOTE_BARE" update-ref refs/pull/1/head "$HIDDEN_SHA"

REMOTE_URL="file://$FAKE_REMOTE_BARE"

cd "$PROJECT"
printf 'name: fvm_smoke_app\nenvironment:\n  sdk: ">=3.6.0 <4.0.0"\n' > pubspec.yaml
printf 'name: fvm_smoke_workspace\npackages:\n  - .\n' > melos.yaml
: > .gitignore

run_fvm_skip() {
  HOME="$HOME_DIR" \
  FVM_CACHE_PATH="$CACHE" \
  FVM_GIT_CACHE_PATH="$GIT_CACHE" \
  FVM_FLUTTER_URL="$REMOTE_URL" \
  FVM_USE_GIT_CACHE=true \
  dart run "$FVM_REPO/bin/main.dart" --fvm-skip-input "$@"
}

run_fvm_interactive_with_yes() {
  SMOKE_HOME="$HOME_DIR" \
  SMOKE_CACHE="$CACHE" \
  SMOKE_GIT_CACHE="$GIT_CACHE" \
  SMOKE_REMOTE_URL="$REMOTE_URL" \
  SMOKE_REPO="$FVM_REPO" \
  expect <<'EOF'
set timeout 90
set main [file join $env(SMOKE_REPO) bin main.dart]
spawn env \
  "HOME=$env(SMOKE_HOME)" \
  "FVM_CACHE_PATH=$env(SMOKE_CACHE)" \
  "FVM_GIT_CACHE_PATH=$env(SMOKE_GIT_CACHE)" \
  "FVM_FLUTTER_URL=$env(SMOKE_REMOTE_URL)" \
  "FVM_USE_GIT_CACHE=true" \
  dart run $main use stable --force --skip-setup --skip-pub-get
expect {
  "Would you like to configure melos.yaml to use FVM-managed Flutter SDK?" { send "y\r" }
  timeout { puts "Timed out waiting for Melos prompt"; exit 124 }
}
expect eof
catch wait result
exit [lindex $result 3]
EOF
}

printf '\n== fvm version ==\n'
run_fvm_skip --version

printf '\n== install stable --no-setup ==\n'
run_fvm_skip install stable --no-setup

printf '\n== use stable, non-interactive default prompt path ==\n'
USE_SKIP_OUTPUT="$(run_fvm_skip use stable --force --skip-setup --skip-pub-get 2>&1)"
printf '%s\n' "$USE_SKIP_OUTPUT"
case "$USE_SKIP_OUTPUT" in
  *"Would you like to configure melos.yaml to use FVM-managed Flutter SDK?"*) ;;
  *) echo "Melos prompt was not emitted under skip input" >&2; exit 1 ;; 
esac
case "$USE_SKIP_OUTPUT" in
  *"Skipping input confirmation"*) ;; 
  *) echo "Skip-input confirmation warning was not emitted" >&2; exit 1 ;; 
esac
case "$USE_SKIP_OUTPUT" in
  *"Using default value of false"*) ;; 
  *) echo "Skip-input default value was not reported as false" >&2; exit 1 ;; 
esac
if grep -Fq 'sdkPath:' melos.yaml; then
  echo "melos.yaml changed even though skip-input default is false" >&2
  exit 1
fi

test -f .fvmrc
grep -Fq '"flutter": "stable"' .fvmrc
test -f .fvm/fvm_config.json
grep -Fq '"flutterSdkVersion": "stable"' .fvm/fvm_config.json
test -f .fvm/version
grep -Fxq '3.99.0-smoke' .fvm/version
test -f .fvm/release
grep -Fxq 'stable' .fvm/release

test -L .fvm/flutter_sdk
FLUTTER_SDK_TARGET="$(readlink .fvm/flutter_sdk)"
case "$FLUTTER_SDK_TARGET" in
  "$CACHE/versions/stable") ;; 
  *) echo "Unexpected flutter_sdk symlink target: $FLUTTER_SDK_TARGET" >&2; exit 1 ;; 
esac

test -L .fvm/versions/stable
VERSION_LINK_TARGET="$(readlink .fvm/versions/stable)"
case "$VERSION_LINK_TARGET" in
  "$CACHE/versions/stable") ;; 
  *) echo "Unexpected version symlink target: $VERSION_LINK_TARGET" >&2; exit 1 ;; 
esac

grep -Fxq '.fvm/' .gitignore
grep -Fq '"dart.flutterSdkPath": ".fvm/versions/stable"' .vscode/settings.json

printf '\n== use stable, interactive yes prompt path ==\n'
run_fvm_interactive_with_yes
grep -Fq 'sdkPath: .fvm/flutter_sdk' melos.yaml

```

--------------------------------

### Get Project Configuration

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/json-api.md

Returns project configuration. Use `--compress` for compact JSON output and `--path` to specify the project directory.

```bash
fvm api project [--compress] [--path <path>]
```

--------------------------------

### Install FVM using Chocolatey

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/getting-started/installation.mdx

Installs FVM using the Chocolatey package manager on Windows. This command can be run in the command line or PowerShell.

```bash
choco install fvm
```

--------------------------------

### Run Integration Tests

Source: https://github.com/leoafarias/fvm/blob/main/AGENTS.md

Execute the integration test suite. This requires Flutter to be installed.

```bash
dart run grinder integration-test
```

--------------------------------

### Integrate FVM with CI/CD

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/workflows.mdx

Installs FVM and the project SDK version within a continuous integration pipeline.

```bash
# Install FVM
dart pub global activate fvm

# Install project SDK version
fvm install

# Run Flutter commands
fvm flutter build apk --release
```

--------------------------------

### Install FVM in Container or CI Environments

Source: https://github.com/leoafarias/fvm/blob/main/scripts/install.md

Set the FVM_ALLOW_ROOT environment variable to permit installation in root-privileged environments like Docker or CI runners.

```bash
export FVM_ALLOW_ROOT=true
curl -fsSL https://fvm.app/install.sh | bash
```

--------------------------------

### Configure offline installation

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/workflows.mdx

Sets up custom cache paths and disables git caching for offline environments.

```bash
# Configure custom cache path
fvm config --cache-path /shared/flutter-cache

# Disable git cache for offline use
fvm config --no-use-git-cache

# Install from local cache
fvm install 3.19.0
```

--------------------------------

### Manage custom Flutter forks

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/workflows.mdx

Adds and installs custom Flutter SDK forks for project use.

```bash
# Add fork
fvm fork add company https://github.com/company/flutter.git

# Install from fork
fvm install company/stable

# Use fork version
fvm use company/3.19.0
```

--------------------------------

### FVM list output examples

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/custom-version.mdx

Terminal output showing the cached Flutter versions before and after adding a custom fork.

```ansi
Cache directory:  /Users/{user}/fvm/versions
Directory Size: 6.47 GB

┌────────────────┬─────────┬────────────────────┬─────────────────┬──────────────┬────────┬───────┐
│ Version        │ Channel │ Flutter Version    │ Dart Version    │ Release Date │ Global │ Local │
├────────────────┼─────────┼────────────────────┼─────────────────┼──────────────┼────────┼───────┤
│ stable         │ stable  │ 3.24.1             │ 3.5.1           │ Aug 21, 2024 │        │       │
├────────────────┼─────────┼────────────────────┼─────────────────┼──────────────┼────────┼───────┤
│ 3.19.0         │ stable  │ 3.19.0             │ 3.3.0           │ Feb 15, 2024 │        │       │
└────────────────┴─────────┴────────────────────┴─────────────────┴──────────────┴────────┴───────┘
```

```ansi
Cache directory:  /Users/{user}/fvm/versions
Directory Size: 6.47 GB

┌────────────────┬─────────┬────────────────────┬─────────────────┬──────────────┬────────┬───────┐
│ Version        │ Channel │ Flutter Version    │ Dart Version    │ Release Date │ Global │ Local │
├────────────────┼─────────┼────────────────────┼─────────────────┼──────────────┼────────┼───────┤
│ custom_special │         │ 3.24.0-1.0.pre.575 │ 3.6.0-146.0.dev │              │        │       │
├────────────────┼─────────┼────────────────────┼─────────────────┼──────────────┼────────┼───────┤
│ stable         │ stable  │ 3.24.1             │ 3.5.1           │ Aug 21, 2024 │        │       │
├────────────────┼─────────┼────────────────────┼─────────────────┼──────────────┼────────┼───────┤
│ 3.19.0         │ stable  │ 3.19.0             │ 3.3.0           │ Feb 15, 2024 │        │       │
└────────────────┴─────────┴────────────────────┴─────────────────┴──────────────┴────────┴───────┘
```

--------------------------------

### Clean up SDK versions

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/workflows.mdx

Lists installed versions and removes specific or all versions to free disk space.

```bash
# List installed versions
fvm list

# Remove specific version
fvm remove 3.16.0

# Remove all versions
fvm remove --all
```

--------------------------------

### Example JSON Response Payload

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/json-api.md

This is an example of the JSON output you can expect from the 'fvm api project' command, detailing various aspects of the project's Flutter configuration.

```json
{
  "project": {
    "name": "my_project",
    "config": {
      "flutter": "3.19.0",
      "flavors": {
        "production": "3.19.0",
        "development": "stable"
      }
    },
    "path": "/path/to/project",
    "pinnedVersion": {
      "name": "3.19.0",
      "releaseFromChannel": null,
      "type": "release"
    },
    "activeFlavor": "production",
    "flavors": {
      "production": "3.19.0",
      "development": "stable"
    },
    "dartToolGeneratorVersion": "3.3.0",
    "dartToolVersion": "3.19.0",
    "isFlutter": true,
    "localFvmPath": "/path/to/project/.fvm",
    "localVersionsCachePath": "/path/to/project/.fvm/versions",
    "localVersionSymlinkPath": "/path/to/project/.fvm/versions/3.19.0",
    "gitIgnorePath": "/path/to/project/.gitignore",
    "pubspecPath": "/path/to/project/pubspec.yaml",
    "configPath": "/path/to/project/.fvmrc",
    "legacyConfigPath": "/path/to/project/.fvm/fvm_config.json",
    "hasConfig": true,
    "hasPubspec": true,
    "pubspec": {
      "name": "my_project",
      "version": "0.1.0",
      "publish_to": "none",
      "environment": {
        "sdk": ">=2.17.0 <4.0.0"
      },
      "description": "A new Flutter project.",
      "dependencies": {
        ...
      },
      "dev_dependencies": {
        ...
      },
      "flutter": {
        "uses-material-design": true
      }
    }
  }
}
```

--------------------------------

### Add and use a Flutter fork with FVM

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/custom-version.mdx

Use the fork command to register a custom repository and then install or use it like a standard Flutter version.

```bash
# Add a fork
fvm fork add mycompany https://github.com/mycompany/flutter.git

# Use it like any version
fvm install mycompany/stable
fvm use mycompany/3.19.0
```

--------------------------------

### fvm list

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/basic-commands.mdx

Displays all Flutter SDK versions currently installed and cached by FVM.

```APIDOC
## list

### Description
Displays all installed Flutter SDK versions.

### Method
CLI

### Endpoint
fvm list

### Aliases
- `fvm ls` - Short form

### Output
Shows all cached SDK versions with their installation paths.
```

--------------------------------

### GET /api/project

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/json-api.md

Fetches details about the current Flutter project configuration.

```APIDOC
## GET /api/project

### Description
Fetches details about the current Flutter project configuration.

### Method
GET

### Endpoint
/api/project

### Query Parameters
- **--compress** (boolean) - Optional - Outputs JSON with no whitespace.
- **--path** (string) - Optional - The path to the project. Defaults to the current working directory.

### Response
#### Success Response (200)
- **project** (object) - Contains detailed project information.
  - **name** (string) - The name of the project.
  - **config** (object) - Project configuration details.
    - **flutter** (string) - The Flutter SDK version used.
    - **flavors** (object) - Defined project flavors and their associated Flutter versions.
  - **path** (string) - The absolute path to the project directory.
  - **pinnedVersion** (object) - Information about the pinned Flutter SDK version.
    - **name** (string) - The name of the pinned version.
    - **releaseFromChannel** (string or null) - The release channel from which the version was obtained.
    - **type** (string) - The type of the pinned version (e.g., 'release').
  - **activeFlavor** (string) - The currently active project flavor.
  - **flavors** (object) - A mapping of flavor names to their Flutter SDK versions.
  - **dartToolGeneratorVersion** (string) - The version of the Dart tool generator.
  - **dartToolVersion** (string) - The version of the Dart tool.
  - **isFlutter** (boolean) - Indicates if the project is a Flutter project.
  - **localFvmPath** (string) - The local path to the FVM configuration directory.
  - **localVersionsCachePath** (string) - The path to the cached Flutter versions.
  - **localVersionSymlinkPath** (string) - The path to the symlink for the active Flutter version.
  - **gitIgnorePath** (string) - The path to the .gitignore file.
  - **pubspecPath** (string) - The path to the pubspec.yaml file.
  - **configPath** (string) - The path to the FVM configuration file (.fvmrc).
  - **legacyConfigPath** (string) - The path to the legacy FVM configuration file.
  - **hasConfig** (boolean) - Indicates if an FVM configuration file exists.
  - **hasPubspec** (boolean) - Indicates if a pubspec.yaml file exists.
  - **pubspec** (object) - The content of the pubspec.yaml file.

### Response Example
```json
{
  "project": {
    "name": "my_project",
    "config": {
      "flutter": "3.19.0",
      "flavors": {
        "production": "3.19.0",
        "development": "stable"
      }
    },
    "path": "/path/to/project",
    "pinnedVersion": {
      "name": "3.19.0",
      "releaseFromChannel": null,
      "type": "release"
    },
    "activeFlavor": "production",
    "flavors": {
      "production": "3.19.0",
      "development": "stable"
    },
    "dartToolGeneratorVersion": "3.3.0",
    "dartToolVersion": "3.19.0",
    "isFlutter": true,
    "localFvmPath": "/path/to/project/.fvm",
    "localVersionsCachePath": "/path/to/project/.fvm/versions",
    "localVersionSymlinkPath": "/path/to/project/.fvm/versions/3.19.0",
    "gitIgnorePath": "/path/to/project/.gitignore",
    "pubspecPath": "/path/to/project/pubspec.yaml",
    "configPath": "/path/to/project/.fvmrc",
    "legacyConfigPath": "/path/to/project/.fvm/fvm_config.json",
    "hasConfig": true,
    "hasPubspec": true,
    "pubspec": {
      "name": "my_project",
      "version": "0.1.0",
      "publish_to": "none",
      "environment": {
        "sdk": ">=2.17.0 <4.0.0"
      },
      "description": "A new Flutter project.",
      "dependencies": {
        ...
      },
      "dev_dependencies": {
        ...
      },
      "flutter": {
        "uses-material-design": true
      }
    }
  }
}
```
```

--------------------------------

### GET fvm api context

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/json-api.md

Returns information about the current FVM environment configuration.

```APIDOC
## GET fvm api context

### Description
Returns information about the FVM's current context.

### Method
GET

### Endpoint
fvm api context

### Parameters
#### Query Parameters
- **--compress** (flag) - Optional - Outputs JSON with no whitespace.

### Response
#### Success Response (200)
- **context** (object) - FVM environment details including paths and configuration settings.

#### Response Example
{
  "context": {
    "fvmVersion": "3.0.14",
    "workingDirectory": "/path/to/project"
  }
}
```

--------------------------------

### Trigger FVM Cache Migration

Source: https://github.com/leoafarias/fvm/blob/main/internal/migration-manual-test-plan.md

Run the FVM installation command for the 'stable' version, which triggers the cache migration logic from a legacy clone to a bare mirror. Ensure the correct environment variables are set.

```bash
# Trigger EnsureCache -> ensureBareCacheIfPresent -> _migrateCacheCloneToMirror
FVM_CACHE_PATH="$FVM_CACHE_PATH" FVM_USE_GIT_CACHE=true \
  dart run bin/main.dart install stable
```

--------------------------------

### fvm releases

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/basic-commands.mdx

Fetches and displays available Flutter SDK releases that can be installed.

```APIDOC
## releases

### Description
Shows available Flutter SDK releases for installation.

### Method
CLI

### Endpoint
fvm releases [options]

### Parameters
#### Options
- **-c, --channel** (string) - Filter by channel: stable, beta, dev, all (default: stable)

### Request Example
```bash
fvm releases
fvm releases --channel beta
fvm releases --channel all
```
```

--------------------------------

### Get FVM environment information as JSON

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/basic-commands.mdx

Retrieves detailed FVM environment information, including configuration and paths, in JSON format. Use the `--compress` option for compact output.

```bash
fvm api context
```

```bash
fvm api context --compress
```

--------------------------------

### Get project configuration as JSON

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/basic-commands.mdx

Retrieves the FVM project configuration for a specified directory in JSON format. Use the `-p` or `--path` option to target a specific project.

```bash
fvm api project --path /projects/myapp
```

--------------------------------

### Set project Flutter version

Source: https://github.com/leoafarias/fvm/blob/main/example/README.md

Configures the project to use the previously installed Flutter version.

```bash
> fvm use 1.17.4
```

--------------------------------

### Get FVM Environment Context

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/json-api.md

Returns FVM environment information. Use `--compress` for compact JSON output.

```bash
fvm api context [--compress]
```

--------------------------------

### Configure Shell PATH for FVM

Source: https://github.com/leoafarias/fvm/blob/main/scripts/install.md

Manually add the FVM binary directory to your PATH when the installer cannot modify the shell environment directly.

```bash
export PATH="$HOME/fvm/bin:$PATH"
```

--------------------------------

### Configure PATH for FVM (Pub)

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/getting-started/installation.mdx

Adds the FVM binary directory to your system's PATH environment variable for pub installations on macOS/Linux. This allows you to run FVM commands from any directory.

```bash
export PATH="$PATH:$HOME/.pub-cache/bin"
```

--------------------------------

### List FVM cached versions

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/custom-version.mdx

Display the current FVM cache directory and the list of installed Flutter versions.

```bash
fvm list
```

--------------------------------

### Verify Git Safe Directory Configuration

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/troubleshooting/git-safe-directory-windows.md

After applying a fix, use these commands to verify that Git trusts the necessary directories and to check your FVM setup. Retrying the original command confirms the issue is resolved.

```bash
# List all trusted directories
git config --global --get-all safe.directory

# Double-check your setup
fvm doctor

# Retry the original command
fvm flutter doctor
```

--------------------------------

### List FVM Cached Versions

Source: https://github.com/leoafarias/fvm/blob/main/internal/migration-manual-test-plan.md

Execute the 'fvm list' command with the custom cache path and git cache enabled to verify that the installed versions are correctly recognized and listed.

```bash
FVM_CACHE_PATH="$FVM_CACHE_PATH" FVM_USE_GIT_CACHE=true \
  dart run bin/main.dart list
```

--------------------------------

### Next.js App Component Setup

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/_app.mdx

This is the root component for a Next.js application. It imports global and local styles and renders the main Component with its props.

```javascript
import "../globals.css";
import "../styles.css";

export default function App({ Component, pageProps }) {
  return <Component {...pageProps} />;
}
```

--------------------------------

### Run Dart commands with FVM

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/basic-commands.mdx

Execute common Dart CLI commands using the FVM-managed SDK. Ensure FVM is installed and configured.

```bash
fvm dart pub get
fvm dart analyze
fvm dart format .
fvm dart run build_runner build
```

--------------------------------

### Spawn Command with Specific SDK Version

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/running-flutter.mdx

Execute a command using a specific installed Flutter SDK version, identified by its version number or channel.

```bash
fvm spawn 3.19.0 doctor
```

--------------------------------

### Embed fvm_mcp into FVM CLI

Source: https://github.com/leoafarias/fvm/blob/main/fvm_mcp/README.md

Integrate fvm_mcp as a subcommand within the FVM CLI to keep the MCP surface version-locked with the installed FVM. This involves creating an McpCommand class that starts the server over stdio.

```dart
// lib/src/commands/mcp_command.dart  (inside FVM CLI)
import 'dart:io';
import 'package:dart_mcp/stdio.dart';
import 'package:fvm_mcp/src/server.dart';
import 'package:args/command_runner.dart';

class McpCommand extends Command<int> {
  @override
  final name = 'mcp';
  @override
  final description = 'Start the embedded MCP server over stdio.';

  @override
  Future<int> run() async {
    final channel = stdioChannel(input: stdin, output: stdout);
    final server = await FvmMcpServer.start(channel: channel);
    await server.done;
    return 0;
  }
}

// In the CLI entry, add:  runner.addCommand(McpCommand());
```

--------------------------------

### Verify Flutter SDK Version for Beta Channel

Source: https://github.com/leoafarias/fvm/blob/main/internal/migration-manual-test-plan.md

Execute the 'flutter --version' command using the Flutter SDK installed from the beta channel within the custom cache path. This verifies SDK execution and version reporting.

```bash
"$FVM_CACHE_PATH/versions/beta/bin/flutter" --version
```

--------------------------------

### Uninstall FVM using Install Script (macOS/Linux)

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/getting-started/faq.md

Use this command to uninstall FVM when installed via the install script on macOS or Linux.

```bash
./install.sh --uninstall
```

--------------------------------

### Use a custom version in a project

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/custom-version.mdx

Set the project to use a manually added custom version by referencing its name.

```bash
fvm use custom_special
```

--------------------------------

### Test Multiple Versions

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/quick-reference.md

Spawns a command using specific SDK versions to test compatibility across different releases.

```bash
fvm spawn 3.19.0 test
fvm spawn 3.16.0 test
```

--------------------------------

### Navigate to project directory

Source: https://github.com/leoafarias/fvm/blob/main/example/README.md

Changes the current working directory to the target project path.

```bash
> cd path/to/project
```

--------------------------------

### Uninstall FVM using Install Script

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/getting-started/installation.mdx

Uninstalls FVM by running the install script with the --uninstall flag. This command removes FVM from your system.

```bash
curl -fsSL https://fvm.app/install.sh | bash -s -- --uninstall
```

--------------------------------

### Activate FVM as a Pub Package

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/getting-started/installation.mdx

Installs FVM as a global Dart pub package. This method is not recommended if FVM will manage your global Flutter install.

```bash
dart pub global activate fvm
```

--------------------------------

### Switch project to a specific flavor

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/project-flavors.md

Set the project version to the version configured for the specified flavor.

```bash
fvm use {flavor_name}
```

--------------------------------

### Test across SDK versions

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/workflows.mdx

Runs tests using the project's configured version or spawns specific versions for testing.

```bash
# Test with current project version
fvm flutter test

# Test with specific version
fvm spawn 3.19.0 test

# Test with another version
fvm spawn 3.16.0 test
```

--------------------------------

### Project File Structure

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/quick-reference.md

Displays the standard directory layout created by FVM within a project.

```text
myproject/
├── .fvm/
│   ├── flutter_sdk → ../../../.fvm/versions/3.19.0
│   └── fvm_config.json
├── .fvmrc
└── .gitignore (updated)
```

--------------------------------

### Set Global Flutter SDK URL

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/custom-version.mdx

Globally changes the repository URL FVM uses for installing and managing Flutter SDK versions. If you have existing versions installed, they must be reinstalled to use the new URL.

```bash
fvm config --flutter-url https://github.com/org/custom-flutter.git
```

--------------------------------

### Add Dart SDK to PATH on Linux/macOS

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/getting-started/faq.md

Append this line to your `~/.bashrc` or `~/.profile` to ensure the `pub` command is found.

```bash
export PATH="$PATH:/usr/lib/dart/bin"
```

--------------------------------

### Uninstall FVM using Homebrew

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/getting-started/faq.md

Uninstall FVM if it was installed using Homebrew.

```bash
brew uninstall fvm
```

--------------------------------

### Run Unit Tests

Source: https://github.com/leoafarias/fvm/blob/main/AGENTS.md

Execute unit tests for the project.

```bash
dart test
```

--------------------------------

### MCP Client Configuration (Binary Mode)

Source: https://github.com/leoafarias/fvm/blob/main/fvm_mcp/README.md

Configure your MCP client to connect to a standalone fvm_mcp binary. Ensure the binary is in your PATH.

```json
{
  "command": "fvm_mcp",
  "args": []
}
```

--------------------------------

### Manage SDK flavors

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/workflows.mdx

Assigns different SDK versions to specific project flavors and executes commands for those flavors.

```bash
# Set development version
fvm use 3.19.0 --flavor development

# Set production version
fvm use 3.16.0 --flavor production

# Use flavor-specific version
fvm flavor development build apk
```

--------------------------------

### Uninstall FVM using Chocolatey (Windows)

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/getting-started/faq.md

Uninstall FVM if it was installed using Chocolatey on Windows.

```powershell
choco uninstall fvm
```

--------------------------------

### Fetch Flutter Project Details

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/json-api.md

Use this command to retrieve detailed configuration information for the current Flutter project. The output is a JSON payload.

```bash
fvm api project [options]
```

--------------------------------

### FVM Destroy

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/basic-commands.mdx

Removes the entire FVM cache and all installed versions. Use with caution as this action is irreversible.

```APIDOC
## POST /api/destroy

### Description
Removes the entire FVM cache and all installed versions.

### Method
POST

### Endpoint
/api/destroy

### Parameters
#### Query Parameters
- **options** (string) - Optional - Options for the destroy command, such as `--force` to bypass confirmation.

### Request Example
```json
{
  "options": "--force"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating the cache has been cleared.

#### Response Example
```json
{
  "message": "FVM cache and all installed versions have been removed."
}
```
```

--------------------------------

### Configure FVM project flavors

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/project-flavors.md

Define SDK versions for different environments in the FVM configuration file.

```json
{
  "flutter": "stable",
  "flavors": {
    "development": "stable",
    "staging": "3.19.0",
    "production": "3.16.0"
  }
}
```

--------------------------------

### GET fvm api releases

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/advanced/json-api.md

Provides a list of available Flutter SDK releases from the official channels.

```APIDOC
## GET fvm api releases

### Description
Provides a list of available Flutter SDK releases.

### Method
GET

### Endpoint
fvm api releases

### Parameters
#### Query Parameters
- **--compress** (flag) - Optional - Outputs JSON with no whitespace.
- **--limit** (number) - Optional - Number of releases to return.
- **--filter-channel** (string) - Optional - Filter by channel (stable, beta, dev).

### Response
#### Success Response (200)
- **versions** (array) - List of available releases.
- **channels** (object) - Information about release channels.

#### Response Example
{
  "versions": [
    {
      "hash": "0b591f2c82e9f59276ed68c7d4cbd63196f7c865",
      "channel": "beta",
      "version": "3.17.0-0.0.pre"
    }
  ]
}
```

--------------------------------

### Configure monorepo SDK versions

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/workflows.mdx

Sets SDK versions at the root and for specific sub-apps within a monorepo structure.

```bash
# Root configuration
cd monorepo
fvm use 3.19.0

# App-specific versions
cd apps/mobile
fvm use 3.16.0

# Package uses root version
cd packages/shared
# Inherits from root
```

--------------------------------

### Deactivate FVM using Pub

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/getting-started/faq.md

Deactivate FVM from global packages if it was installed via `dart pub global activate`.

```bash
dart pub global deactivate fvm
```

--------------------------------

### Inspect Project Files

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/manual-smoke-test.md

Displays the content of several project configuration files, including `.fvmrc`, `.fvm/fvm_config.json`, `.fvm/version`, `.fvm/release`, `.gitignore`, `.vscode/settings.json`, and `melos.yaml`.

```bash
printf '\n== project files ==\n'
printf '.fvmrc:\n'
sed -n '1,20p' .fvmrc
printf '\n'
printf '.fvm/fvm_config.json:\n'
sed -n '1,20p' .fvm/fvm_config.json
printf '\n'
printf '.fvm/version: '
cat .fvm/version
printf '\n'
printf '.fvm/release: '
cat .fvm/release
printf '\n'
printf 'flutter_sdk -> %s\n' "$FLUTTER_SDK_TARGET"
printf 'version link -> %s\n' "$VERSION_LINK_TARGET"
printf '.gitignore:\n'
sed -n '1,20p' .gitignore
printf '\n'
printf '.vscode/settings.json:\n'
sed -n '1,40p' .vscode/settings.json
printf '\n'
printf 'melos.yaml:\n'
sed -n '1,40p' melos.yaml
printf '\n'
```

--------------------------------

### Configure Version Control for FVM

Source: https://github.com/leoafarias/fvm/blob/main/docs/pages/documentation/guides/workflows.mdx

Add the local symlink to gitignore and commit configuration files to ensure consistent SDK versions across team environments.

```bash
# Add to .gitignore
.fvm/flutter_sdk

# Commit these files
.fvmrc
.fvm/fvm_config.json
```