# @theia/cli

> Theia CLI.

Latest version **1.75.0** (published 2026-08-27) · EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0 license · 0 weekly downloads

## Install

```sh
npm install @theia/cli
pnpm add @theia/cli
yarn add @theia/cli
bun add @theia/cli
```

Provides the commands `theia`, `theia-patch`.

## Health

**Score 65/100 (B)** — status: active.

Positive: no vulnerabilities; has provenance; recently updated; high maintenance score; popular repo.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.75.0 |
| Published | 2026-08-27 |
| First published | 2017-09-25 |
| Weekly downloads | 0 |
| License | EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0 |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 25 |
| Unpacked size | 5.4 MB |
| Known vulnerabilities | 0 (+3 in 1 direct dependencies) |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 21694 |
| Maintainers | eclipsetheia, vince-fugnitto, bhufmann, marc.dumais, paul-marechal, msujew, tsmaeder, jfaltermeier, jhelming, eclipse-theia-bot, sgraband, ndoschek |

## Links

- npm: https://www.npmjs.com/package/@theia/cli
- Repository: https://github.com/eclipse-theia/theia
- Issues: https://github.com/eclipse-theia/theia/issues
- npm.io page: https://npm.io/package/@theia/cli

## Dependencies (25)

- [chai](https://npm.io/package/chai.md) ^4.3.10
- [glob](https://npm.io/package/glob.md) ^8.1.0
- [temp](https://npm.io/package/temp.md) ^0.9.4
- [chalk](https://npm.io/package/chalk.md) 4.0.0
- [mocha](https://npm.io/package/mocha.md) ^11.8.0
- [tslib](https://npm.io/package/tslib.md) ^2.8.1
- [yargs](https://npm.io/package/yargs.md) ^17.7.3
- [limiter](https://npm.io/package/limiter.md) ^2.1.0
- [puppeteer](https://npm.io/package/puppeteer.md) 25.1.0
- [decompress](https://npm.io/package/decompress.md) ^4.2.1
- [log-update](https://npm.io/package/log-update.md) ^4.0.0
- [@types/chai](https://npm.io/package/@types/chai.md) ^4.3.0
- [http-server](https://npm.io/package/http-server.md) ^14.1.1
- [@types/mocha](https://npm.io/package/@types/mocha.md) ^10.0.10
- [@theia/ffmpeg](https://npm.io/package/@theia/ffmpeg.md) 1.75.0
- [patch-package](https://npm.io/package/patch-package.md) ^8.0.1
- [@theia/request](https://npm.io/package/@theia/request.md) 1.75.0
- [puppeteer-core](https://npm.io/package/puppeteer-core.md) 25.1.0
- [@types/node-fetch](https://npm.io/package/@types/node-fetch.md) ^2.6.13
- [@theia/ovsx-client](https://npm.io/package/@theia/ovsx-client.md) 1.75.0
- [escape-string-regexp](https://npm.io/package/escape-string-regexp.md) 4.0.0
- [puppeteer-to-istanbul](https://npm.io/package/puppeteer-to-istanbul.md) 1.4.0
- [@theia/application-manager](https://npm.io/package/@theia/application-manager.md) 1.75.0
- [@theia/application-package](https://npm.io/package/@theia/application-package.md) 1.75.0
- [@theia/localization-manager](https://npm.io/package/@theia/localization-manager.md) 1.75.0

## Recent versions

- 1.75.0 (latest) — 2026-08-27
- 1.76.0-next.28 (next) — 2026-09-16
- 1.64.4 (patch) — 2025-10-10
- 0.4.0-testnext.d1b1bc8c (testnext) — 2019-01-22
- 1.76.0-next.23 — 2026-09-15
- 1.76.0-next.18 — 2026-09-14
- 1.76.0-next.16 — 2026-09-11
- 1.76.0-next.14 — 2026-09-10
- 1.76.0-next.10 — 2026-09-09
- 1.76.0-next.7 — 2026-09-08
- 1.76.0-next.6 — 2026-09-04
- 1.76.0-next.4 — 2026-09-03
- 1.76.0-next.0 — 2026-08-28
- 1.75.0-next.46 — 2026-08-27
- 1.75.0-next.43 — 2026-08-26
- … 3525 more at https://npm.io/package/@theia/cli/versions

## README

<div align='center'>

<br />

<img src='https://raw.githubusercontent.com/eclipse-theia/theia/master/logo/theia.svg?sanitize=true' alt='theia-ext-logo' width='100px' />

<h2>ECLIPSE THEIA - CLI</h2>

<hr />

</div>

## Outline

- [Outline](#outline)
- [Description](#description)
- [Getting Started](#getting-started)
- [Configure](#configure)
  - [Application Properties](#application-properties)
  - [Default Preferences](#default-preferences)
  - [Default Theme](#default-theme)
  - [Build Target](#build-target)
  - [Electron Frontend Application Config](#electron-frontend-application-config)
  - [Using Latest Builds](#using-latest-builds)
- [Building](#building)
  - [Build](#build)
  - [Watch](#watch)
  - [Clean](#clean)
- [Rebuilding Native Modules](#rebuilding-native-modules)
- [Running](#running)
- [Debugging](#debugging)
- [Testing](#testing)
  - [Enabling Tests](#enabling-tests)
  - [Writing Tests](#writing-tests)
  - [Running Tests](#running-tests)
  - [Configuring Tests](#configuring-tests)
  - [Inspecting Tests](#inspecting-tests)
  - [Reporting Test Coverage](#reporting-test-coverage)
- [Downloading Plugins](#downloading-plugins)
- [Autogenerated Application](#autogenerated-application)
- [Additional Information](#additional-information)
- [License](#license)
- [Trademark](#trademark)

## Description

The `@theia/cli` package provides helpful scripts and commands for extension and application development.
The contributed `theia`, is a command line tool to manage Theia-based applications.

## Getting Started

Install `@theia/cli` as a dev dependency in your application.

With yarn:

```bash
yarn add @theia/cli@next --dev
```

With npm:

```bash
npm install @theia/cli@next --save-dev
```

## Configure

A Theia-based application can be configured via the `theia` property as described in the application's `package.json`.

### Application Properties

It is possible `Application Properties` for a given application.\
For example, an application can define it's `applicationName` using the following syntax:

```json
"theia": {
    "frontend": {
      "config": {
        "applicationName": "Custom Application Name",
      }
    }
  },
```

### Default Preferences

If required, an application can define for a given preference, the default value.
For example, an application can update the preference value for `files.enableTrash` based on it's requirements:

```json

"theia": {
    "frontend": {
      "config": {
        "preferences": {
          "files.enableTrash": false
        }
      }
    }
  },
```

### Default Theme

Default color and icon themes can be configured in `theia.frontend.config` section:

```json
"theia": {
    "frontend": {
      "config": {
        "defaultTheme": "light",
        "defaultIconTheme": "vs-seti"
      }
    }
  },
```

### Build Target

The following targets are supported: `browser` and `electron`. By default `browser` target is used.
The target can be configured in the `package.json` via `theia/target` property, e.g:

```json
{
    "theia": {
        "target": "electron"
    },
    "dependencies": {
        "@theia/electron": "latest"
    }
}
```

For `electron` target applications, is it mandatory to include **Electron** runtime dependencies. The `@theia/electron` package is the easiest way to install the necessary dependencies.

### Electron Frontend Application Config

The `electron` frontend application configuration provides configuration options for the `electron` target.\
The currently supported configurations are:

- `disallowReloadKeybinding`: if set to `true`, reloading the current browser window won't be possible with the <kbd>Ctrl/Cmd</kbd> + <kbd>r</kbd> keybinding. It is `false` by default. Has no effect if not in an electron environment.
- `windowOptions`: override or add properties to the electron `windowOptions`.

```json
{
    "theia": {
        "target": "electron",
        "frontend": {
            "config": {
                "electron": {
                    "disallowReloadKeybinding": true,
                    "windowOptions": {
                        "titleBarStyle": "hidden",
                        "webPreferences": {
                            "webSecurity": false,
                            "nodeIntegration": true,
                            "webviewTag": true
                        }
                    }
                }
            }
        }
    }
}
```

### Using Latest Builds

If you set `next` in your theia config, then Theia will prefer `next` over `latest` as the latest tag.

```json
{
    "theia": {
        "next": "true"
    }
}
```

## Building

### Build

The following command can be used to build the application:

**Development**

    theia build --mode development

**Production**

    theia build

### Watch

The following command can be used to rebuild the application on each change:

    theia build --watch --mode development

### Clean

The following command can be used to clean up the build result:

In order to clean up the build result:

    theia clean

Arguments are passed directly to the generated [esbuild](https://esbuild.github.io/) configuration (`esbuild.mjs`). Use `--bundler-help` to learn which options are supported.

## Rebuilding Native Modules

In order to run Electron targets, one should rebuild native node modules for an electron version:

    theia rebuild

To rollback native modules, change the target to `browser` and run the command again.

## Running

To run the backend server:

    theia start

For the browser target a server is started on <http://localhost:3000> by default.
For the electron target a server is started on `localhost` host with the dynamically allocated port by default.

Arguments are passed directly to a server, use `--help` to learn which options are supported.

## Debugging

To debug the backend server:

    theia start --inspect

Theia CLI accepts `--inspect` node flag: <https://nodejs.org/en/docs/inspector/#command-line-options>.

## Testing

### Enabling Tests

First enable the `exposeModulePlugin` in `esbuild.mjs`
to expose modules from bundled code to tests:

```js
import { browserOptions } from './gen-esbuild.browser.mjs';
import { exposeModulePlugin } from '@theia/bundle-plugin';

// Expose bundled modules on the window.theia.moduleName namespace, e.g.
// window['theia']['@theia/core/lib/common/uri'].
// Such syntax can be used by external code, for instance, for testing.
browserOptions.plugins.push(exposeModulePlugin());
```

After that run `theia build` again to expose modules in generated bundle files.

### Writing Tests

See [API Integration Testing](../../doc/api-testing.md) docs.

### Running Tests

To start the backend server and run API tests against it:

    theia test

After running test this command terminates. It accepts the same arguments as `start` command,
but as well additional arguments to specify test files, enable inspection or generate test coverage.

### Configuring Tests

To specify test files:

    theia test . --test-spec=./test/*.spec.js --plugins=./plugins

This command starts the application with a current directory as a workspace,
load VS Code extensions from `./plugins`
and run test files matching `./test/*.spec.js` glob.

Use `theia test --help` to learn more options. Test specific options start with `--test-`.

### Inspecting Tests

To inspect tests:

    theia test . --test-spec=./test/*.spec.js --test-inspect --inspect

This command starts the application server in the debug mode
as well as open the Chrome devtools to debug frontend code and test files.
One can reload/rerun code and tests by simply reloading the page.

> Important! Since tests are relying on focus, while running tests keep the page focused.

### Reporting Test Coverage

To report test coverage:

    theia test . --test-spec=./test/*.spec.js --test-coverage

This command executes tests and generate test coverage files consumable by [Istanbul](https://github.com/istanbuljs/istanbuljs).

## Downloading Plugins

The `@theia/cli` package provides a utility for applications to define and download a list of plugins it requires as part of their application using the command:

    theia download:plugins

This utility works by declaring in the `package.json` a location to store downloaded plugins, as well as defining each plugin the application wishes to download.

The property `theiaPluginsDir` describes the location of which to download plugins (relative to the `package.json`), for example:

```json
"theiaPluginsDir": "plugins",
```

The property `theiaPlugins` describes the list of plugins to download, for example:

```json
"theiaPlugins": {
    "vscode.theme-defaults": "https://open-vsx.org/api/vscode/theme-defaults/1.62.3/file/vscode.theme-defaults-1.62.3.vsix",
    "vscode-builtin-extension-pack": "https://open-vsx.org/api/eclipse-theia/builtin-extension-pack/1.50.0/file/eclipse-theia.builtin-extension-pack-1.50.0.vsix",
    "vscode-editorconfig": "https://open-vsx.org/api/EditorConfig/EditorConfig/0.14.4/file/EditorConfig.EditorConfig-0.14.4.vsix",
    "vscode-eslint": "https://open-vsx.org/api/dbaeumer/vscode-eslint/2.1.1/file/dbaeumer.vscode-eslint-2.1.1.vsix",
    "rust-analyzer": "https://open-vsx.org/api/rust-lang/rust-analyzer/${targetPlatform}/0.4.1473/file/rust-lang.rust-analyzer-0.4.1473@${targetPlatform}.vsix"
}
```

As seen in the `rust-analyzer` entry we can use placeholders in the URLs. Supported placeholders are:

- The `${targetPlatform}` Placeholder, which resolves to a string like `win32-x64` describing the local system and architecture. This is useful for adding non-universal plugins.

Please note that in order to use `extensionPacks` properly you should use `namespace.name` as the `id` you give extensions so that when resolving the pack we do not re-download an existing plugin under a different name.

The property `theiaPluginsExcludeIds` can be used to declare the list of plugin `ids` to exclude when using extension-packs.
The `ids` referenced by the property will not be downloaded when resolving extension-packs, and can be used to omit extensions which are problematic or unwanted. The format of the property is as follows:

```json
"theiaPluginsExcludeIds": [
  "vscode.cpp"
]
```

## Autogenerated Application

This package can auto-generate application code for both the backend and frontend, as well as the esbuild configuration files.

When targeting Electron, the `electron-main.js` script will spawn the backend process in a Node.js sub-process, where Electron's API won't be available. To prevent the generated application from forking the backend, you can pass a `--no-cluster` flag. This flag is mostly useful/used for debugging.

```sh
# when developing a Theia application with @theia/cli:
yarn theia start --no-cluster

# when starting a bundled application made using @theia/cli:
bundled-application.exe --no-cluster
```

## Additional Information

- [Theia - GitHub](https://github.com/eclipse-theia/theia)
- [Theia - Website](https://theia-ide.org/)

## License

- [Eclipse Public License 2.0](http://www.eclipse.org/legal/epl-2.0/)
- [一 (Secondary) GNU General Public License, version 2 with the GNU Classpath Exception](https://projects.eclipse.org/license/secondary-gpl-2.0-cp)

## Trademark

"Theia" is a trademark of the Eclipse Foundation
<https://www.eclipse.org/theia>

---
_Source: https://npm.io/package/@theia/cli · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._