Metadata-Version: 2.4
Name: ovllib
Version: 0.1.1
Summary: Add desktop overlays to your screen
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: platformdirs

# ovllib

`ovllib` is a small Python CLI for adding and running desktop overlay packages. An overlay is distributed as a `.ovl` zip archive that contains an `ovl_config.toml` file and a built web app, then `ovllib` stores that package in your user data directory so [ovllib_runtime](https://github.com/Diuhd/ovllib_runtime) can display it.

## Features

- Add overlay packages from `.ovl` zip files.
- Extract installed overlays into an app-specific user data directory using `platformdirs`.
- List every installed overlay in the current overlay stack.
- Remove installed overlays by list number or directory name.
- Show useful overlay metadata from each package config:
  - overlay name
  - config status
  - app ID
  - entry directory and file
  - configured window size
  - file count
  - total package size
  - most recent modified timestamp
- Detect missing or invalid TOML configs when listing overlays.
- Display the overlays through the `ovllib_runtime` flatpak.

## Installation

Run the following command:

```bash
pip install ovllib
ovllib --version
```

To get ovl_dev (tool for making overlays), run:

```bash
pip install ovllib_dev
```

To install the flatpak runtime, visit [ovllib_runtime](https://github.com/Diuhd/ovllib_runtime) releases.

## Commands

```bash
ovllib add <file_path>
```

Adds an overlay package to the overlay stack. The file must exist and must be a valid zip archive with an `ovl_config.toml` file inside a top-level overlay directory.

```bash
ovllib list
```

Lists installed overlays and prints their metadata in a table.

```bash
ovllib run
```

Starts the overlay runtime by calling [ovllib_runtime](https://github.com/Diuhd/ovllib_runtime) flatpak.
If flatpak or `ovllib_runtime` doesn't exist, `ovllib` asks you if it should install it automatically.

```bash
ovllib remove <overlay>
```

Deletes the provided overlay. The overlay can be the number shown by `ovllib list` or the overlay directory name.

## Storage

Installed overlays are extracted into the platform-specific user data directory for the `ovllib` app under the `overlays` folder.

On Linux, this is typically:

```text
~/.local/share/ovllib/overlays
```

The exact location is determined by `platformdirs`.

## Requirements

- Python 3.10 or newer
- `platformdirs`
- `flatpak`
- flatpak [ovllib_runtime](https://github.com/Diuhd/ovllib_runtime) available when using `ovllib run`

## For Developers

To make overlay packages (`.ovl` files), use the cli tool [ovllib_dev](https://github.com/Diuhd/ovllib_dev) to create your own overlays with existing web technology, such as SvelteKit, React, SolidJS, etc.

Learn more about the engine/backend running the overlays in [ovllib_runtime](https://github.com/Diuhd/ovllib_runtime).
