Launching JETLS

This guide explains how to launch the JETLS language server using jetls serve and describes the available communication channels.

The jetls executable

The jetls executable is the main entry point for JETLS, providing three commands:

• jetls serve - Start the language server for editor integration (this page)
• jetls check - Run diagnostics from the command line
• jetls schema - Print JSON Schema for JETLS configuration

The executable can be installed as an executable app via Pkg.jl:

julia -e 'using Pkg; Pkg.Apps.add(; url="https://github.com/aviatesk/JETLS.jl", rev="release")'

jetls serve --help

jetls serve - Start language server for editor integration

Starts JETLS as an LSP server for use with LSP client editors.
By default, communicates via stdin/stdout.

Usage: jetls serve [OPTIONS]

Options:
  --stdio                     Use standard input/output (default)
  --pipe-connect=<path>       Connect to client's Unix domain socket/named pipe
  --pipe=<path>               Alias for --pipe-connect (LSP client convention)
  --pipe-listen=<path>        Listen on Unix domain socket/named pipe
  --socket=<port>             Listen on TCP socket
  --clientProcessId=<pid>     Monitor client process (enables crash detection)
  --help, -h                  Show this help message

Examples:
  jetls serve
  jetls serve --pipe-listen=/tmp/jetls.sock
  jetls serve --socket=8080

Communication channels

jetls serve supports multiple communication channels between the client and server. Choose based on your environment and requirements:

pipe-connect / pipe-listen (Unix domain socket / named pipe)

• Advantages: Complete isolation from stdin/stdout, preventing protocol corruption; fastest for local communication
• Best for: Local development, Remote SSH, WSL
• Limitations: Not suitable for cross-container communication
• Note: Client is responsible for socket file cleanup in both modes

jetls serve provides two pipe modes:

pipe-connect

Server connects to a client-created socket. This is the mode used by the jetls-client VSCode extension and is generally easier to implement:

• Client creates and listens on the socket first
• Client spawns the server process
• Server immediately connects to the client's socket
• No stdout monitoring required - simpler client implementation

Example:

jetls serve --pipe-connect=/tmp/jetls.sock

--pipe=<path> is accepted as an alias for --pipe-connect=<path>. This matches the flag convention stock LSP clients use for their pipe transport (e.g. vscode-languageclient spawns the server with --pipe=<name>).

pipe-listen

Server creates and listens on a socket, then waits for the client to connect. This is the traditional LSP server mode:

• Client spawns the server process
• Server creates socket and prints <JETLS-PIPE-READY>/tmp/jetls.sock</JETLS-PIPE-READY> to stdout
• Client must monitor stdout for the readiness notification
• Client connects to the socket after receiving notification

Example:

jetls serve --pipe-listen=/tmp/jetls.sock

socket (TCP)

• Advantages: Complete isolation from stdin/stdout, preventing protocol corruption; works across network boundaries; supports port forwarding
• Best for: Manual remote connection across different machines (without VSCode Remote); shared server accessed by multiple developers
• Limitations: May require firewall configuration; potentially less secure than local alternatives

Example:

jetls serve --socket=7777

The server will print <JETLS-PORT>7777</JETLS-PORT> to stdout once it starts listening. This is especially useful when using --socket=0 for automatic port assignment, as the actual port number will be announced:

jetls serve --socket=0
# Output: <JETLS-PORT>54321</JETLS-PORT>  (actual port assigned by OS)

Use with SSH port forwarding to connect from a different machine:

ssh -L 8080:localhost:8080 user@remote
# Then connect your local client to localhost:8080

stdio

• Advantages: Simplest setup; maximum compatibility; works everywhere
• Best for: Dev containers; environments where pipe doesn't work
• Limitations: Risk of protocol corruption if any code writes to stdin/stdout

Example:

jetls serve --stdio
# or simply
jetls serve

Client process monitoring

