Skip to content

Json Output

FaithBeam edited this page Oct 28, 2026 · 5 revisions

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.

Download progress

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 output

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 output

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 output

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 output

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 output

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 output

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}

Parsing

  1. Read stdout one line at a time.
  2. Parse each line as JSON and switch on type.
  3. Ignore any line that isn't valid JSON or has a type you 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.
  4. Use the result message (or the process exit code) to decide whether the command succeeded.

Python example

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()

Clone this wiki locally