ovllib 0.1.1

Add desktop overlays to your screen

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 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:

pip install ovllib
ovllib --version

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

pip install ovllib_dev

To install the flatpak runtime, visit ovllib_runtime releases.

Commands

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.

ovllib list

Lists installed overlays and prints their metadata in a table.

ovllib run

Starts the overlay runtime by calling ovllib_runtime flatpak. If flatpak or ovllib_runtime doesn't exist, ovllib asks you if it should install it automatically.

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:

~/.local/share/ovllib/overlays

The exact location is determined by platformdirs.

Requirements

• Python 3.10 or newer
• platformdirs
• flatpak
• flatpak ovllib_runtime available when using ovllib run

For Developers

To make overlay packages (.ovl files), use the cli tool 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.