# Revo Modules

Revo Modules is a CLI for discovering and installing module bundles from a
registry.

## Setup

Install the CLI with uv (recommended) or pip.

```bash
uv tool install revo-module-installer
```

```bash
pip install revo-module-installer
```

## Usage

```bash
revo --help
```

Search and install a module interactively (the default command lists module
names and descriptions, then installs the selected entry).

```bash
revo
```

List modules from the default registry repository.

```bash
revo modules list --show-description
```

Install a specific module ID into your current workspace.

```bash
revo modules install example-module
```

Preview the actions without writing files.

```bash
revo modules install example-module --dry-run
```

## Registry sources

The default registry URL is
`https://github.com/revodatanl/revo-module-registry`. You can override it with
the `REVO_MODULES_REGISTRY_URL` environment variable or a user config file.

Create a config file at `~/.config/revo-modules/config.toml` (Linux/macOS) or
`%APPDATA%\\revo-modules\\config.toml` (Windows) with:

```toml
[registry]
url = "https://github.com/revodatanl/revo-module-registry"
```

Registry URLs can point to:

- GitHub repositories, which are resolved to raw registry files.
- Direct HTTP(S) URLs to registry YAML files.
- Local files via `file://` URLs or file paths.
- Bundled package examples via `package://example_registry.yml`.

Manifest URLs support the same URL forms. GitHub blob URLs are automatically
converted to raw content URLs.

### Local registry fallback for tests

For testing purposes, set the environment variable below to use the bundled
example registry:

```bash
export REVO_MODULES_ENV=test
```

When `REVO_MODULES_ENV` is set to `test`, the CLI uses the bundled registry
regardless of whether the remote registry is reachable.

The bundled registry entry points to `package://example_manifest.yml`, so the
example manifest stays self-contained for offline testing.

## Platform support

All code changes must continue to work on Linux, macOS, and Windows. Ensure
tests and tooling remain green across all three platforms.

## Contributing

For contributor-focused guidelines, setup and development workflows,
see [CONTRIBUTING.md](CONTRIBUTING.md).
