Langium CLI

4.2.1 verified Thu Apr 23 auth: no javascript

The Langium CLI (`langium-cli`) is the command-line interface for the Eclipse Langium framework, a powerful toolset for building domain-specific languages (DSLs) with full language server protocol (LSP) support. Currently at stable version 4.2.1, it follows a regular release cadence with minor versions released every few months and major versions annually or as significant breaking changes necessitate. Its primary function is to generate the core language infrastructure—including parsers, ASTs, and language server components—from a Langium grammar definition file. It differentiates itself by deeply integrating with TypeScript and VS Code, providing a robust foundation for creating custom programming languages and their development tooling efficiently, without manual boilerplate code generation. The CLI requires a configuration file, `langium-config.json`, to specify language details, grammar paths, and output targets for various artifacts like TextMate syntax highlighting, Monarch syntax highlighting, Prism syntax highlighting, and railroad diagrams.

Common errors

error Error: langium-config.json not found in the current directory or specified path. ↓

cause The `langium generate` command could not locate the required configuration file.

fix

Create a langium-config.json file in your project root, or specify its path using langium generate -f <path/to/config.json>.

error Error: 'langium' is not recognized as an internal or external command, operable program or batch file. ↓

cause The `langium-cli` package is not installed globally or not found in the local `node_modules/.bin` directory.

fix

Use npx langium-cli <command> to execute it without global installation, or install globally with npm install -g langium-cli.

error Error: Command failed with exit code 1: langium generate ↓

cause A general error occurred during the generation process, often due to an invalid grammar, malformed configuration, or issues with output directory permissions.

fix

Inspect the console output for more specific error messages from the Langium generator. Verify your .langium grammar file for syntax errors and ensure langium-config.json is correctly structured and paths are valid.

Warnings

breaking Langium v4.0.0 introduced significant breaking changes in the core API, particularly for how language services are initialized. Custom language services or extensions built directly on Langium's API might require refactoring. ↓

fix Review the Langium v4.0.0 changelog for detailed migration steps, focusing on `createDefaultModule` replacements (`createDefaultLangiumCoreServices`, `createDefaultLangiumGrammarServices`) and updates to `CstNode.fullText` usage.

breaking The `langium-cli` package, along with the core Langium framework, now requires Node.js version 20.10.0 or higher and npm version 10.2.3 or higher. Older Node.js or npm versions are no longer supported. ↓

fix Upgrade your Node.js environment to >=20.10.0 and npm to >=10.2.3 using a tool like nvm (Node Version Manager) or by updating your system's Node.js installation.

gotcha Incorrect or missing `langium-config.json` file can lead to failed code generation or unexpected behavior. The CLI relies heavily on this configuration for identifying grammars, output paths, and generating various artifacts. ↓

fix Ensure a valid `langium-config.json` exists in your project root or is specified via the `--file` option. Refer to the Langium documentation for the correct schema and example configurations.

gotcha When developing with `langium-cli generate --watch`, changes to grammar files will trigger regeneration. However, changes to other parts of your project (e.g., custom language server logic) may require a manual rebuild of your TypeScript project. ↓

fix Run `npm run build` or your project's TypeScript compilation command after making changes to non-grammar source files. The `--watch` flag only applies to grammar regeneration.

Install

npm install langium-cli

yarn add langium-cli

pnpm add langium-cli

Imports

generateAction
```
import { generateAction } from 'langium-cli'
```
While langium-cli is primarily a command-line tool, this symbol is hypothesized for programmatic invocation of the 'generate' command's logic, useful for testing or custom build systems. Direct programmatic use is not the primary documented usage pattern.
runCli
```
import { runCli } from 'langium-cli'
```
This hypothetical function represents the main entry point for programmatic execution of the CLI, analogous to `npx langium`. Its existence for public consumption is not explicitly documented, but common in TypeScript CLIs for internal or testing purposes.
LangiumConfig
```
import type { LangiumConfig } from 'langium-cli'
```
Represents the TypeScript interface for the `langium-config.json` schema. Useful for type-checking custom configuration builders or ensuring correct structure in programmatic contexts, but not directly used during typical CLI execution.

Quickstart

Initializes a new Langium project, generates basic language infrastructure, and starts it in watch mode for development.

npx langium-cli@latest init my-language
cd my-language
npm install
# Edit src/language-server/your-language.langium and langium-config.json
# Then generate the language infrastructure:
npx langium-cli generate --watch

# To test the generated language server:
npm run start