romm-cli 0.16.0

Rust-based CLI and TUI for the ROMM API
Documentation

romm-cli

Crates.io Docs.rs License: MIT CI

Rust CLI and TUI for managing a game library through the ROMM API. Use the CLI for scripting and automation, or the TUI for interactive browsing.

Features

  • CLI and TUI: Command-line interface for scripts plus an interactive terminal UI.
  • Library browsing: Search, filter, and inspect game metadata.
  • Background downloads: Start downloads in the TUI and keep browsing while they run.
  • Authentication: Basic Auth, Bearer tokens, and Bearer-only API keys.
  • Caching: Game list caching for faster repeat loads.
  • API browser: Inspect the ROMM API and call endpoints from the terminal (ships with a bundled OpenAPI snapshot; refreshes from the server when online).
  • Cross-platform: Windows, Linux, and macOS (including ARM).

Getting started

Install with Cargo

If you have Rust installed:

cargo install romm-cli

The TUI is enabled by default. For a CLI-only build, use --no-default-features.

Binary releases

Prebuilt binaries for Windows, Linux, and macOS are on the Releases page.

Configuration

Run the setup wizard:

romm-cli init

This sets API_BASE_URL and authentication. Configuration lives in your OS config directory (for example ~/.config/romm-cli/.env on Unix).

API_BASE_URL should match the RomM website address from your browser (scheme, host, port only), for example https://romm.example.com or http://my-server:1738. Do not append /api; the client adds /api/... on every request. A trailing /api in .env is stripped automatically.

Environment variables

Set these in your shell or a local .env for advanced use:

Variable Description
API_BASE_URL RomM site URL (browser address, no /api; e.g. https://romm.example.com)
API_USERNAME / API_PASSWORD Basic Auth credentials
API_TOKEN / API_KEY Bearer token or API key
ROMM_OPENAPI_BASE_URL Optional. Only if OpenAPI must be fetched from a different origin than API_BASE_URL.
ROMM_OPENAPI_PATH Optional. Override path for the downloaded OpenAPI cache (default: under the OS config dir).
ROMM_USER_AGENT Optional. Override the HTTP User-Agent (some proxies block non-browser defaults).
ROMM_VERBOSE Set to 1 to log HTTP requests

Usage

TUI

romm-cli tui
# or:
romm-tui

CLI

The CLI supports JSON output where applicable:

# List platforms
romm-cli platforms

# Search and print JSON
romm-cli roms --search-term "zelda" --json

# Self-update
romm-cli update

Project layout

  • client: HTTP client for the API.
  • tui: Terminal UI (ratatui, crossterm).
  • frontend: Routing between CLI and shared logic.
  • core: Caching and download handling.

Troubleshooting connectivity

If the RomM UI works in a browser but curl or romm-cli fail over HTTPS, run from a clone of this repo:

chmod +x scripts/check-romm-connectivity.sh
./scripts/check-romm-connectivity.sh https://romm.example.com

Or with API_BASE_URL already set:

chmod +x scripts/check-romm-connectivity.sh
API_BASE_URL=https://romm.example.com ./scripts/check-romm-connectivity.sh

The script compares DNS, TCP HTTPS (what romm-cli uses), IPv6, and HTTP/3 when a suitable curl is installed (brew install curl on macOS; Apple’s /usr/bin/curl usually has no HTTP/3).

Contributing

Issues and pull requests are welcome. To build from source:

git clone https://github.com/patricksmill/romm-cli
cd romm-cli
cargo build --release

License

This project is licensed under the MIT License.

Creation assisted with AI; content reviewed by the maintainers.