Integrating with Pkl Language Server

Pkl Language Server is a low-level tool that is meant to be integrated with editors by way of plugins.

The documentation below is intended for plugin implementors.

Distribution

Pkl Language Server is published to Maven Central, and also as releases on GitHub.

It is recommended that the jar file be bundled into an editor plugin’s package contents.

Running Pkl Language Server

To run the server, provide the jar as an argument to Java. For example:

java -jar path/to/pkl-lsp.jar

Pkl Language Server requires Java 22 or higher.

We plan on providing native binaries in the future.

Follow #60 to stay updated on its progress.

`pkl-lsp` URI scheme

The server uses the pkl-lsp scheme to represent sources from the standard library, as well as other types of non-file Pkl sources.

For example, the pkl:base standard library module is surfaced to editors as URI pkl-lsp://stdlib/base.pkl.

Custom client options

When starting the server, additional client options can be provided to configure the behavior of the language server.

These options are provided in the initializationOptions section of the Initialize Request.

`renderOpenFileCommandInDocs`

Type: Boolean

Cause the server to render links within documentation using the command:pkl.open.file URI.

If enabled, clients are expected to implement the command pkl.open.file.

`extendedClientCapabilities`

Tell the server that the client supports additional capabilities made available by Pkl Language Server.

Name Description

Name	Description
`actionableRuntimeNotifications`	The client supports the `pkl/actionableNotification` message.
`pklConfigureCommand`	The client supports the `pkl.configure` command.

actionableRuntimeNotifications

The client supports the pkl/actionableNotification message.

pklConfigureCommand

The client supports the pkl.configure command.

Pkl CLI configuration

To support flows like sync projects, and package downloading, the server will look for a path to the Pkl CLI.

By default, the server will look for the CLI within the environment’s $PATH.

If the client supports the Configuration Request, it will look for the configuration value pkl.cli.path at scope Pkl.

Additional message types

Pkl Language Server extends the Language Server Protocol with custom message types.

These message types are optional, and enhance the integration with an editor.

File Contents Request

Method: pkl/fileContents

Body: TextDocumentIdentifier

Read text contents of the document identified by the specified params..

Download Package Request

Method: pkl/downloadPackage

Body: String

Download the specified package.

Sync Projects Request

Method: pkl/syncProjects

Body: Any

Sync any PklProject defined in the workspace. This allows the server to understand imports declared using dependency notation.

Commands

The following commands can optionally be implemented. If implemented, and the capability is made known to Pkl Language Server, the server will issue Execute Command requests.

Name Arguments Description

Name	Arguments	Description
`pkl.open.file`	`[uri: String, line: Int?, column: Int?]`	Send a File Contents Request to Pkl Language Server, and open the resulting contents in an editor pane at the indicated line and column.
`pkl.syncProjects`	`<none>`	Send a Sync Projects Request to Pkl Language Server.
`pkl.configure`	`[configurationPath: string]`	Open the editor’s settings/configuration panel at the configuration path.
`pkl.downloadPackage`	`[packageUri: string]`	Send a Download Package Request to Pkl Language Server.

pkl.open.file

[uri: String, line: Int?, column: Int?]

Send a File Contents Request to Pkl Language Server, and open the resulting contents in an editor pane at the indicated line and column.

pkl.syncProjects

<none>

Send a Sync Projects Request to Pkl Language Server.

pkl.configure

[configurationPath: string]

Open the editor’s settings/configuration panel at the configuration path.

pkl.downloadPackage

[packageUri: string]

Send a Download Package Request to Pkl Language Server.