Skip to content

cli.md

Latest commit

 

History

History
260 lines (178 loc) · 7.77 KB

cli.md

File metadata and controls

260 lines (178 loc) · 7.77 KB
Raw

romm-cli

Crates.io Docs.rs

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.

Tag Archives contain
romm-cli-v* romm-cli only
romm-tui-v* romm-tui only

Release process and versioning: releases.md. Changelog: romm-cli/CHANGELOG.md.

Features

  • Scripting and automation — resource–action subcommands with short aliases (p, r, dl, …)
  • JSON output — stable --json on stdout for platforms, ROMs, scans, sync, and more (json-output.md)
  • Authentication — romm-cli auth for login/logout without re-running init
  • Upload and scan — chunked ROM upload with optional post-upload library scan (scan-after-upload.md)
  • Save sync — device registration, plan, and run from a local manifest (save-sync.md)
  • Downloads — download extras for covers, manuals, and sibling content
  • Metadata editing — search, match, edit, and unmatch game metadata (metadata-editing.md)
  • Cache utilities — inspect and clear on-disk ROM/metadata caches
  • Self-update — interactive update check against GitHub romm-cli-v* releases
  • Shell completions — bash, zsh, fish, PowerShell, Elvish (see below)

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 ROMs and print JSON (`roms` lists by default)
romm-cli roms --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>

# Metadata: search, match, edit, unmatch (RomM 4.8+)
romm-cli roms metadata search <rom-id> --query "zelda"
romm-cli roms metadata match <rom-id> --igdb-id 1234
romm-cli roms metadata edit <rom-id> --summary "My note"

# 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 login --pairing-code ABCD1234
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.

Metadata editing

Match and edit game metadata from the CLI or TUI. Requires RomM 4.8+. See metadata-editing.md.

Configuration (config)

Inspect and persist local settings (approach D: file + env + source attribution):

romm-cli config path
romm-cli config show --sources --json
romm-cli config set theme dracula
romm-cli config env-map save_sync.device_id
romm-cli config reset --yes

config set writes config.json only; environment variables still override at runtime. Use config show --file for on-disk JSON without env merge.

Saves (saves)

Per-game save management (matches TUI game-detail Saves tab):

romm-cli saves list --rom-id 42 --json
romm-cli saves get 9
romm-cli saves download 9 --output ./game.sav [--overwrite]
romm-cli saves upload --rom-id 42 ./save.srm --emulator retroarch

Collections (collections)

List and manage library collections:

romm-cli collections list --type all --json
romm-cli collections get 3 --type manual
romm-cli collections delete 2 --type smart --yes

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

Code Meaning Typical cause
0 Success Command completed (including user-cancelled downloads)
1 General failure Unexpected error, app-level validation
2 Usage error Invalid flags or arguments (clap)
3 Config / auth Missing API_BASE_URL, bad credentials
4 API / network Server errors, connection failures, download failures

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. Generate scripts at install time with romm-cli completions <shell>:

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

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
romm-cli completions zsh > ~/.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