Repository navigation
Json Output
Every command accepts --json (see Commands). It's meant for GUI wrappers and scripts that drive the CLI.
With --json, the CLI writes newline-delimited JSON (NDJSON) to stdout: one JSON object per line. Property names are camelCase, and every object has a type field that says which kind of message it is.
type |
When | Fields |
|---|---|---|
log |
Any log message at Information or above |
timestamp, level, message, exception?
|
progress |
Sampled progress for each addon (every 250ms by default) |
name, operation (Download, Extract, Expand, CheckMd5, Skipped), progress (0.0–1.0, or null when a download's size is unknown), bytesDownloaded?, totalBytes? (downloads only; totalBytes is null when unknown), complete, total, url, archiveName, downloadPath, extractPath
|
updates |
update check only, once |
count, updates[] (status: Added/Modified/Removed, addonName?, oldZipName?, newZipName?) |
checksum |
anomaly check only, one per file as it's checked |
path, status (Ok, Corrupt, NotFound), complete, total
|
prune |
cache prune check and cache prune apply, once |
count, totalBytes, archives[] (path, sizeBytes, lastWriteTime) |
profile |
config, config info and config set, once |
settingsPath, profile (every profile setting; see below) |
profiles |
config list, create, delete and use, once |
profiles[] (name, active) |
mo2SelectedProfile |
mo2 config get/set selected-profile, once |
profile |
mo2Profiles |
mo2 profiles list, once |
profiles[] (profile names) |
mods |
mo2 profile list mods, once |
profile, mods[] (name, status: Enabled/Disabled) |
mod |
mo2 mod status, enable and disable, once |
profile, name, status (Enabled/Disabled) |
logsFolder |
debug logs, once |
path |
hashProgress |
debug hash-install, at most once a second |
progress (0.0–1.0) |
hashArchive |
debug hash-install, once when finished |
path, hashType
|
result |
Always the last line |
command, success, exitCode, error?
|
command in the result line is the command you ran, for example full-install, anomaly check, config use, mo2 mod enable or debug hash-install. Running config with no subcommand reports config.
{"type":"log","timestamp":"2026-10-24T12:00:00-05:00","level":"Information","message":"Starting install"}
{"type":"progress","name":"Some Addon","operation":"Download","progress":0.42,"bytesDownloaded":4404019,"totalBytes":10485760,"complete":3,"total":120,"url":"https://...","archiveName":"addon.7z","downloadPath":"...","extractPath":"..."}
{"type":"result","command":"full-install","success":true,"exitCode":0,"error":null}Strings follow standard JSON escaping, so some characters come out as escape sequences (for example ' becomes \u0027). Any JSON parser decodes them.
Some servers don't report a download's size. GitHub archive zips are one example: they're generated on the fly, so there's no Content-Length. For those downloads, progress and totalBytes are null, and only bytesDownloaded grows. Show an indeterminate progress bar with the byte count instead of a percentage. Every download still finishes with a final update where progress is 1 and totalBytes equals bytesDownloaded.
{
"type": "progress",
"name": "MagsRedux",
"operation": "Download",
"progress": null,
"bytesDownloaded": 12998,
"totalBytes": null,
"complete": 40,
"total": 120,
"url": "https://github.com/...",
"archiveName": "...",
"downloadPath": "...",
"extractPath": "..."
}bytesDownloaded and totalBytes are only set when operation is Download. For Extract, CheckMd5 and the other operations, they're null and progress is always a number.
anomaly check writes one checksum message for each file in checksums.md5. Use complete/total for a progress bar, and collect the lines whose status isn't Ok to get the failed files. If any file fails, the result line has success: false and an error such as "3 file(s) corrupt or missing".
{"type":"checksum","path":"/games/anomaly/bin/AnomalyDX11.exe","status":"Ok","complete":1,"total":2841}
{"type":"checksum","path":"/games/anomaly/db/mods/foo.db","status":"Corrupt","complete":2,"total":2841}
{"type":"result","command":"anomaly check","success":false,"exitCode":1,"error":"1 file(s) corrupt or missing"}cache prune check writes one prune message listing the out-of-date archives that would be removed. cache prune apply writes it after deleting them, so it lists what was actually removed. When there's nothing to prune, count is 0 and archives is empty. Sizes are in bytes.
{"type":"prune","count":2,"totalBytes":734003200,"archives":[{"path":"/games/gamma/downloads/old-addon.7z","sizeBytes":524288000,"lastWriteTime":"2026-03-14T18:22:01-05:00"},{"path":"/games/gamma/downloads/other.zip","sizeBytes":209715200,"lastWriteTime":"2026-05-02T09:10:44-05:00"}]}
{"type":"result","command":"cache prune check","success":true,"exitCode":0,"error":null}config, config info and config set write a profile message with the active profile's settings. config set writes it after the change is saved. The profile object has active, profileName, anomaly, gamma, cache, mo2Profile, downloadThreads, modPackMakerUrl, modListUrl, gammaSetupRepoUrl, gammaSetupRepoBranch, stalkerGammaRepoUrl, stalkerGammaRepoBranch, gammaLargeFilesRepoUrl, gammaLargeFilesRepoBranch, teivazAnomalyGunslingerRepoUrl, teivazAnomalyGunslingerRepoBranch and pythonApiUrl.
{"type":"profile","settingsPath":"/home/user/.config/stalker-gamma/settings.json","profile":{"active":true,"profileName":"gamma","anomaly":"/games/anomaly","gamma":"/games/gamma","cache":"/games/cache","mo2Profile":"G.A.M.M.A","downloadThreads":4,"...":"..."}}
{"type":"result","command":"config info","success":true,"exitCode":0,"error":null}config list, config create, config delete and config use write a profiles message with every profile and which one is active, after any change is saved.
{"type":"profiles","profiles":[{"name":"gamma","active":true},{"name":"testing","active":false}]}
{"type":"result","command":"config use","success":true,"exitCode":0,"error":null}mo2 config get selected-profile writes the profile selected in ModOrganizer.ini. mo2 config set selected-profile writes the same message after the change is saved. If the profile doesn't exist, it writes mo2Profiles with the available profiles, then a failed result.
{"type":"mo2SelectedProfile","profile":"G.A.M.M.A"}
{"type":"result","command":"mo2 config get selected-profile","success":true,"exitCode":0,"error":null}mo2 profiles list writes the names of every MO2 profile.
{"type":"mo2Profiles","profiles":["G.A.M.M.A","Testing"]}
{"type":"result","command":"mo2 profiles list","success":true,"exitCode":0,"error":null}mo2 profile list mods <profile> writes every mod in that profile's modlist.txt.
{"type":"mods","profile":"G.A.M.M.A","mods":[{"name":"Some Addon","status":"Enabled"},{"name":"Other Addon","status":"Disabled"}]}
{"type":"result","command":"mo2 profile list mods","success":true,"exitCode":0,"error":null}mo2 mod status, mod enable and mod disable work on the active CLI profile's mo2Profile and write the mod's status. enable and disable write it after the change is saved. mo2 mod delete and mo2 profile delete write only a result.
{"type":"mod","profile":"G.A.M.M.A","name":"Some Addon","status":"Enabled"}
{"type":"result","command":"mo2 mod enable","success":true,"exitCode":0,"error":null}gog fix-install has no dedicated message. It reports what it changed through log messages (the paths it replaced in ModOrganizer.ini and any git folders it moved), then writes the result line.
{"type":"log","timestamp":"...","level":"Information","message":"ModOrganizer.ini updated","exception":null}
{"type":"result","command":"gog fix-install","success":true,"exitCode":0,"error":null}debug logs writes the full path of the logs folder, then opens it in the system file explorer.
{"type":"logsFolder","path":"/home/user/.config/stalker-gamma/logs"}
{"type":"result","command":"debug logs","success":true,"exitCode":0,"error":null}debug hash-install hashes the Anomaly, GAMMA and cache folders. While it runs, it writes hashProgress (at most once a second, and always at 100%). When it finishes, it writes hashArchive with the full path of the zip it created.
{"type":"hashProgress","progress":0.37}
{"type":"hashProgress","progress":1}
{"type":"hashArchive","path":"/home/user/stalker-gamma-cli-hashes-user.1.2.3.zip","hashType":"Sha256"}
{"type":"result","command":"debug hash-install","success":true,"exitCode":0,"error":null}- Read stdout one line at a time.
- Parse each line as JSON and switch on
type. - Ignore any line that isn't valid JSON or has a
typeyou don't recognize. Errors that happen before logging is set up (missing dependencies or no active profile) may not be JSON, and skipping unknown types keeps your parser working with newer CLI versions. - Use the
resultmessage (or the process exit code) to decide whether the command succeeded.
import json
import subprocess
proc = subprocess.Popen(
["stalker-gamma", "full-install", "--json"],
stdout=subprocess.PIPE,
text=True,
bufsize=1, # line-buffered
)
for line in proc.stdout:
try:
msg = json.loads(line)
except json.JSONDecodeError:
continue # skip non-JSON lines
match msg.get("type"):
case "log":
print(f"[{msg['level']}] {msg['message']}")
case "progress":
if msg["progress"] is not None:
amount = f"{msg['progress']:.0%}"
else:
# download size unknown: show bytes instead of a percentage
amount = f"{(msg.get('bytesDownloaded') or 0) / 1024 / 1024:.1f} MB"
print(
f"{msg['name']} | {msg['operation']} | "
f"{amount} | [{msg['complete']}/{msg['total']}]"
)
case "updates":
for u in msg["updates"]:
print(f"{u['status']}: {u.get('addonName')} | {u.get('oldZipName')} -> {u.get('newZipName')}")
case "checksum":
if msg["status"] != "Ok":
print(msg["path"], msg["status"])
case "prune":
print(f"{msg['count']} archive(s), {msg['totalBytes'] / 1024 / 1024:.0f} MB")
for a in msg["archives"]:
print(f" {a['path']}")
case "profile":
print(f"{msg['profile']['profileName']} ({msg['settingsPath']})")
case "profiles":
for p in msg["profiles"]:
print(f"{'-> ' if p['active'] else ' '}{p['name']}")
case "mo2SelectedProfile":
print(f"Selected MO2 profile: {msg['profile']}")
case "mo2Profiles":
for name in msg["profiles"]:
print(name)
case "mods":
for m in msg["mods"]:
print(f"{m['status']:<9} | {m['name']}")
case "mod":
print(f"{msg['status']:<9} | {msg['name']}")
case "logsFolder":
print(f"Logs: {msg['path']}")
case "hashProgress":
print(f"Hashing {msg['progress']:.0%}")
case "hashArchive":
print(f"Hashes ({msg['hashType']}) written to {msg['path']}")
case "result":
print("Done." if msg["success"] else f"Failed: {msg.get('error')}")
proc.wait()