The --clientProcessId option enables the server to monitor the client process for crash detection, where the server periodically checks whether the specified process is still alive. If the client crashes or terminates unexpectedly, the server will automatically shut down, ensuring proper cleanup even when the client cannot execute the normal LSP shutdown sequence.

Initialization options

JETLS accepts static initialization options that are set once at server startup and require a server restart to take effect. Unlike dynamic configuration that can be changed at runtime, these options configure fundamental server behavior.

Schema

A JSON Schema for initialization options is available. See the JSON Schema section for download links.

How to configure initialization options

Initialization options can be configured via:

• Editor-specific settings
• The [initialization_options] section in .JETLSConfig.toml

When both sources are present, file-based configuration takes precedence (file > client > default), as like JETLS configuration priority.

File-based configuration

Configure initialization options in .JETLSConfig.toml at your project root:

[[initialization_options.analysis_overrides]]
path = "test/fixtures/**"

This method is client-agnostic and can be easily committed to version control.

Client configuration

The method and format for specifying initialization options varies by editor. Consult your editor's documentation on how to configure LSP initialization options. Below are examples for VSCode and Zed.

If your editor does not support specifying initialization options, use the file-based configuration instead.

VSCode (jetls-client extension)

Configure initialization options in VSCode's settings.json:

{
  "jetls-client.initializationOptions": {
    "analysis_overrides": [
      {
        "path": "test/fixtures/**"
      }
    ]
  }
}

Zed (aviatesk/zed-julia extension)

Configure initialization options in Zed's settings.json:

{
  "lsp": {
    "JETLS": {
      "initialization_options": {
        "analysis_overrides": [
          {
            "path": "test/fixtures/**"
          }
        ]
      }
    }
  }
}

Options reference

• analysis_overrides
• reuse_native_inference
• configuration_section

analysis_overrides

• Type: array of tables
• Default: []

Excludes the matched files from full analysis. This is primarily a workaround for the known memory leak, where memory usage grows with each re-analysis: excluding the files that trigger the heaviest analysis keeps the server usable until the leak is fixed.

Each entry requires a path field: a glob pattern selecting the files to exclude. Patterns are matched against file paths relative to the workspace root, and ** matches directories recursively. Use / as the separator on all platforms, including Windows; backslashes are not interpreted as separators.

# exclude test fixtures entirely
[[initialization_options.analysis_overrides]]
path = "test/fixtures/**"

Save-time diagnostics produced by full analysis, including toplevel diagnostics and inference diagnostics, are unavailable for the matched files.

Features that do not require full analysis keep working. These include completion, hover, inlay hints, and syntax diagnostics. Context-independent lowering diagnostics also remain available, while context-dependent diagnostics such as lowering/macro-expansion-error and lowering/undef-global-var are unavailable. Hover and type inlay hints infer the current top-level form on demand, but their results may be incomplete because full analysis does not establish a module context for the matched files.

reuse_native_inference

• Type: boolean
• Default: false

When enabled, calls to methods defined outside the modules being analyzed reuse results from Julia's native inference cache instead of being analyzed recursively.

This may substantially speed up full analysis of packages with large dependencies. The reused results come from the dependencies' precompiled images, so the speedup requires those dependencies to be precompiled, and grows with how much of their code precompilation covers. Packages whose analysis time is dominated by their own code see little change, while those that spend much of it in dependencies can become several times faster.

[initialization_options]
reuse_native_inference = true

Analysis results may change slightly when this option is enabled, since the reused results come from Julia's compiler rather than the JETLS analyzer, and that can change the diagnostics that are reported. Diagnostics for the modules being analyzed are unaffected in practice, but this remains an experimental option that may be removed or changed in future releases.

configuration_section

• Type: string
• Default: unset

A contract for language client implementors rather than for users: the client declares the configuration section it stores JETLS settings under (e.g. "jetls-client.settings" for the VSCode extension), and JETLS then registers workspace/didChangeConfiguration with that section so the client only sends the notification when the relevant settings actually change. When unset, the notification is registered without a section filter.