### MCP server usage examples

Source: https://scalameta.org/metals/docs/features/mcp

Examples of starting the MCP server with different options: specifying a port, generating config for Cursor, using stdio transport, and overriding user configuration.

```bash
# Start MCP server for a project  
metals-mcp --workspace /path/to/project  

# Start with a specific port  
metals-mcp --workspace /path/to/project --port 8080  

# Generate configuration for Cursor  
metals-mcp --workspace /path/to/project --client cursor  

# Use stdio transport (useful for tools without HTTP support)  
metals-mcp --workspace /path/to/project --transport stdio  

# Override user configuration  
metals-mcp --workspace /path/to/project --java-home /path/to/jdk
```

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

### Start run session arguments example

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example arguments for the metals-run-session-start command. The DebugSessionParameters object should be forwarded to the debug-adapter-start command as is.

```json
{
  "targets": ["mybuild://workspace/foo/?id=foo"],
   dataKind: "scala-main-class",
   data: {
      className: "com.foo.App"
   }
}

```

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

### Build and launch the website with yarn

Source: https://scalameta.org/metals/docs/contributors/updating-website

Build and launch the website locally. Run yarn install only the first time. Use yarn start for development with live reload, or yarn build and yarn serve to test the search feature.

```bash
cd website  

yarn install # only the first time, to install the dependencies  

yarn start  

  

# To test search feature in local development  

yarn build  

yarn serve  


```

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

### startMcpServer configuration

Source: https://scalameta.org/metals/docs/editors/user-configuration

Configuration example for the startMcpServer setting. When true, Metals starts the MCP (SSE) server that an AI agent can connect to. The default is false.

```json
{
  "metals": {
    "startMcpServer": true
  }
}
```

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

### Discover main classes - request example

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example arguments for the 'discover-jvm-run-command' command. The object contains a path to a Scala file and a run type.

```json
{

    "path": "path/to/file.scala",

    "runType": "run"

}
```

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

### debug-adapter-start DebugDiscoveryParams example

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example DebugDiscoveryParams object for the debug-adapter-start command. Discovers and runs a test or main class.

```json
{  

    "path": "path/to/file.scala",  

    "runType": "run",  

}  

```

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

### debug-adapter-start DebugSessionParameters example

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example DebugSessionParameters object for the debug-adapter-start command. Specifies a target and a main class to run.

```json
{  

  "targets": ["mybuild://workspace/foo/?id=foo"],  

   dataKind: "scala-main-class",  

   data: {  

      className: "com.foo.App"  

   }  

}  

```

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

### Discover main classes - response example

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example response from the 'discover-jvm-run-command' command. Contains targets, data kind, and data with class name, arguments, JVM options, environment variables, and shell command.

```json
{

  "targets": ["id1"],

  "dataKind": "scala-main-class",

  "data": {

    "class": "Foo",

    "arguments": [],

    "jvmOptions": [],

    "environmentVariables": [],

    "shellCommand": "java ..."

  }

}
```

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

### BSP server discovery configuration file (.bsp/bill.json)

Source: https://scalameta.org/metals/docs/integrations/new-build-tool

Example JSON configuration file that Metals uses to discover and connect to a BSP server. The 'argv' field specifies the command to start the server process.

```json
{
  "name": "Bill",
  "version": "1.0.0",
  "bspVersion": "2.0.0",
  "languages": ["scala"],
  "argv": ["bill", "bsp"]
}
```

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

### debug-adapter-start DebugUnresolvedMainClassParams example

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example DebugUnresolvedMainClassParams object for the debug-adapter-start command. Resolves a main class by name and target.

```json
{  

  "mainClass": "path/to/file.scala",  

  "buildTarget": "metals"  

}  

```

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

### Example .env file format

Source: https://scalameta.org/metals/docs/integrations/debug-adapter-protocol

Example of a supported `.env` file for `envFile` parameter. Supports single-line and multi-line quoted values without substitution. Variables in `env` object take precedence. Keys with dots or dashes are ignored.

```plaintext
# single line values
key1=value 1
key2='value 2'   # ignored inline comment
key3="value 3"

# multi-line values
key4='line 1
line 2'
key5="line 1
line 2"

# export statements
export key6=value 6

# comma delimiter
key7:value 6

# keys cannot contain dots or dashes
a.b.key8=value 8   # will be ignored
a-b-key9=value 9   # will be ignored
```

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

### debug-adapter-start DebugUnresolvedTestClassParams example

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example DebugUnresolvedTestClassParams object for the debug-adapter-start command. Resolves a test suite by name.

```json
{  

   "testClass": "com.foo.FooSuite"  

}  

```

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

### debug-adapter-start ScalaTestSuitesDebugRequest example

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example ScalaTestSuitesDebugRequest object for the debug-adapter-start command. Specifies a target and test suites to run.

```json
{  

  "target": "metals"  

  "requestData" : {  

    "suites": ["com.foo.FooSuite"],  

    "jvmOptions": []],  

    "environmentVariables": [],  

   }  

}  

```

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

### Install standalone MCP server with Coursier

Source: https://scalameta.org/metals/docs/features/mcp

Installs the standalone MCP server using Coursier.

```bash
cs install metals-mcp
```

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

### Start Vim with local Metals version

Source: https://scalameta.org/metals/docs/contributors/getting-started

Starts Vim with the locally published Metals version. Run this after creating the new-metals-vim script and ensure the script is in your $PATH.

```shell
cd test-workspace # any directory you want to manually test Metals  

new-metals-vim && vim build.sbt # remember to have the script in your $PATH  

```

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

### Install Bazel BSP with coursier

Source: https://scalameta.org/metals/docs/build-tools/bazel

