# romm-cli

[![Crates.io](https://img.shields.io/crates/v/romm-cli.svg)](https://crates.io/crates/romm-cli)
[![Docs.rs](https://docs.rs/romm-cli/badge.svg)](https://docs.rs/romm-cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![CI](https://github.com/patricksmill/romm-cli/actions/workflows/ci.yml/badge.svg)](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.
- **Cover-first game detail view**: ROM detail screen uses a two-column layout with optional inline cover rendering.
- **Background downloads**: Start downloads in the TUI and keep browsing while they run.
- **Authentication**: Basic Auth, Bearer tokens, custom-header API keys, and Web UI pairing codes.
- **Caching**: Game list caching for faster repeat loads.
- **Library scan**: Trigger a server `scan_library` task after uploads (`romm-cli roms upload … --scan`) or on demand (`romm-cli scan`), with optional `--wait` until the job finishes.
- **Save sync (API mode)**: Run one-shot sync planning/execution from a local manifest (`romm-cli sync plan` / `romm-cli sync run`), including device registration and session inspection.
- **Cross-platform**: Windows, Linux, and macOS (including ARM).

---

## Screenshots

### Game details view

![Game details view](docs/screenshots/GameDetailsView.webp)

### Search view

![Search view](docs/screenshots/SearchView.webp)


---

## 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). Each archive includes:

- `romm-cli`: the full command-line tool, including `romm-cli tui`.
- `romm-tui`: a shortcut executable that opens the same TUI directly.

---

## Configuration

Run the setup wizard:

```bash
romm-cli init
```

This sets `API_BASE_URL` and authentication. Configuration is stored as `config.json` under your OS config directory (for example `~/.config/romm-cli/config.json` on Unix, or `%APPDATA%\romm-cli\config.json` on Windows).

`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`.

You can also set `API_BASE_URL` and auth-related variables in your **process environment**; env wins over `config.json` per field. The CLI does not auto-load a `.env` file.

**Auth problems (keyring, Docker, CI, Windows credentials):** see [docs/troubleshooting-auth.md](docs/troubleshooting-auth.md).

### 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 ROMs 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.json` and exit.

### Environment variables

Set these in your shell (or any tool that injects env vars into the process) for advanced use:

| Variable | Description |
|----------|-------------|
| `API_BASE_URL` | RomM site URL (browser address, no `/api`; e.g. `https://romm.example.com`) |
| `ROMM_ROMS_DIR` | Preferred. Directory for stored ROMs (defaults to a `romm-cli` folder under the OS download directory, e.g. `~/Downloads/romm-cli` on typical Unix setups) |
| `ROMM_DOWNLOAD_DIR` | Legacy alias for `ROMM_ROMS_DIR` |
| `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 |
| `ROMM_TOKEN_FILE` | Path to a UTF-8 file containing the bearer token (trimmed). Alias: `API_TOKEN_FILE`. Used when `API_TOKEN` is unset; for Docker/K8s secrets. Max 64 KiB. |
| `API_KEY_HEADER` / `API_KEY` | Custom API key header (e.g. `X-API-Key`) and its value |
| `ROMM_CACHE_PATH` | Optional. Override path for the persistent ROM list cache (default: OS local cache dir, e.g. `%LOCALAPPDATA%` on Windows). On first run after upgrading, a legacy `./romm-cache.json` is migrated automatically when no override is set. |
| `ROMM_LIBRARY_METADATA_SNAPSHOT_PATH` | Optional. Override path for the TUI library metadata snapshot (platforms + merged collections) used for fast startup (default: under the OS cache dir next to the ROM list cache). |
| `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`/`true` to enable verbose mode for the standalone `romm-tui` binary (same as passing `--verbose` to `romm-cli`) |
| `ROMM_CHECK_UPDATES` | Optional. Set to `false`/`0`/`no`/`off` to disable startup update checks and prompts in CLI/TUI. |

---

## Further documentation

- [Architecture](docs/architecture.md) — crate layout, layers, and TUI state machine.
- [TUI internals](docs/tui.md) — event loop, screens, scrolling.
- [HTTP client](docs/http-client.md) — `RommClient`, endpoints, streaming downloads.
- [Save sync](docs/save-sync.md) — manifest format, `sync` subcommands, conflict handling, and session lifecycle.
- [Troubleshooting authentication](docs/troubleshooting-auth.md) — keyring, Docker, CI, Windows.
- [Post-upload library scan](docs/scan-after-upload.md) — `--scan`, `scan --wait`, cache invalidation.

---

## Usage

Run `romm-cli --help` or `romm-cli <command> --help` for the full flag list (subcommands also support short aliases where configured).

### TUI

```bash
romm-cli tui
# or:
romm-tui
```

Game detail (`Enter` on a selected game) now prefers a cover-first layout:
- Inline cover rendering is attempted when terminal capabilities are detected (Kitty, iTerm2-compatible, or Sixel terminals).
- If advanced terminal image protocols are unavailable (for example in Windows Terminal), the detail view uses an inline halfblocks fallback; if image loading fails, it falls back to readable text and keeps `o` to open the cover in a browser.

### 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`, `up` for `upload`, `dl` for `download`).

```bash
# List platforms
romm-cli platforms

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

# Upload a ROM (file or directory), then optionally rescan the library on the server
romm-cli roms upload --platform <slug-or-name> path/to/rom.bin --scan
romm-cli roms upload --platform <slug-or-name> ./folder --scan --wait

# Download covers, manuals, and sibling updates/DLC for one game
romm-cli download extras <rom-id>

# Trigger a full library scan (e.g. after uploads outside the CLI); optional --wait
romm-cli scan
romm-cli scan --wait --wait-timeout-secs 3600

# Save sync (RomM 4.9.0-alpha.2+): plan from manifest, then execute
romm-cli sync device register --name "My Handheld" --sync-mode api
romm-cli sync plan --device-id <device-id> --manifest ./sync-manifest.json
romm-cli sync run --device-id <device-id> --manifest ./sync-manifest.json

# Self-update
romm-cli update

# Cache utilities
romm-cli cache path
romm-cli cache info
romm-cli cache clear

# Rotate credentials without re-entering ROM path/base URL
romm-cli auth status
romm-cli auth login --token-file ~/.romm-token
romm-cli auth logout
```

On interactive startup, `romm-cli` and `romm-tui` check for newer releases and can prompt to update now, open the online changelog, or skip.

After a chunked upload, RomM still needs a **library scan** before new games appear in search and the TUI. See [docs/scan-after-upload.md](docs/scan-after-upload.md) for batch uploads, `--wait`, JSON output, and cache behavior.

Save sync commands use RomM sync endpoints introduced in the `4.9.0-alpha.2` pre-release. For details and the full manifest schema, see [docs/save-sync.md](docs/save-sync.md).

---

## Project layout

- **`src/frontend`**: Routing between CLI and TUI execution.
- **`src/commands`**: CLI argument parsing and non-TUI command logic.
- **`src/endpoints`**: Typed RomM API routes (`Endpoint` trait).
- **`src/services`**: Thin helpers over endpoints (e.g. platform/ROM services).
- **`src/tui`**: Terminal UI (`ratatui`, `crossterm`) and state machine (`AppScreen`).
- **`src/core`**: ROM list cache, background downloads, and related utilities.
- **`src/client.rs`**: HTTP client wrapper around `reqwest`.
- **`src/config.rs`**: Layered environment loading and keyring integration.

---

## 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.*
