romm-cli

Command-line interface for scripting and automation against a RomM server. Depends on romm-api for HTTP, config, and domain logic.

Crate path: romm-cli/ in the workspace. The romm-cli binary is the primary user-facing tool.

Install

Cargo

cargo install romm-cli

For the interactive terminal UI, install the separate romm-tui crate.

Binary releases

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

Release process and versioning: releases.md.

Configuration

Run the setup wizard:

romm-cli init

Full details (environment variables, precedence, custom paths, keyring): romm-api configuration.

Auth troubleshooting: troubleshooting-auth.md.

Usage

Run romm-cli --help or romm-cli <command> --help for the full flag list. Many subcommands have short aliases (e.g. setup for init, p for platforms, r for roms, dl for download).

Common commands

# List platforms
romm-cli platforms

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

# Upload a ROM, 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; optional --wait
romm-cli scan
romm-cli scan --wait --wait-timeout-secs 3600

# Save sync (RomM 4.9.0-alpha.2+)
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 checks for newer releases and can prompt to update. Disable with ROMM_CHECK_UPDATES=false (see api.md).

Post-upload library scan

After chunked uploads, RomM needs a library scan before new games appear in search and the TUI. See scan-after-upload.md.

Save sync

Save sync uses RomM sync endpoints from the 4.9.0-alpha.2 pre-release onward. See save-sync.md for manifest schema and conflict handling.

JSON output

Commands that support --json emit stable, machine-readable JSON on stdout. Progress and status go to stderr. See json-output.md for field reference and versioning policy.

Exit codes

Example:

romm-cli platforms
case $? in
  0) echo ok ;;
  3) echo "fix config or auth" ;;
  4) echo "API or network issue" ;;
  *) echo "other failure" ;;
esac

Errors are printed to stderr with actionable hints (for example, suggesting romm-cli init or romm-cli auth).

Shell completions

Tab completion is available for bash, zsh, fish, PowerShell, and Elvish. Scripts live in romm-cli/completions/ and can be regenerated at runtime:

romm-cli completions bash
romm-cli completions zsh
romm-cli completions fish
romm-cli completions powershell

Bash — user install:

mkdir -p ~/.local/share/bash-completion/completions
romm-cli completions bash > ~/.local/share/bash-completion/completions/romm-cli

Zsh — clap generates _romm-cli (underscore prefix required):

mkdir -p ~/.zfunc
cp romm-cli/completions/_romm-cli ~/.zfunc/_romm-cli
# Add to ~/.zshrc before compinit:
# fpath=(~/.zfunc $fpath); autoload -Uz compinit; compinit

Fish:

romm-cli completions fish > ~/.config/fish/completions/romm-cli.fish

PowerShell:

romm-cli completions powershell > $PROFILE.CurrentUserCurrentHost

Start a new shell session after installing completions.

Library use

The romm-cli crate re-exports romm_api modules for backward compatibility with existing crates.io consumers:

use romm_cli::client::RommClient;
use romm_cli::config::load_config;

New embedders should depend on romm-api directly.

Related documentation

• romm-api — configuration, HTTP client, errors
• romm-tui — terminal UI
• Save sync
• Post-upload library scan
• JSON output