Run this command in the directory where Bazel BSP should be installed. Replace <version> with the newest available version from the release page or check for the latest nightly using `cs complete-dep org.jetbrains.bsp:bazel-bsp:`. After installation, use the `Metals: Connect to build server` command if Metals doesn't pick up the new BSP configuration automatically.

```bash
cs launch org.jetbrains.bsp:bazel-bsp:<version> -M org.jetbrains.bsp.bazel.install.Install -- --targets //...  
```

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

### Discover tests - request for a file

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example arguments for the 'discover-tests' command when discovering test cases for a specific URI.

```json
{

  uri: file:///home/dev/foo/Bar.scala

}
```

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

### debug-adapter-start DebugUnresolvedAttachRemoteParams example

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example DebugUnresolvedAttachRemoteParams object for the debug-adapter-start command. Attaches to a running JVM process.

```json
{  

    "hostName": "localhost",  

    "port": 1234,  

    "buildTarget": "metals",  

}  

```

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

### Goto location command arguments example

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example arguments for the metals-goto-location command. The first parameter is an LSP Location object with uri and range fields; the second optional parameter otherWindow is a Boolean hint to open the location in another window.

```json
[

  {
    "uri": "file://path/to/Definition.scala",
    "range": {
      "start": {"line": 194, "character": 0},
      "end":   {"line": 194, "character": 1}
    },
    "otherWindow" : true
  },

]

```

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

### Install Metals with Coursier bootstrap

Source: https://scalameta.org/metals/docs/editors/vim

Installs the Metals language server as a standalone binary using Coursier. This is the simplest way to set up Metals for use with alternative LSP clients.

```bash
coursier bootstrap org.scalameta:metals_2.13:1.6.8 -o metals -f  

```

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

### Bootstrap metals binary with coursier

Source: https://scalameta.org/metals/docs/editors/emacs

Installs the metals-emacs binary as `metals` in current directory. Required before starting Emacs with the above config. Uses Scala 2.13 version 1.6.8.

```shell
coursier bootstrap org.scalameta:metals_2.13:1.6.8 -o metals -f  


```

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

### Discover tests - request for all test suites

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example arguments for the 'discover-tests' command when discovering all test suites. An empty object is used.

```json
{}
```

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

### Insert inferred method - request example

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example arguments for the 'insert-inferred-method' command. Contains a document URI and a position with line and character.

```json
{

  document: "file:///home/dev/foo/Bar.scala",

  position: {line: 5, character: 12}

}
```

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

### Run standalone MCP server

Source: https://scalameta.org/metals/docs/features/mcp

Starts the standalone MCP server for a Scala project.

```bash
metals-mcp --workspace /path/to/your/scala/project
```

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

### bsp-switch

Source: https://scalameta.org/metals/docs/integrations/new-editor

Prompts the user to select a new build server to connect to. This command does nothing in case there are less than two installed build servers on the computer. In case the user has multiple BSP servers installed, Metals will prompt the user to select which server to use.

```APIDOC
## [workspace/executeCommand] bsp-switch

### Description
Prompts the user to select a new build server to connect to. This command does nothing in case there are less than two installed build servers on the computer. In case the user has multiple BSP servers installed, Metals will prompt the user to select which server to use.

### Command
`"bsp-switch"`

### Arguments
- **null** - Required - No arguments.

### Response
No response body is specified.
```

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

### maven_install with fetch_sources enabled

Source: https://scalameta.org/metals/docs/build-tools/bazel

Example maven_install rule with fetch_sources = True to enable sources for library dependencies, required for Metals to work with Bazel. Without this, sources for dependencies are not available.

```scala
maven_install(  
    artifacts =  ["com.github.ghostdogpr:caliban_2.13:2.0.1"],  
    maven_install_json = "@//:maven_install.json",  
    repositories = [  
        "https://maven.google.com",  
        "https://repo1.maven.org/maven2",  
    ],  
    version_conflict_policy = "pinned",  
    fetch_sources = True,  
)  


```

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

### "debug-adapter-start" (DebugDiscoveryParams)

Source: https://scalameta.org/metals/docs/integrations/new-editor

Start a new debugger session by running the discovered test or main class.

```APIDOC
## "debug-adapter-start"

### Description
Start a new debugger session by running the discovered test or main class.

### Command
`"debug-adapter-start"`

### Arguments
DebugDiscoveryParams object Example:
```
{
    "path": "path/to/file.scala",
    "runType": "run",
}
```
```

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

### debug-adapter-start parameters for explicit main class

Source: https://scalameta.org/metals/docs/integrations/debug-adapter-protocol

JSON parameters for starting a debug session for an explicit main class. Includes optional `buildTarget`, `args`, `jvmOptions`, `env`, and `envFile`. `buildTarget` is optional and useful when classes have identical names across modules.

```json
{
  "mainClass": "com.foo.App",
  "buildTarget": "foo",
  "args": ["bar"],
  "jvmOptions": ["-Dpropert=123"],
  "env": { "RETRY": "TRUE" },
  "envFile": ".env"
}
```

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

### "debug-adapter-start" (DebugSessionParameters)

Source: https://scalameta.org/metals/docs/integrations/new-editor

Start a new debugger session with fully specified DebugSessionParams.

```APIDOC
## "debug-adapter-start"

### Description
Start a new debugger session with fully specified DebugSessionParams.

### Command
`"debug-adapter-start"`

### Arguments
DebugSessionParameters object Example:
```
{
  "targets": ["mybuild://workspace/foo/?id=foo"],
   dataKind: "scala-main-class",
   data: {
      className: "com.foo.App"
   }
}
```
```

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

### Get Documentation for a Symbol

