romm-api

Shared HTTP client, API types, configuration, and domain logic for RomM frontends (CLI, TUI, and future Android via UniFFI).

Crate path: romm-api/ in the workspace.

When to use this crate

[dependencies]
romm-api = "0.40"
tokio = { version = "1", features = ["macros", "rt-multi-thread"] }

Quick start

use romm_api::client::RommClient;
use romm_api::config::load_config;
use romm_api::error::RommError;

#[tokio::main]
async fn main() -> Result<(), RommError> {
    let config = load_config()?;
    let client = RommClient::new(&config, false)?;

    let version = client.rom_server_version_from_heartbeat().await;
    println!("Connected to RomM server version: {:?}", version);

    Ok(())
}

Run cargo doc -p romm-api --open for the full API reference.

Module overview

See HTTP client and endpoints for request/response patterns and streaming downloads.

Configuration

All frontends share the same configuration layer in romm-api::config.

Setup wizard (CLI)

The easiest way to create config.json is through the CLI:

romm-cli init

Config file location

config.json lives under the 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.

The library does not auto-load a .env file. Set environment variables in your shell or process manager.

Auth problems (keyring, Docker, CI, Windows credentials): see troubleshooting-auth.md.

API token (recommended)

romm-cli init --url https://romm.example.com --token-file ~/.romm-token --check

Prefer --token-file over --token to keep secrets out of shell history. The CLI stores the token in the OS keyring when available.

Non-interactive init 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 after saving.
• --force — Overwrite existing configuration without asking.
• --print-path — Print the path to config.json and exit.

Environment variables

Test-only variables (ROMM_TEST_*) are omitted. For auth precedence and keyring behavior, see troubleshooting-auth.md.

Configuration precedence

Settings merge per field from lowest to highest precedence:

1. Built-in defaults — HTTPS enabled, default theme, OS download folder.
2. config.json — written by romm-cli init, TUI setup, Settings, or auth login.
3. Environment variables — override config.json for matching fields.
4. OS keyring — resolves <stored-in-keyring> placeholders after env + file merge.
5. Command-specific CLI runtime — only where documented (e.g. download --output).

Examples:

• config.json has base_url https://romm.local, but API_BASE_URL=https://romm.prod is set → https://romm.prod is used.
• romm-cli download --output /tmp/roms uses /tmp/roms for that run.

There are no global --url / --token flags on normal commands. Connection settings come from env + file + keyring.

Custom console paths

Default download layout: {base Roms Dir}/{platform-slug}/.

Map individual consoles in config.json or via TUI Settings → ROMs → Console paths:

{
  "download_dir": "C:\\Games\\romm-cli",
  "roms_layout": {
    "platform_dirs": {
      "7": "D:\\Roms\\Switch",
      "3": "E:\\Roms\\NES"
    }
  }
}

Keys in platform_dirs are RomM platform IDs. Unmapped consoles use the base subfolder.

Custom console save paths

Default save layout: {Save Dir}/{platform-slug}/{game}/.

Map consoles in Settings → Saves → Save console paths or config.json:

{
  "save_sync": {
    "save_dir": "C:\\Games\\romm-cli\\saves",
    "platform_dirs": {
      "7": "D:\\Saves\\Switch",
      "3": "E:\\Saves\\NES"
    }
  }
}

Errors and exit codes

Library methods return typed errors from romm_api::error. The CLI binary maps them to process exit codes via romm_api::exit:

See CLI documentation for scripting examples.

Workspace utilities

Related documentation

• HTTP client and endpoints
• Architecture overview
• Troubleshooting authentication
• Workspace split ADR
• Android frontend design