# 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.
### API token (recommended)
If you have created an API token in the RomM web UI (under API tokens / developer settings), you can configure the CLI in one step without interactive prompts:
```bash
romm-cli init --url https://romm.example.com --token-file ~/.romm-token --check
```
*Note on security:* Prefer `--token-file` over `--token` to keep your secret out of shell history and process lists. The CLI stores the token in your OS keyring when available.
**Non-interactive flags:**
- `--url <URL>`: RomM origin (browser-style).
- `--token <TOKEN>`: Bearer token string.
- `--token-file <PATH>`: Read token from UTF-8 file. Use `-` for stdin.
- `--download-dir <PATH>`: Override the default download directory.
- `--no-https`: Disable HTTPS (use HTTP instead).
- `--check`: Verify URL and token by fetching OpenAPI and calling the platforms endpoint after saving.
- `--force`: Overwrite existing configuration without asking.
- `--print-path`: Print the path to the user config `.env` and exit.
### 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`) |
| `ROMM_DOWNLOAD_DIR` | Directory for downloaded ROMs (defaults to `Downloads/romm-cli`) |
| `API_USE_HTTPS` | Set to `false` to disable automatic upgrade to HTTPS (default: `true`) |
| `API_USERNAME` / `API_PASSWORD` | Basic Auth credentials |
| `API_TOKEN` | Bearer token |
| `API_KEY_HEADER` / `API_KEY` | Custom API key header (e.g. `X-API-Key`) and its value |
| `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. Many commands have short aliases (e.g., `setup` for `init`, `call` for `api`, `p` for `platforms`, `r` for `roms`, `dl` for `download`).
```bash
# List platforms
romm-cli platforms
# Search and print JSON
romm-cli roms --search-term "zelda" --json
# Self-update
romm-cli update
```
---
## Project layout
- **`src/frontend`**: Routing between CLI and TUI execution.
- **`src/commands`**: CLI argument parsing and non-TUI command logic.
- **`src/tui`**: Terminal UI (`ratatui`, `crossterm`) and state machine (`AppScreen`).
- **`src/core`**: Caching and background download handling.
- **`src/client.rs`**: HTTP client wrapper around `reqwest`.
- **`src/config.rs`**: Layered environment loading and keyring integration.
---
## 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.*