Source: https://scalameta.org/metals/docs/features/mcp

Use the MCP tool to show documentation for a given Scala symbol.

```text
Using MCP, show the documentation for scala.collection.immutable.List
```

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

### file-decode build target URI

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example URI for the file-decode command with build target decoder. Use this to decode a build target.

```text
metalsDecode:file:///workspacePath/buildTargetName.metals-buildtarget  

```

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

### "debug-adapter-start" (DebugUnresolvedMainClassParams)

Source: https://scalameta.org/metals/docs/integrations/new-editor

Start a new debugger session by resolving a main class by name and target.

```APIDOC
## "debug-adapter-start"

### Description
Start a new debugger session by resolving a main class by name and target.

### Command
`"debug-adapter-start"`

### Arguments
DebugUnresolvedMainClassParams object Example:
```
{
  "mainClass": "path/to/file.scala",
  "buildTarget": "metals"
}
```
```

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

### Bootstrap Metals with Coursier

Source: https://scalameta.org/metals/docs/integrations/new-editor

Use Coursier to obtain the JVM classpath of Metals and create the 'metals' executable. This is the basic command to start the server.

```bash
coursier bootstrap org.scalameta:metals_2.13:1.6.8 -o metals -f  
```

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

### targetBuildTool configuration

Source: https://scalameta.org/metals/docs/editors/user-configuration

Configuration example for the targetBuildTool setting. Specifies the preferred build tool when multiple are detected, preventing the selection dialog. Valid values are "sbt", "gradle", "mvn", "mill", "scala-cli", "bazel". The default is an empty string.

```json
{
  "metals": {
    "targetBuildTool": "bazel"
  }
}
```

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

### Mirror configuration for jcenter and typesafe repositories

Source: https://scalameta.org/metals/docs/troubleshooting/proxy

Example mirror configuration entries for jcenter and typesafe repositories. Add similar entries for each repository that fails to resolve, and check sbt documentation for the exact repository names.

```text
jcenter.from=https://repo1.maven.org/maven2  

jcenter.to=https://artifactory.mycomany.com/maven2  

  

typesafe.from=https://repo.typesafe.com/typesafe/ivy-releases  

typesafe.to=https://artifactory.mycompany.com/typesafe-ivy-releases/  



```

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

### Bloop startup failure: FailedToOpenBspConnection and java.io.IOException

Source: https://scalameta.org/metals/docs/troubleshooting/proxy

Shows the error output when Bloop fails to start, including a stack trace and a message that Java cannot be found. This may indicate that Java is not on the PATH, preventing Bloop from launching.

```text
error: The command bsp --protocol tcp --port 44559 returned with an error  

>  

error: The launcher failed to establish a bsp connection, aborting...  

ERROR Failed to connect with build server, no functionality will work.  

java.lang.RuntimeException: The server did not start, got FailedToOpenBspConnection  

	at bloop.launcher.LauncherMain.failPromise$1(Launcher.scala:92)  

	at bloop.launcher.LauncherMain.runLauncher(Launcher.scala:119)  

	at scala.meta.internal.metals.BloopServers$$anon$1.run(BloopServers.scala:101)  

	at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:515)  

	at java.util.concurrent.FutureTask.run(FutureTask.java:264)  

	at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1128)  

	at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:628)  

	at java.lang.Thread.run(Thread.java:834)  



```

```text
Exception in thread "bloop-server-background" java.io.IOException: Cannot run program "java" (in directory "<some path here ...>"): error=2, No such file or directory  

        at java.lang.ProcessBuilder.start(ProcessBuilder.java:1048)  



```

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

### "debug-adapter-start" (DebugUnresolvedAttachRemoteParams)

Source: https://scalameta.org/metals/docs/integrations/new-editor

Start a new debugger session by attaching to existing jvm process.

```APIDOC
## "debug-adapter-start"

### Description
Start a new debugger session by attaching to existing jvm process.

### Command
`"debug-adapter-start"`

### Arguments
DebugUnresolvedAttachRemoteParams object Example:
```
{
    "hostName": "localhost",
    "port": 1234,
    "buildTarget": "metals",
}
```
```

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

### "debug-adapter-start" (DebugUnresolvedTestClassParams)

Source: https://scalameta.org/metals/docs/integrations/new-editor

Start a new debugger session by resolving a test suite by name and possibly target.

```APIDOC
## "debug-adapter-start"

### Description
Start a new debugger session by resolving a test suite by name and possibly target.

### Command
`"debug-adapter-start"`

### Arguments
DebugUnresolvedTestClassParams object Example:
```
{
   "testClass": "com.foo.FooSuite"
}
```
```

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

### RunScalafixRulesParams example for scalafix-run-only

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example of the RunScalafixRulesParams object for the scalafix-run-only command. It includes a textDocumentPositionParams with a file URI and position, and a rules array specifying which Scalafix rules to run.

```json
{
  
  "textDocumentPositionParams": {
    
    "textDocument": {
      
      "uri": "path/to/file.scala"
      
    },
    
    "position": {
      
      "line": 70,
      
      "character": 33
      
    }
    
  },
  
  "rules": ["ExplicitResultTypes"]
  
}
```

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

### customProjectRoot configuration

Source: https://scalameta.org/metals/docs/editors/user-configuration

Configuration example for the customProjectRoot setting. Specifies an optional relative path to the project's root. Set to "." to use the workspace root. The default is an empty string.

```json
{
  "metals": {
    "customProjectRoot": "backend/scalaProject/"
  }
}
```

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

### debug-adapter-start parameters for explicit test class

Source: https://scalameta.org/metals/docs/integrations/debug-adapter-protocol

