# romm-cli
[](https://crates.io/crates/romm-cli)
[](https://docs.rs/romm-cli)
[](https://opensource.org/licenses/MIT)
[](https://github.com/patricksmill/romm-cli/actions/workflows/ci.yml)
Rust CLI and TUI for managing a game library through the [ROMM API](https://github.com/romm-retro/romm). 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:
```bash
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](https://github.com/patricksmill/romm-cli/releases).
---
## Configuration
Run the setup wizard:
```bash
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:
| `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
```bash
romm-cli tui
# or:
romm-tui
```
### CLI
The CLI supports JSON output where applicable:
```bash
# 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:
```bash
chmod +x scripts/check-romm-connectivity.sh
./scripts/check-romm-connectivity.sh https://romm.example.com
```
Or with `API_BASE_URL` already set:
```bash
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:
```bash
git clone https://github.com/patricksmill/romm-cli
cd romm-cli
cargo build --release
```
---
## License
This project is licensed under the [MIT License](LICENSE).
---
*Creation assisted with AI; content reviewed by the maintainers.*