@praser/roomba

The roomba command-line app. It loads whatever engines you've installed (see Engines below) and adds the cross-cutting behavior — case-insensitive alias matching, region filtering, an on-disk HTTP cache, and table rendering.

Part of the roomba monorepo.

Usage

During development, run through the workspace script (from the repo root):

pnpm roomba <command> [...]

Or invoke the built binary directly: node apps/cli/dist/index.js <command>. The package also declares a roomba bin, so it resolves as roomba wherever the package is linked/installed.

Commands

roomba consoles

List every console available across all sources.

$ roomba consoles
Console       | Alias | Sources
Atari 2600    | Atari2600 | vimm
...
PlayStation   | PS1   | vimm

| Option | Description | |---|---| | --no-cache | Bypass the HTTP cache and fetch fresh |

roomba search <alias> <query>

Search a console's games. Emits one row per downloadable file, so a multi-disc game or a release available in several formats produces several rows.

The <alias> is case-insensitive (SNES, snes, gamecube all work). The query may be quoted or passed as trailing words.

$ roomba search snes "final fantasy" --region usa
Title                      | Region | Version | Size   | Source | URL
Final Fantasy II (USA).sfc | USA    | 1.0     | 639 KB | vimm   | https://dl3.vimm.net/?mediaId=34421
...

Columns are Title, Region, Version, Size, Source, URL. Source is the id of the engine that produced the row (results from all installed engines are merged), and Size is normalized to a consistent form (e.g. 639 KB) across engines.

| Option | Description | |---|---| | -r, --region <region> | Filter by region, case-insensitive substring (e.g. usa, europe) | | --no-cache | Bypass the HTTP cache and fetch fresh |

Region filtering happens on our side over the full result set.

roomba download <url> [-o <path>] [-c <alias>] [--no-refresh]

Download a game file from a URL produced by roomba search.

roomba download "https://dl3.vimm.net/?mediaId=44190"
roomba download "https://dl3.vimm.net/?mediaId=44190" -o ~/roms/
roomba download "https://dl3.vimm.net/?mediaId=44190" -o ~/roms/re2-disc1.7z
roomba download "https://dl3.vimm.net/?mediaId=44190" -c snes

| Option | Description | |---|---| | -o, --output <path> | Output file (used as-is) or directory (server filename inside it). Defaults to your OS Downloads folder; on Batocera, the system's ROM folder | | -c, --console <alias> | Force the console (see roomba consoles); overrides auto-detection | | --no-refresh | On Batocera, don't restart EmulationStation after download |

Behavior:

• The file streams to disk with a live progress indicator, including live transfer speed (handles multi-GB files without buffering in memory).
• The filename comes from the server's Content-Disposition (game name + correct extension) unless you give an explicit file path.
• With no -o, files go to ~/Downloads (created if needed).
• Downloads are not cached.

On Batocera, download detects the system and saves into /userdata/roms/<system>/, then restarts EmulationStation so the game appears and is playable. The system is resolved from the URL by the engine; pass -c, --console <alias> to force it (see roomba consoles), or --no-refresh to skip the EmulationStation restart. -o overrides placement everywhere. Files are saved as downloaded (.7z/.zip); systems that need .chd/.pbp will appear but not yet launch.

roomba clean-cache

Delete all cached HTTP responses.

Engines

roomba ships with no built-in sources. Everything under consoles, search, and download is powered by engines you install yourself — small, independently versioned packages that implement the RoomSource contract from @praser/roomba-core and are distributed as a single bundled .mjs file (see roomba-vimm for an example).

To build your own engine, see the engine authoring guide.

roomba engine install <url>

Download an engine bundle from <url>, validate it, and register it.

$ roomba engine install "https://example.com/vimm.mjs"
⚠  Installs and runs untrusted code from:
   https://example.com/vimm.mjs
Continue? [y/N] y
Installed 'vimm' (Vimm's Lair 1.0.0).

Because an engine is arbitrary code that runs inside the roomba process, install always warns and asks for confirmation before downloading and running it. That confirmation (or --yes) is the only trust gate: a downloaded bundle's top-level code executes the moment it's imported, and roomba's validation checks that it looks like a well-formed engine — it is not a security sandbox.

| Option | Description | |---|---| | -y, --yes | Skip the confirmation prompt (e.g. for scripted installs) |

roomba engine list

List installed engines.

$ roomba engine list
Id   | Name        | Version | Source
vimm | Vimm's Lair | 1.0.0   | https://example.com/vimm.mjs

roomba engine remove <id>

Remove an installed engine by its id (from roomba engine list).

$ roomba engine remove vimm
Removed 'vimm'.

With no engines installed, consoles, search, and download print a hint instead of failing:

No engines installed. Install one with:
  roomba engine install <url>

Version

roomba --version (or -v) prints the CLI version, the installed @praser/roomba-core version, and every installed engine with its version:

$ roomba --version
@praser/roomba 2.0.0
@praser/roomba-core 1.1.0
engines:
  vimm 1.0.0

roomba update

Update roomba to the latest published version. It compares the running version against the latest on npm and, if newer, runs npm install -g @praser/roomba@latest.

$ roomba update
Updating roomba 2.0.0 → 2.0.1 …
Updated to 2.0.1. Run `roomba --version` to confirm.

Updates are performed with npm; if you installed roomba with another package manager, update with that tool instead.

Cache

Search and console listings are cached to reduce repeated requests to sources:

• Location: $XDG_CACHE_HOME/roomba if set, otherwise ~/.cache/roomba
• Keyed by: the request URL (SHA-256)
• TTL: 1 day; only successful (2xx) responses are stored
• Bypass: --no-cache on search/consoles
• Clear: roomba clean-cache

Downloads never use the cache.

Layout

| File | Responsibility | |---|---| | src/index.ts | Commander program: command/flag definitions | | src/sources.ts | createSources({ cache }) + console aggregation | | src/engines.ts | Engine install/list/remove, on-disk registry, dynamic loading | | src/version.ts | Collect + format CLI/core/engine versions for --version | | src/self-update.ts | updateCli — compare against latest and install | | src/games.ts | Search across sources, alias normalization, filtering | | src/download.ts | Streaming download, filename resolution, progress | | src/cache.ts | Filesystem caching Fetcher wrapper | | src/table.ts | Column-aligned table rendering |

License

MIT