JSON parameters for starting a debug session for an explicit test class. Includes optional `buildTarget`. A URI is returned that can be used by the DAP client.

```json
{
  "testClass": "com.foo.FooSuite",
  "buildTarget": "foo"
}
```

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

### build-connect

Source: https://scalameta.org/metals/docs/integrations/new-editor

Establishes a new connection to the build server and reindexes the workspace. This command can be helpful in scenarios when Metals feels unresponsive, for example when reopening Metals after the computer has been sleeping.

```APIDOC
## [workspace/executeCommand] build-connect

### Description
Establishes a new connection to the build server and reindexes the workspace. This command can be helpful in scenarios when Metals feels unresponsive, for example when reopening Metals after the computer has been sleeping.

### Command
`"build-connect"`

### Arguments
- **null** - Required - No arguments.

### Response
No response body is specified.
```

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

### autoImportBuilds configuration

Source: https://scalameta.org/metals/docs/editors/user-configuration

Configuration example for the autoImportBuilds setting. "initial" automatically imports a build when a project is first opened, "all" automates build imports after subsequent changes as well. The default is "off".

```json
{
  "metals": {
    "autoImportBuilds": all
  }
}
```

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

### file-decode jar URI

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example URI for the file-decode command with jar decoder. Use this to decode a file inside a sources jar.

```text
metalsDecode:jar:file:///somePath/someFile-sources.jar!/somePackage/someFile.java  

```

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

### "debug-adapter-start" (ScalaTestSuitesDebugRequest)

Source: https://scalameta.org/metals/docs/integrations/new-editor

Start a new debugger session for a test suite, can be used to run a single test case.

```APIDOC
## "debug-adapter-start"

### Description
Start a new debugger session for a test suite, can be used to run a single test case.

### Command
`"debug-adapter-start"`

### Arguments
ScalaTestSuitesDebugRequest object Example:
```
{
  "target": "metals"
  "requestData" : {
    "suites": ["com.foo.FooSuite"],
    "jvmOptions": [],
    "environmentVariables": [],
   }
}
```
```

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

### file-decode tasty URIs

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example URIs for the file-decode command with tasty decoder. Use these to decode .tasty files.

```text
metalsDecode:file:///somePath/someFile.scala.tasty-decoded  

metalsDecode:file:///somePath/someFile.tasty.tasty-decoded  

```

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

### defaultBspToBuildTool configuration

Source: https://scalameta.org/metals/docs/editors/user-configuration

Configuration example for the defaultBspToBuildTool setting. When true, Metals uses the build tool as the build server instead of Bloop if the build tool can serve as one. The default is false.

```json
{
  "metals": {
    "defaultBspToBuildTool": true
  }
}
```

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

### Don't generate Bloop plugin file for sbt

Source: https://scalameta.org/metals/docs/editors/user-configuration

When true, Metals will not generate `metals.sbt` files, assuming sbt-bloop is already manually installed. Build import will fail with a 'not valid command bloopInstall' error if Bloop is not manually installed. Defaults to `false`.

```json
{
  "metals": {
    "bloopSbtAlreadyInstalled": false
  }
}
```

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

### Configure inlayHints.implicitConversions.enable in Metals settings

Source: https://scalameta.org/metals/docs/editors/user-configuration

Disables inlay hints for implicit conversions. The default is false; this example sets it to false explicitly.

```json
{
  
  "metals": {  
    "inlayHints.implicitConversions.enable": false  
  }  
}  


```

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

### Configure inlayHints.hintsInPatternMatch.enable in Metals settings

Source: https://scalameta.org/metals/docs/editors/user-configuration

Disables inlay hints for pattern matches. The default is false; this example sets it to false explicitly.

```json
{
  
  "metals": {  
    "inlayHints.hintsInPatternMatch.enable": false  
  }  
}  


```

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

### Configure inlayHints.byNameParameters.enable in Metals settings

Source: https://scalameta.org/metals/docs/editors/user-configuration

Disables inlay hints for by-name parameters. The default is false; this example sets it to false explicitly.

```json
{
  
  "metals": {  
    "inlayHints.byNameParameters.enable": false  
  }  
}  


```

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

### Configure inlayHints.typeParameters.enable in Metals settings

Source: https://scalameta.org/metals/docs/editors/user-configuration

Disables inlay hints for type parameters. The default is false; this example sets it to false explicitly.

```json
{
  
  "metals": {  
    "inlayHints.typeParameters.enable": false  
  }  
}  


```

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

### Configure inlayHints.closingLabels.enable in Metals settings

Source: https://scalameta.org/metals/docs/editors/user-configuration

Disables closing label hints for methods/classes/objects. The default is false; this example sets it to false explicitly.

```json
{
  
  "metals": {  
    "inlayHints.closingLabels.enable": false  
  }  
}  


```

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

### Configure enableSemanticHighlighting in Metals settings

Source: https://scalameta.org/metals/docs/editors/user-configuration

Disables semantic tokens highlighting. The default is true; this example sets it to false.

```json
{
  
  "metals": {  
    "enableSemanticHighlighting": false  
  }  
}  


```

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

### enableBestEffort configuration

Source: https://scalameta.org/metals/docs/editors/user-configuration

Configuration example for the enableBestEffort setting. When using Scala 3, enables best effort compilation to improve Metals correctness when the workspace doesn't compile. The default is false.

```json
{
  "metals": {
    "enableBestEffort": true
  }
}
```

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

### Generate release notes draft with scala-cli

Source: https://scalameta.org/metals/docs/contributors/releasing

Install scala-cli and run the merged PRs script to generate a draft of release notes. The script requires two tags and a GitHub API token (basic token, no additional scopes) as arguments. Ensure the required tags are available, possibly by fetching them with `git fetch <main_fork> --tags`.

