# romm-cli
[](https://crates.io/crates/romm-cli)
[](https://docs.rs/romm-cli)
Command-line interface for scripting and automation against a [RomM](https://github.com/romm-retro/romm) server. Depends on [`romm-api`](api.md) 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
```bash
cargo install romm-cli
```
For the interactive terminal UI, install the separate [`romm-tui`](tui.md) crate.
### Binary releases
Prebuilt archives for Windows, Linux, and macOS are on the [Releases page](https://github.com/patricksmill/romm-cli/releases).
| `romm-cli-v*` | `romm-cli` only |
| `romm-tui-v*` | `romm-tui` only |
Release process and versioning: [releases.md](releases.md). Changelog: [romm-cli/CHANGELOG.md](../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](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](scan-after-upload.md))
- **Save sync** — device registration, plan, and run from a local manifest ([save-sync.md](save-sync.md))
- **Downloads** — `download extras` for covers, manuals, and sibling content
- **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:
```bash
romm-cli init
```
Full details (environment variables, precedence, custom paths, keyring): **[romm-api configuration](api.md#configuration)**.
**Auth troubleshooting:** [troubleshooting-auth.md](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
```bash
# 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>
# 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](api.md#environment-variables)).
### 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](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](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](json-output.md) for field reference and versioning policy.
---
## Exit codes
| 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:
```bash
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>`:
```bash
romm-cli completions bash
romm-cli completions zsh
romm-cli completions fish
romm-cli completions powershell
romm-cli completions elvish
```
**Bash** — user install:
```bash
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):
```bash
mkdir -p ~/.zfunc
romm-cli completions zsh > ~/.zfunc/_romm-cli
# Add to ~/.zshrc before compinit:
# fpath=(~/.zfunc $fpath); autoload -Uz compinit; compinit
```
**Fish**:
```bash
romm-cli completions fish > ~/.config/fish/completions/romm-cli.fish
```
**PowerShell**:
```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:
```rust
use romm_cli::client::RommClient;
use romm_cli::config::load_config;
```
New embedders should depend on [`romm-api`](api.md) directly.
---
## Related documentation
- [Changelog](../romm-cli/CHANGELOG.md)
- [romm-api](api.md) — configuration, HTTP client, errors
- [romm-tui](tui.md) — terminal UI
- [Save sync](save-sync.md)
- [Post-upload library scan](scan-after-upload.md)
- [JSON output](json-output.md)