Command Line Interface

Command-Line Interface

TrayIconGuard.exe is one binary with three personalities: a tray-resident GUI (no arguments), a headless guard (--watch), and one-shot CLI verbs for scripting and monitoring. This page lists every flag with its exact effect and, where measured, the exact output and exit code produced by the build studied at commit 124e849 under a Wine test harness (see Troubleshooting for the environment's limits). Exit codes are a stable contract: 0 ok · 1 invalid arguments · 2 unsupported OS/store · 3 partial failure.

---

Contents

• Command table
• Measured output samples
• Exit-code contract and its rough edges
• Single instance and IPC
• Deployment recipes
• See also

---

Command table

Command	Effect	Exit
(no args)	Start the GUI; restores window position/size/page from settings; first run shows the setup wizard	0 on normal exit
--minimized, -m	Start the GUI hidden in the notification area (this is what autostart uses)	—
--show	IPC: activate the window of a running instance; 3 when none runs	0 / 3
--toggle-guard	IPC: pause or resume the guard of a running instance; 3 when none runs	0 / 3
--status	Print human-readable tray state and exit	0
--status --json	Same data as JSON; stdout carries nothing else	0
--promote-all	Reconcile pass now (mode-aware), apply legacy belt + HideSCA cleanup, optional auto-backup	0 / 2 / 3
--restore-defaults	Delete all IsPromoted values and the legacy belt value	0 / 2
--restart-explorer	Kill shell, wait ≤8 s, start manually if absent	0 / 3
--backup	Write a schema-8 snapshot to the backups folder	0 / 3
--restore-latest	Apply the newest snapshot	0 / 3
--watch	Headless guard loop (Ctrl+C stops)	0 / 2
--install-autostart	Add HKCU\…\Run\TrayIconGuard = "<exe>" --minimized	0 / 3
--uninstall-autostart	Remove that Run value	0 / 3
--uninstall	Exit running instance, remove shortcuts/autostart/Apps-&-Features entry, schedule self-delete of the install folder	0 / 3
--mode <full|custom|compact>	Set the visibility mode, run an immediate pass, print it	0
--check-update	Fetch the feed and compare versions	0 / 3
--update-now	Fetch, download, SHA-256 verify, apply, relaunch (no confirmation in CLI mode)	0 / 3
--ui-test [page]	QA: render one page (dashboard icons guard appearance backups activity about), self-capture %TEMP%\tig-uitest-<page>.png, exit	0
--version, -v	Print version	0
--help, -h, /?	Print help	0

Parsing notes (src/core/cli.cpp:138-176): flags are case-insensitive and trimmed; --json and --force are modifiers; --mode and --ui-test consume the next argument when it does not start with -; any unknown argument fails parsing.

Measured output samples

All captured 2026-10-16 from the HEAD build (self-reported version 8.3.0) in a Wine prefix whose store is absent — which conveniently exercises the unsupported-store paths:

$ TrayIconGuard.exe --version
TrayIconGuard 8.3.0 (native x64, zero dependencies)          [exit 0]

$ TrayIconGuard.exe --status
TrayIconGuard 8.0.0 "Aurora" — status
  OS:               Windows 10  (build 7601)
  Icon store:       NOT SUPPORTED on this build
  Icons:            0 total, 0 promoted, 0 hidden, 0 excluded
  EnableAutoTray:   (absent)
  HideSCA* policies: 0 active
  Autostart:        not installed
  Guard (this CLI): n/a (use GUI or --watch)                 [exit 0]

$ TrayIconGuard.exe --promote-all
error: NotifyIconSettings store not supported on this Windows build   [exit 2]

$ TrayIconGuard.exe --backup
backup failed: NotifyIconSettings store is not present on this Windows build  [exit 3]

$ TrayIconGuard.exe --restore-latest
no snapshots found                                            [exit 3]

$ TrayIconGuard.exe --mode full
display mode: full                                            [exit 0]

$ TrayIconGuard.exe --check-update
feed: https://raw.githubusercontent.com/paulmann/windows-show-all-tray-icons/main/update/stable.json  latest=8.4.0  newer=yes  [exit 0]

JSON shape (--status --json, verbatim from the same run):

{
  "app": "TrayIconGuard 8.0.0",
  "os": "Windows 10  (build 7601)",
  "build": 7601,
  "storeSupported": false,
  "total": 0,
  "promoted": 0,
  "hidden": 0,
  "excluded": 0,
  "enableAutoTray": -1,
  "hideScaPolicies": 0,
  "autostart": false,
  "icons": []
}

The help text prints 18 command lines and the exit-code legend; its banner in the studied builds reads TrayIconGuard 8.1.0 "Aurora" — … — a hardcoded string, part of the version-drift record in Changelog and Versioning.

Exit-code contract and its rough edges

Two UX gaps were measured on the 8.3.0/8.4.0 builds; the first is fixed in 8.6.2:

Note

• Invalid arguments used to exit 1 without any output (the parser built an unknown argument: … message that wWinMain discarded). Since 8.6.2 the CLI prints error: <reason> plus a --help hint and still exits 1; the side effect (forwarding show to a running GUI instance) is unchanged.
• --restore-defaults and --watch exit 2 on unsupported stores silently, while --promote-all prints an explanatory line. Monitoring that branches on exit 2 should log the command name itself.
• Redirected output used to be discarded on real Windows (8.6.0): --status --json > file produced an empty file. Fixed in 8.6.2 — > and pipes now receive the same bytes the console shows. See Testing and QA.

3 (“partial failure”) covers: no running instance for IPC verbs, backup/restore failures, Explorer restart failure, update download/verify/apply failure, and reconcile passes that return a negative count.

Single instance and IPC

A named mutex (TrayIconGuard.SingleInstance.v8) enforces one GUI instance: a second GUI launch sends show over WM_COPYDATA to the message-only window TrayIconGuard.Ipc.v8 (constant 0x54494738, verbs show|toggle-guard|exit) and exits 0. Headless verbs use the same channel; --uninstall asks the running GUI to exit first and waits ~1.2 s before removing files (src/core/installer.cpp).

Deployment recipes

# logon-triggered headless guard (replaces the v7 BAT/PS watcher editions)
schtasks /Create /TN TrayGuard /TR "C:\Tools\TrayIconGuard.exe --watch" /SC ONLOGON

# one-shot promotion from any script, with the documented partial-failure branch
TrayIconGuard.exe --promote-all; if ($LASTEXITCODE -ne 0) { Write-Host "partial failure or unsupported store" }

# monitoring scrape
TrayIconGuard.exe --status --json | ConvertFrom-Json | Select-Object promoted, hidden, excluded

Remember the caveat from The Guard Watcher: in the published source --watch relies on the poll timer to wake; set guard.pollMs (e.g. 5000) in settings.json for unattended deployments until the patched build is adopted.

---

See also

• Configuration Reference — every setting the CLI respects
• The Guard Watcher — what --watch actually loops on
• Self-Updater Guide — --check-update / --update-now and the feed contract
• Installation and Deployment — autostart, schtasks, MSIX