```bash
cs install scala-cli  

scala-cli ./bin/merged_prs.scala -- <tag1> <tag2> "<github_api_token>"  


```

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

### Configure inlayHints.namedParameters.enable in Metals settings

Source: https://scalameta.org/metals/docs/editors/user-configuration

Disables inlay hints for named parameters. The default is false; this example sets it to false explicitly.

```json
{
  
  "metals": {  
    "inlayHints.namedParameters.enable": false  
  }  
}  


```

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

### file-decode semanticdb URIs

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example URIs for the file-decode command with semanticdb decoder. Use these to decode semanticdb files in compact or detailed format.

```text
metalsDecode:file:///somePath/someFile.java.semanticdb-compact  

metalsDecode:file:///somePath/someFile.java.semanticdb-detailed  

metalsDecode:file:///somePath/someFile.scala.semanticdb-compact  

metalsDecode:file:///somePath/someFile.scala.semanticdb-detailed  

metalsDecode:file:///somePath/someFile.java.semanticdb.semanticdb-compact  

metalsDecode:file:///somePath/someFile.java.semanticdb.semanticdb-detailed  

metalsDecode:file:///somePath/someFile.scala.semanticdb.semanticdb-compact  

metalsDecode:file:///somePath/someFile.scala.semanticdb.semanticdb-detailed  

```

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

### Configure inlayHints.implicitArguments.enable in Metals settings

Source: https://scalameta.org/metals/docs/editors/user-configuration

Disables inlay hints for implicit arguments. The default is false; this example sets it to false explicitly.

```json
{
  
  "metals": {  
    "inlayHints.implicitArguments.enable": false  
  }  
}  


```

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

### verboseCompilation configuration

Source: https://scalameta.org/metals/docs/editors/user-configuration

Configuration example for the verboseCompilation setting. When true, build servers like Bloop or Scala CLI will include all possible debugging information, including incremental compilation details in Zinc. The default is false.

```json
{
  "metals": {
    "verboseCompilation": true
  }
}
```

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

### file-decode javap URIs

Source: https://scalameta.org/metals/docs/integrations/new-editor

Example URIs for the file-decode command with javap decoder. Use these to decode .java, .scala, or .class files, with optional -verbose suffix for more detailed output.

```text
metalsDecode:file:///somePath/someFile.java.javap  

metalsDecode:file:///somePath/someFile.scala.javap  

metalsDecode:file:///somePath/someFile.class.javap  

metalsDecode:file:///somePath/someFile.java.javap-verbose  

metalsDecode:file:///somePath/someFile.scala.javap-verbose  

metalsDecode:file:///somePath/someFile.class.javap-verbose  

```

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

### testUserInterface configuration

Source: https://scalameta.org/metals/docs/editors/user-configuration

Configuration example for the testUserInterface setting. Valid values are "code lenses" and "test explorer". The default is "code lenses".

```json
{
  "metals": {
    "testUserInterface": test explorer
  }
}
```

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

### Enable closing label hints (inlayHints.closingLabels.enable)

Source: https://scalameta.org/metals/docs/integrations/new-editor

When true, method/class/object definitions using braces syntax get a closing label hint next to the closing brace with the definition name. Default is false.

```json
{
  "metals": {
    "inlayHints.closingLabels.enable": false
  }
}
```

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

### Enable intermediate type hints for multi-line expressions (inlayHints.hintsXRayMode.enable)

Source: https://scalameta.org/metals/docs/integrations/new-editor

When true, each method/attribute call in a multi-line chain gets its own type annotation. Default is false.

```json
{
  "metals": {
    "inlayHints.hintsXRayMode.enable": false
  }
}
```

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

### Configure inlayHints.hintsXRayMode.enable in Metals settings

Source: https://scalameta.org/metals/docs/editors/user-configuration

Disables inlay hints for intermediate types of multi-line expressions. The default is false; this example sets it to false explicitly.

```json
{
  
  "metals": {  
    "inlayHints.hintsXRayMode.enable": false  
  }  
}  


```

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

### Configure inlayHints.inferredTypes.enable in Metals settings

Source: https://scalameta.org/metals/docs/editors/user-configuration

Disables inlay hints for inferred types. The default is false; this example sets it to false explicitly.

```json
{
  
  "metals": {  
    "inlayHints.inferredTypes.enable": false  
  }  
}  


```

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

### .bsp/bazelbsp.json Bazel BSP server configuration

Source: https://scalameta.org/metals/docs/build-tools/bazel

The .bsp/bazelbsp.json file generated by Metals to start the Bazel BSP server. Contains the server initializer class, workspace paths, and supported languages. The version and bspVersion fields are specific to the Bazel BSP server.

```json
{  
  "name": "bazelbsp",  
  "argv": [  
    "/usr/lib/jvm/graal17/bin/java",  
    "-classpath",  
    "<classpath on your machine>",  
    "org.jetbrains.bsp.bazel.server.ServerInitializer",  
    "/path/to/workspace",  
    "/path/to/workspace/projectview.bazelproject",  
    "false"  
  ],  
  "version": "3.1.0-20240130-33760f0-NIGHTLY",  
  "bspVersion": "2.1.0",  
  "languages": [  
    "scala",  
    "java",  
    "kotlin"  
  ]  
}  


```

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

### Apply Bloop plugin to all projects

Source: https://scalameta.org/metals/docs/build-tools/gradle

Enable the Bloop plugin for all projects in the Gradle build by applying it in the 'allprojects' block. This is part of the manual installation process.

```groovy
allprojects {  

   apply plugin: bloop.integrations.gradle.BloopPlugin  

}  

```

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

