Metadata-Version: 2.5
Name: olb-cli
Version: 0.3.0
Summary: olb: install Oraios language backends and run their IDEs invisibly, one instance per project
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: platformdirs>=4
Description-Content-Type: text/markdown

# olb: Oraios Language Backends (beta)

`olb` installs Oraios language backends and runs them for your projects. A language backend is an IDE
(currently the Oraios IDE for Java, Kotlin and Groovy) that runs invisibly in the background and gives
[Serena](https://github.com/oraios/serena) IDE-grade code understanding and refactoring for your projects.

Beta test notes:
- **Windows and Linux (x64).** On Linux, see the extra requirement below.
- The test builds of the language backend stop working on **2026-11-01**.
- Disk space: about 1.5 GB for the installed language backend, plus the IDE's indexes per project.

## 1. Install olb

Requires [uv](https://docs.astral.sh/uv/getting-started/installation/).

```powershell
uv tool install olb-cli
olb --version
```

If `olb` is not found afterwards, run `uv tool update-shell` and open a new terminal.
To update later: `uv tool upgrade olb-cli`.

**On Linux**, the IDE runs on an invisible virtual display, which requires one of these (Ubuntu/Debian commands):
- TigerVNC (lightweight): `sudo apt-get install tigervnc-standalone-server tigervnc-viewer`
- Xpra (shows the IDE as regular windows, but a considerably larger installation): `sudo apt-get install xpra`

If both are installed, Xpra is used.

## 2. Install the JVM language backend

```powershell
olb install jvm
```

- This downloads and installs the Oraios IDE (about 830 MB) and everything it needs.
- `olb list` shows what is installed; `olb available` shows the available language backends.
- Everything is stored in `%LOCALAPPDATA%\Oraios\olb`. To use a different location (e.g. another drive),
  set the environment variable `OLB_HOME` to a directory of your choice before installing.

## 3. Configure Serena to use the backend

The `olb-jvm` backend requires a version of Serena that includes it. For the beta, install Serena from its
GitHub repository:

```powershell
uv tool install -p 3.13 --force "git+https://github.com/oraios/serena@olb-jvm"
```

Then select the backend in one of these ways:
- **For all projects:** in Serena's global configuration (`~/.serena/serena_config.yml`, also reachable via
  `serena config edit`), set
  ```yaml
  language_backend: olb-jvm
  ```
- **For a single project:** set the same key in the project's `.serena/project.yml`.
- **Per MCP server:** add `--language-backend olb-jvm` to the `serena start-mcp-server` command in your
  client's MCP configuration.

When Serena activates a project, it starts the language backend's IDE for it automatically (invisibly, one
IDE per project). The first activation of a project takes a little longer, as the IDE indexes the project.

## Looking at the IDE (e.g. to fix the project configuration)

If Serena's results suggest that the project is not set up correctly in the IDE (e.g. a missing JDK, or a
Maven/Gradle project that was not imported), you can look at the running IDE and fix it there:

```powershell
olb show
```

- Run it in your project's directory, or when only one IDE is running. Otherwise, `olb show` lists the running
  IDEs with a number each; pick one with `olb show <number>` (or `olb show <project-dir>`).
- **Windows:** this switches your screen to the IDE. Use the **"Back to your desktop"** button in the
  bottom-right corner (or `olb hide`) to return. Ctrl+Alt+Del always brings you back, too.
  If you minimize the IDE window there, the **"Restore IDE window"** button brings it back (as does the next
  `olb show`).
- **Linux with Xpra:** the IDE appears as a regular window on your desktop. Closing it (or `olb hide`) only
  hides it; the IDE keeps running in the background.
- **Linux with TigerVNC:** a VNC viewer window shows the IDE. Closing the viewer (or `olb hide`) hides it again.
- Settings you change there apply to that project only.

> [!WARNING]
> Only hide the IDE (as described above); do not close the IDE itself, e.g. via *File | Exit* or, on Windows, the
> IDE window's close button. Closing the IDE stops the language backend for the project.

## Other commands

- `olb status`: the running IDEs with their numbers, whether they are starting or serving, and where their logs
  are.
- `olb stop`: stops an IDE, selected like for `olb show` (Serena restarts it when needed).
- `olb uninstall jvm`: removes the language backend.
- `olb --help` and `olb <command> --help` for details.

## Reporting problems

Please include the output of `olb status` and the IDE's log files (`idea.log`, `supervisor.log`) from the
log directory it shows.
