Usage Global Behavior

Global behavior

Part of the Usage reference. · Next: Authentication →

• -j, --json: A global flag accepted by every command (before or after the command, e.g. aurelia --json list or aurelia list -j). Output is emitted as JSON on stdout. Diagnostics and progress are written to stderr, so stdout stays clean for piping into tools like jq. Errors are printed as a single JSON line with a machine-readable type, see Exit codes & logging.

• -v, --verbose: A global, repeatable flag that increases log verbosity. Logs are written to stderr. At the default level Aurelia prints high-level progress (connecting, fetching owned games, …) while the chatty Steam networking stack is quieted. -v, -vv and -vvv progressively unmute it. This is the way to diagnose a command that appears to hang: the last line printed shows exactly which step is stuck (typically a Steam CM connection or RPC). RUST_LOG/AURELIA_LOG (standard tracing env-filter syntax, e.g. RUST_LOG=steam_vent=trace) override the flag entirely.

• Short flags: Since v0.1.37-2, almost every option has a one-letter short form (shown in each command's option table and in --help). Within one command no two flags share a letter, and the same letter means the same thing across commands where possible:

  Short	Long	Used by
  -j	--json	every command
  -c	--country (alias --cc)	info, price, search, deals, similar, events, wishlist
  -l	--lang (alias --language)	info, achievements, the store commands, wishlist
  -n	--count	listing commands (search, deals, news, reviews, chat history, …)
  -r	--restart-steam	install, move, relink, import, enable, disable
  -f	--force	update, stop, image, scripts new
  -R	--no-recurse	the workshop install/subscribe commands
  -N	--no-update / --no-pin	play / downgrade

  play --noupdate is now play --no-update (-N). The old spelling still works as an alias.

• Session: After login, a refresh token is stored so subsequent commands reuse the session automatically. Commands that need Steam (account, install, play, …) fail with not logged in — run \aurelia login` first ("type": "auth_required"`, exit code 77) if no valid session exists. If the stored session exists but Steam refused it, the error says why (e.g. rate limiting) instead. The session file is encrypted with a key kept in your OS keyring, see Authentication.

• Region and language: Commands that show store text or prices pick the language from --lang, then config language, then the system locale, then English. The price country comes from --country, then config country, then the system locale, then US. The locale is read from LC_ALL, LC_MESSAGES, LC_MONETARY and LANG, in that order (e.g. de_DE.UTF-8 means German and DE, pt_BR means brazilian and BR).

• Rate limits and retries: Web requests (storefront, GitHub, Proton downloads, image probes) are retried up to three times on timeouts, connection errors and HTTP 502–504, with exponential backoff. An HTTP 429 that asks for a wait of 30 seconds or less is waited out and retried. Otherwise the command fails fast with "type": "rate_limited" (exit code 75) and, when the server said, retry_after_seconds.

• Library discovery: Installed games are detected across all Steam libraries, including secondary libraries on other drives (e.g. F:\SteamLibrary) even if they are not listed in libraryfolders.vdf.

• Unsafe directory names: Aurelia never creates, moves, relinks or deletes an install directory whose name could leave steamapps/common (an empty name, ., .., or anything with a path separator). An install whose installdir would be unsafe is placed in _. uninstall, move and relink refuse to touch such an install, and proton uninstall rejects such a runtime name.

• Logging: Set RUST_LOG to control tracing verbosity, e.g. RUST_LOG=debug (to stderr).

• Config location: Aurelia stores its session, config, caches and launch logs under ~/.config/Aurelia by default. Set AURELIA_CONFIG_DIR to relocate them, useful for an embedding driver (e.g. Heroic) that needs Aurelia's state isolated from a user's standalone install.

• AURELIA_DIAGNOSE_INSTALL=1: opt-in diagnostic mode for the Windows Steam runtime install/repair flow, which runs the installer with verbose WINEDEBUG and captures output to a timestamped log under ~/.config/Aurelia/logs/. No effect on normal game launches.

<APP_ID> is the numeric Steam application id (visible via aurelia list, or find one with search).