### Configure bloopJvmProperties in Metals settings

Source: https://scalameta.org/metals/docs/editors/user-configuration

Passes JVM properties to the Bloop server. The default is ["-Xmx1G"]; this example sets the same value explicitly.

```json
{
  
  "metals": {  
    "bloopJvmProperties": ["-Xmx1G"]  
  }  
}  


```

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

### Push release tag to trigger release workflow

Source: https://scalameta.org/metals/docs/contributors/releasing

Check the remote configuration and push the release tag to the main fork to trigger the release workflow. The example shows a remote named `primary` pointing to the scalameta/metals repository and pushing tag `v1.0.0`.

```bash
> git remote -v  

primary	git@github.com:scalameta/metals.git (fetch)  

primary	git@github.com:scalameta/metals.git (push)  

> git push primary v1.0.0  


```

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

### Tail LSP trace file on Linux/macOS

Source: https://scalameta.org/metals/docs/contributors/getting-started

Watch the JSON-RPC trace file for the text editor after starting Metals. The traces are very verbose, so delete the files if you are not debugging JSON communication.

```bash
# Linux and macOS  

tail -f $WORKSPACE/.metals/lsp.trace.json  


```

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

### scalaCliLauncher configuration

Source: https://scalameta.org/metals/docs/editors/user-configuration

Configuration example for the scalaCliLauncher setting. Specifies an optional absolute path to a scala-cli executable for running a Scala CLI BSP server. By default, Metals uses scala-cli from PATH or downloads and runs it on the JVM. The default is an empty string.

```json
{
  "metals": {
    "scalaCliLauncher": "/usr/local/bin/scala-cli"
  }
}
```

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

### javaFormat.eclipseProfile configuration

Source: https://scalameta.org/metals/docs/editors/user-configuration

Configuration example for the javaFormat.eclipseProfile setting. Controls which profile is used when the Eclipse formatter file contains more than one profile. The default is an empty string.

```json
{
  "metals": {
    "javaFormat.eclipseProfile": "GoogleStyle"
  }
}
```

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

### javaFormat.eclipseConfigPath configuration

Source: https://scalameta.org/metals/docs/editors/user-configuration

Configuration example for the javaFormat.eclipseConfigPath setting. Specifies an optional custom path to the eclipse-formatter.xml file. Use forward slashes for file separators even on Windows. The default is an empty string.

```json
{
  "metals": {
    "javaFormat.eclipseConfigPath": "formatters/eclipse-formatter.xml"
  }
}
```

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

### enableIndentOnPaste configuration

Source: https://scalameta.org/metals/docs/editors/user-configuration

Configuration example for the enableIndentOnPaste setting. When enabled, Metals adjusts the indentation of pasted snippets to match the current cursor position. The default is false.

```json
{
  "metals": {
    "enableIndentOnPaste": false
  }
}
```

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

### sbt error: Not valid key: metalsEnable

Source: https://scalameta.org/metals/docs/build-tools/sbt

This error indicates an old version of sbt-metals is installed in your build. Remove any usage of sbt-metals from your build to resolve it.

```text
[error] Not a valid key: metalsEnable (similar: scalafixEnabled)  

[error] metalsEnable  

[error]             ^  



```

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

### fallbackScalaVersion configuration

Source: https://scalameta.org/metals/docs/editors/user-configuration

Configuration example for the fallbackScalaVersion setting. This version is used as the default or fallback when a file doesn't belong to a build target or the specified Scala version isn't supported. The default is 3.3.8.

```json
{
  "metals": {
    "fallbackScalaVersion": 3.3.8
  }
}
```

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

### Worksheet scalac options using directive

Source: https://scalameta.org/metals/docs/editors/emacs

Import scalac options in a worksheet using the special `$$scalac` import. This example enables the -Ywarn-unused compiler option.

```scala
//> using options -Ywarn-unused  

  

```

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

### defaultShell configuration

Source: https://scalameta.org/metals/docs/editors/user-configuration

Configuration example for the defaultShell setting. Specifies an optional absolute path to a shell executable used for build operations. The configured shell is used for all build-related subprocesses. The default is an empty string.

```json
{
  "metals": {
    "defaultShell": /usr/bin/fish
  }
}
```

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

### Bootstrap Metals with JVM options

Source: https://scalameta.org/metals/docs/integrations/new-editor

Recommended command to enable JVM string de-duplication and provide generous stack size and memory options. This is optional but recommended.

```bash
coursier bootstrap \
  --java-opt -XX:+UseG1GC \
  --java-opt -XX:+UseStringDeduplication  \
  --java-opt -Xss4m \
  --java-opt -Xms100m \
  org.scalameta:metals_2.13:1.6.8 -o metals -f  
```

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

### Install sbt-bloop plugin in sbt

Source: https://scalameta.org/metals/docs/build-tools/sbt

Add the sbt-bloop plugin to your sbt build. Place this in a global plugins.sbt file or in your project's project/plugins.sbt. The resolver is required to fetch the plugin snapshot.

```scala
// One of:  

//   ~/.sbt/0.13/plugins/plugins.sbt  

//   ~/.sbt/1.0/plugins/plugins.sbt  

resolvers += "central-snapshots" at "https://central.sonatype.com/repository/maven-snapshots/"  

  

addSbtPlugin("ch.epfl.scala" % "sbt-bloop" % "2.1.2")  



```

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

### Configure bloopVersion in Metals settings

Source: https://scalameta.org/metals/docs/editors/user-configuration

Sets the Bloop version used by Metals for importing and running the embedded server. The default is 2.1.2; this example overrides it to 1.4.0-RC1.

