Configuration

Catenary loads configuration from multiple sources, in order of priority (last one wins):

1. Defaults: idle_timeout = 300.
2. User Config: ~/.config/catenary/config.toml.
3. Project Config: .catenary.toml in the current directory or any parent directory (searches upwards).
4. Explicit File: Specified via --config <path>.
5. Environment Variables: Prefixed with CATENARY_ (e.g., CATENARY_IDLE_TIMEOUT=600).
6. CLI Arguments: --lsp and --idle-timeout.

Basic Structure

# Global settings
idle_timeout = 300  # Seconds before closing idle documents (0 to disable)

# Language servers
[server.<language-id>]
command = "server-binary"
args = ["arg1", "arg2"]

JSON Schema

A JSON schema is available in the repository at catenary-config.schema.json. You can use this to get autocompletion and validation in editors like VS Code.

To use it in VS Code, add this to your settings.json:

"yaml.schemas": {
  "https://raw.githubusercontent.com/MarkWells-Dev/Catenary/main/catenary-config.schema.json": [".catenary.toml", "catenary.toml"]
}

(Note: Requires the YAML extension which also handles TOML schemas in some versions, or use a dedicated TOML extension that supports $schema comments).

Example Config

idle_timeout = 300

[server.rust]
command = "rust-analyzer"

[server.rust.initialization_options]
check.command = "clippy"

[server.python]
command = "pyright-langserver"
args = ["--stdio"]

[server.typescript]
command = "typescript-language-server"
args = ["--stdio"]

[server.javascript]
command = "typescript-language-server"
args = ["--stdio"]

[server.go]
command = "gopls"

[server.php]
command = "php-language-server"

Initialization Options

Each server can receive custom initialization_options that are passed to the LSP server during the initialize request. These are server-specific settings that configure the server’s behavior.

[server.rust]
command = "rust-analyzer"

[server.rust.initialization_options]
check.command = "clippy"
cargo.features = "all"

Refer to your language server’s documentation for available options.

Language IDs

The [server.<language-id>] key must match the LSP language identifier. Catenary detects these based on file extension and some common filenames:

Global Options

CLI Override

You can also specify servers via CLI:

catenary --lsp "rust:rust-analyzer" --lsp "python:pyright-langserver --stdio"

Verifying Your Setup

Use catenary doctor to check that configured language servers are working:

catenary doctor

For each configured server, doctor reports one of:

Ready servers also list which Catenary tools they support (e.g. hover, definition, references), based on the capabilities the server reports during initialization.

Use --nocolor to disable colored output, or --root to check a different workspace:

catenary doctor --root /path/to/project