Metals

https://scalameta.org/metals/docs/
Admin
Metals is a Scala language server that provides rich IDE features including code completion,...
Tokens:77,774
Snippets:739
Trust Score:9.6
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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" (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  
```

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

### "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"
}
```
```

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

### 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/"
  }
}
```

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

### 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  

```

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

### 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.
```

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

### 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": [],
   }
}
```
```

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

### 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
  }
}
```

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

### 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  

```
Tokens:
Raw