```json
{
  
  "metals": {  
    "bloopVersion": "1.4.0-RC1"  
  }  
}  


```

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

### Set Bloop version (bloopVersion)

Source: https://scalameta.org/metals/docs/integrations/new-editor

Specifies the Bloop version used for the build tool plugin and embedded server. Default is 2.1.2. Example shows version 1.4.0-RC1.

```json
{
  "metals": {
    "bloopVersion": "1.4.0-RC1"
  }
}
```

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

### Set Bloop JVM properties (bloopJvmProperties)

Source: https://scalameta.org/metals/docs/integrations/new-editor

Optional list of JVM properties passed to the Bloop server. Format follows the Bloop server reference guide. Default is ["-Xmx1G"].

```json
{
  "metals": {
    "bloopJvmProperties": ["-Xmx1G"]
  }
}
```

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

### Configure superMethodLensesEnabled in Metals settings

Source: https://scalameta.org/metals/docs/editors/user-configuration

Disables super method lenses, which are visible above method definitions that override another method. The default is false; this example sets it to false explicitly.

```json
{
  
  "metals": {  
    "superMethodLensesEnabled": false  
  }  
}  


```

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

### Open LspSuite test workspace in VS Code

Source: https://scalameta.org/metals/docs/contributors/getting-started

Opens the generated workspace directory for a failing LspSuite test in Visual Studio Code. For example, for the test case `"deprecated-scala"` in `WarningsLspSuite`, run this command to manually investigate the failure.

```bash
code tests/unit/target/e2e/warnings/deprecated-scala  
```

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

### Example testResult event forwarded to the client

Source: https://scalameta.org/metals/docs/integrations/test-explorer

Shows the JSON structure of a testResult event sent from the BSP server to the DAP client after a test run. It includes suite name, duration, and an array of test results with kind (passed/failed), test name, duration, and optional error message.

```json
{
  "type": "event",
  "seq": 20,
  "event": "testResult",
  "body": {
    "category": "testResult",
    "data": {
      "suiteName": "a.JunitTestSuite",
      "duration": 195,
      "tests": [
        {
          "kind": "failed",
          "testName": "a.JunitTestSuite.test1",
          "duration": 135,
          "error": "* a.JunitTestSuite.test1 - java.lang.AssertionError: assertion failed: should equal be true"
        },
        {
          "kind": "passed",
          "testName": "a.JunitTestSuite.test2",
          "duration": 60
        }
      ]
    },
    "type": "testResult"
  }
}
```

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

### launch.json configuration for Metals debugging

Source: https://scalameta.org/metals/docs/editors/vscode

Sample .vscode/launch.json with configurations for launching a main class, launching a test class, and attaching a debugger. The buildTarget key is optional and needed when there are multiple classes with the same name or when launching from outside the project.

```json
{
  "version": "0.2.0",
  "configurations": [
    // Main class configuration
    {
      "type": "scala",
      "request": "launch",
      // configuration name visible for the user
      "name": "Launch Main",
      // full name of the class to run
      "mainClass": "com.example.Main",
      // optional arguments for the main class
      "args": [],
      // optional jvm properties to use
      "jvmOptions": []
    },
    // Test class configuration
    {
      "type": "scala",
      "request": "launch",
      // configuration name visible for the user
      "name": "Launch Test",
      // full name of the class to run
      "testClass": "com.example.Test"
    },
    // Attach debugger when running via:
    // `-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=localhost:5005`
    {
      "type": "scala",
      "request": "attach",
      "name": "Attach debugger",
      // name of the module that is being debugging
      "buildTarget": "root",
      // Host of the jvm to connect to
      "hostName": "localhost",
      // Port to connect to
      "port": 5005
    }
  ]
}
```

```json
"buildTarget": "root"
```

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

### compile-target

Source: https://scalameta.org/metals/docs/integrations/new-editor

Compiles the currently open file. Can be used as an explicit command in order to force compilation to start and finish e.g. before executing a codeLens. Returns CompileResult with field 'statusCode' being 1 for success, 2 for errors or 3 for compile cancelled.

```APIDOC
## [workspace/executeCommand] compile-target

### Description
Compiles the currently open file. Can be used as an explicit command in order to force compilation to start and finish e.g. before executing a codeLens. Returns CompileResult with field 'statusCode' being 1 for success, 2 for errors or 3 for compile cancelled.

### Command
`"compile-target"`

### Arguments
- **BuildTargetIdentifier** - Required - The build target identifier.

### Response
Returns CompileResult with field 'statusCode' being 1 for success, 2 for errors or 3 for compile cancelled.
```

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

### Add Bloop plugin dependency to buildscript

Source: https://scalameta.org/metals/docs/build-tools/gradle

Add the Bloop plugin classpath to the buildscript dependencies in the Gradle build file. This is required for manual installation of Bloop in highly customized workspaces.

```groovy
buildscript {  

    repositories {  

        mavenCentral()  

    }  

    dependencies {  

        classpath 'ch.epfl.scala:gradle-bloop_2.12:2.1.2'  

    }  

}  

```

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

### "sources-scan"

Source: https://scalameta.org/metals/docs/integrations/new-editor

Walk all files in the workspace and index where symbols are defined. Is automatically run once after `initialized` notification and incrementally updated on file watching events. A language client that doesn't support file watching can run this manually instead. It should not be much slower than walking the entire file tree and reading `*.scala` files to string, indexing itself is cheap.

```APIDOC
## "sources-scan"

### Description
Walk all files in the workspace and index where symbols are defined. Is automatically run once after `initialized` notification and incrementally updated on file watching events. A language client that doesn't support file watching can run this manually instead. It should not be much slower than walking the entire file tree and reading `*.scala` files to string, indexing itself is cheap.

### Command
`"sources-scan"`

### Arguments
`null`
```

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

### "file-decode"

Source: https://scalameta.org/metals/docs/integrations/new-editor

Decode a file into a human readable format. Compilation involves various binary files that can't be read directly in a text editor so they need to be decoded into a human readable format. Examples include `.class` and `.semanticdb`.

```APIDOC
## "file-decode"

### Description
Decode a file into a human readable format. Compilation involves various binary files that can't be read directly in a text editor so they need to be decoded into a human readable format. Examples include `.class` and `.semanticdb`.

### Command
`"file-decode"`

### Arguments
- **uri** (string) - Required - URI of the file with any parameters required for decoding. Examples:
  - javap: `metalsDecode:file:///somePath/someFile.java.javap`, `metalsDecode:file:///somePath/someFile.scala.javap`, `metalsDecode:file:///somePath/someFile.class.javap`, `metalsDecode:file:///somePath/someFile.java.javap-verbose`, `metalsDecode:file:///somePath/someFile.scala.javap-verbose`, `metalsDecode:file:///somePath/someFile.class.javap-verbose`
  - semanticdb: `metalsDecode:file:///somePath/someFile.java.semanticdb-compact`, `metalsDecode:file:///somePath/someFile.java.semanticdb-detailed`, `metalsDecode:file:///somePath/someFile.scala.semanticdb-compact`, `metalsDecode:file:///somePath/someFile.scala.semanticdb-detailed`, `metalsDecode:file:///somePath/someFile.java.semanticdb.semanticdb-compact`, `metalsDecode:file:///somePath/someFile.java.semanticdb.semanticdb-detailed`, `metalsDecode:file:///somePath/someFile.scala.semanticdb.semanticdb-compact`, `metalsDecode:file:///somePath/someFile.scala.semanticdb.semanticdb-detailed`
  - tasty: `metalsDecode:file:///somePath/someFile.scala.tasty-decoded`, `metalsDecode:file:///somePath/someFile.tasty.tasty-decoded`
  - jar: `metalsDecode:jar:file:///somePath/someFile-sources.jar!/somePackage/someFile.java`
  - build target: `metalsDecode:file:///workspacePath/buildTargetName.metals-buildtarget`

### Response
```
interface DecoderResponse {
  requestedUri: string;
  value?: string;
  error?: string
}
```
```

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

### Enable implicit conversion hints (inlayHints.implicitConversions.enable)

Source: https://scalameta.org/metals/docs/integrations/new-editor

When true, places where implicit methods or classes are used display them as decorations or in hover. Default is false.

```json
{
  "metals": {
    "inlayHints.implicitConversions.enable": false
  }
}
```

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

### compile-cascade

Source: https://scalameta.org/metals/docs/integrations/new-editor

Compiles the current open files along with all build targets in this workspace that depend on those files. By default, Metals compiles only the current build target and its dependencies when saving a file. Run the cascade compile task to additionally compile the inverse dependencies of the current build target. For example, if you change the API in main sources and run cascade compile then it will also compile the test sources that depend on main.

```APIDOC
## [workspace/executeCommand] compile-cascade

### Description
Compiles the current open files along with all build targets in this workspace that depend on those files. By default, Metals compiles only the current build target and its dependencies when saving a file. Run the cascade compile task to additionally compile the inverse dependencies of the current build target. For example, if you change the API in main sources and run cascade compile then it will also compile the test sources that depend on main.

### Command
`"compile-cascade"`

### Arguments
- **null** - Required - No arguments.

### Response
No response body is specified.
```

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

### Create JSON-RPC trace files for Linux/macOS and Windows

Source: https://scalameta.org/metals/docs/contributors/getting-started

Create empty trace files in $WORKSPACE/.metals/ to enable JSON-RPC tracing for the text editor, build server, and debug adapter. The Linux/macOS commands use touch; the Windows commands use type nul. Using $WORKSPACE/.metals/ avoids shared trace files in the machine cache directory.

```bash
# Linux and macOS  

touch $WORKSPACE/.metals/lsp.trace.json # text editor  

touch $WORKSPACE/.metals/bsp.trace.json # build server  

touch $WORKSPACE/.metals/dap-server.trace.json # debug adapter  

touch $WORKSPACE/.metals/dap-client.trace.json # debug adapter  


```

```bash
# Windows  

type nul > $WORKSPACE/.metals/lsp.trace.json # text editor  

type nul > $WORKSPACE/.metals/bsp.trace.json # build server  

type nul > $WORKSPACE/.metals/dap-server.trace.json # debug adapter  

type nul > $WORKSPACE/.metals/dap-client.trace.json # debug adapter  


```

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

### Preprocess Markdown files with sbt docs/run -w

Source: https://scalameta.org/metals/docs/contributors/updating-website

Run this command from the repository root to preprocess Markdown files in the docs/ directory. The -w flag watches for changes and regenerates files automatically.

```bash
sbt  

docs/run -w  


```

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

### debug-adapter-start parameters for Metals discovery

Source: https://scalameta.org/metals/docs/integrations/debug-adapter-protocol

JSON parameters for Metals discovery. Uses `runType` of `"run"`, `"runOrTestFile"`, `"testFile"`, or `"testTarget"` and a file URI. Optional `args`, `jvmOptions`, `env`, and `envFile` are also valid.

```json
{
  "path": "file:///path/to/my/file.scala",
  "runType": "testTarget"
}
```

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

### Run a Test Class

Source: https://scalameta.org/metals/docs/features/mcp

Use the MCP tool to run a specific test class.

```text
Using MCP, run the test class com.example.MyServiceSpec
```