User Guide

🚀 Quick start

1. Launch Version Tracker. On first launch, a setup assistant guides you through granting Full Disk Access (needed to scan your applications), then optionally installing the package managers you want to track. Everything can be changed later in Settings.
2. Enjoy the free trial. A 7-day trial of the full version starts automatically — no credit card required. When it ends, the app returns to the free version (scanning always remains available).
3. Wait for the first scan. Depending on the number of installed apps and active sources, the initial scan takes 10 to 60 seconds.
4. Check the « All » tab. This is where all available updates from all sources are gathered.
5. Click « Update All » to launch all updates at once, or use the individual buttons to manage each app.

🗃️ Supported sources

Version Tracker detects updates for:

Each source can be enabled or disabled individually in the Settings.

🖥️ The interface

The main screen is divided into three columns, topped by a toolbar:

Left sidebar

Navigation is organized into collapsible sections that you can reorder by drag and drop. The counter next to each category shows the number of available updates.

• OVERVIEW — Dashboard (overview, recent activity, latest snapshot) and Snapshots
• UPDATES — All (every update in a single list), Apps, Packages, Homebrew, System Updates, Apple Developer Tools…
• Then sections by domain (APPLICATIONS, SYSTEM, AI, JavaScript, Python, Rust, editors…): only those matching what is actually installed on your Mac appear.

Toolbar

• Scan — runs a full scan (the button also lets you cancel a running scan)
• Settings and Feedback — direct access to preferences and the feedback form
• Two buttons to show/hide the sidebar and the Details panel

Center area

The list of items for the selected category, with a search field. Each row shows:

• The app or package icon and name
• The current version and the available version
• A contextual action button (Update, Download, Open, Show in Finder…)

Right sidebar (Details)

Details for the selected item: description, versions, release notes, source, path on disk.

Note : the window width is remembered between sessions. The minimum size is designed to comfortably display all three columns.

🔄 Updating applications

Individual update

Click the green « Update » button on a row (requires an active license or the trial — see License & trial). Depending on the source:

• Mac App Store — uses CommerceKit (silent background update)
• Homebrew Cask/Formula — runs brew upgrade (with admin authentication if needed — see below). If brew refuses the in-place upgrade, Version Tracker automatically applies the forced reinstall brew recommends.
• Sparkle — downloads the DMG/ZIP, unmounts the old version and installs the new one
• GitHub — downloads and installs the most recent binary
• Direct download — see next section

Automatic backup: when the privileged helper is enabled, the previous version of the app is backed up before every update. If anything goes wrong, restore it from Settings → Backups (retention period and number of copies are adjustable).

Batch update

The « Update All » button in the All view launches every automatable update in sequence, after a confirmation that recaps the number of updates. You can leave the view — the operation continues in the background, and a summary is shown when it finishes (including deferred updates).

Manual download (« Download »)

Some apps don't have an automatic mechanism but expose a direct download URL (PKG, DMG, ZIP). For these:

• The orange « Download » button appears
• The file is downloaded to your downloads folder (default ~/Downloads, customizable in Settings)
• Once downloaded, the button becomes « Show in Finder » to finalize installation manually

The « Download all » button starts batch downloads for all eligible apps.

If there's an error (HTTP 403, file not found, etc.), the button switches to « Open »: Version Tracker launches the installed app so it can handle its own update.

📸 Snapshots

The Snapshots view (OVERVIEW section) captures the complete software state of your Mac: applications, packages, tools, installed versions and known updates.

• Create Snapshot (⇧+⌘+N) — captures the current inventory. You can then rename or pin it.
• Compare — select two snapshots to see everything that changed between them: installed, removed or updated items, with filters by change type.
• Export… — exports a snapshot or a comparison as JSON, CSV or Markdown. Two privacy profiles: Full (keeps paths and machine name — keep it local) or Shareable (absolute paths, username and machine name are masked).

Typical use cases: documenting a machine before a migration or reinstall, tracking what an update session actually changed, or sharing a clean inventory.

Automatic snapshots

Two options in Settings → Updates:

• Automatic snapshots around “Update All” — creates an inventory snapshot before and after each batch update, to compare and document the changes.
• Snapshot after each scheduled scan — at the end of each automatic scan, creates a snapshot — only if something changed since the last one.

📋 The menu bar

Version Tracker offers a menu bar icon showing the number of pending updates. The icon animates while a scan or an update is running.

The panel

Clicking the icon opens a panel listing the available updates (your version → new version), with:

• Per-row actions: Update, Download or Open depending on the source
• The Scan, Update All and Download All buttons
• A footer with the date of the last scan and the number of tracked items
• A chevron in the header to collapse or expand the list (“Hide the list” / “Show the list”): collapsed, the panel shrinks to its header and footer

Autonomous, even with the app closed

• Open at login (Settings → General) — launches only the menu bar icon when your session starts, without opening the main window.
• Updates launched from the panel run in a background process, without opening the main window or the Dock icon.
• With Background Scan (Settings → Automation), scheduled scans — by interval or at a fixed daily time — keep running even when the app is quit: badge and notifications stay up to date.

⚙️ Settings

Settings are organized into panes:

Closing the window

• Closing the main window (⌘+W or the red button) hides the window: the app stays active in the background.
• The option « Closing the window keeps only the menu bar » (Settings → General) quits the main app on close and keeps only the menu bar icon.
• ⌘+Q really quits the application (an alert warns you if an update is in progress).

🔐 Administrator authentication

Some updates require administrator privileges. Version Tracker offers two mechanisms:

1. Privileged Helper (recommended) — a small signed daemon, enabled once and for all via Settings → General → Privileged Helper → Enable.
2. One-shot authentication — if the helper isn't installed, a system dialog asks for your admin password on each operation.

What the helper brings:

• No more password prompt on every update
• Atomic installation (the app is never left half-replaced)
• Signature and Team ID verification on the root side
• Automatic backup of the previous version before each update

Helper not responding? After an app update, use the « Repair » button in the Privileged Helper pane: it re-registers the daemon without asking for your password again.

🔑 License & trial

Version Tracker follows a freemium model:

• Free version — full scanning and inventory always remain available: you see everything that is outdated, across all sources.
• License (Solo, Family or Pro) — unlocks one-click update installs, batch updates and updates from the menu bar. See plans and pricing.
• 7-day free trial — starts automatically on first launch, no credit card required. When the trial ends, the app automatically returns to the free version.

Activating a license: open Settings → License and paste the key received by email after purchase. You can deactivate the license on one Mac to free a seat and activate it on another.

🖱️ Keyboard shortcuts

To run a full scan again, use the Scan button in the toolbar or the Scan button in the menu bar panel.

🌍 Languages

Version Tracker is available in:

• 🇬🇧 English
• 🇫🇷 French
• 🇩🇪 German
• 🇪🇸 Spanish
• 🇵🇹 Portuguese (Portugal)

The language follows macOS system settings automatically, and can be overridden in Settings → General → Language.

🗑️ Uninstalling Version Tracker

Dragging the app to the Trash is enough for most people. Here's the full procedure if you want to leave nothing behind.

Simple method (recommended)

• Open Settings and turn off General → Open at login and Automation → Background Scan.
• Quit Version Tracker and its menu bar icon (click the icon → Quit).
• Drag Version Tracker.app from /Applications to the Trash, then empty the Trash.

No rush : even without this step, any leftover traces are inert — nothing runs, nothing is root, nothing uses resources.

For a complete removal (optional)

Version Tracker installs three small components, all approved by you at install time : a privileged helper and a menu bar icon (both inside the app — they disappear with it), and a scheduled scan task (a separate file). If you skipped the step above, remove it manually :

launchctl unload ~/Library/LaunchAgents/com.jpflorencio.VersionTracker.agent.plist 2>/dev/null
rm -f ~/Library/LaunchAgents/com.jpflorencio.VersionTracker.agent.plist

To also remove your app backups and inventory snapshots (irreversible) :

rm -rf ~/Library/Application\ Support/Version\ Tracker
defaults delete com.jpflorencio.VersionTracker

Finally, if Version Tracker is still listed in System Settings → General → Login Items & Extensions, remove the entry (it disappears on its own shortly after).

Planning to reinstall or switch Macs?

• Reinstalling on the same Mac : don't touch anything — your license key stays in the keychain and activates automatically.
• Moving to another Mac : free your activation seat first via Settings → License → Deactivate, before removing the app.

Privileged helper won't reinstall? In System Settings → General → Login Items & Extensions, turn Version Tracker off, then back on (the full cycle resyncs the state — turning it on alone isn't enough). If the problem persists, empty the Trash and restart.

🗑️ Uninstalling package managers

Before you start

• Open the Terminal app (Applications → Utilities). The shell configuration file mentioned below is ~/.zshrc (the macOS default).
• Only remove tools that you installed for Version Tracker. If other software or projects depend on them, keep them.
• Uninstall individual tools first, and Homebrew last: uninstalling it removes all packages installed with it.
• After uninstalling, Version Tracker will simply stop tracking that source. You can reinstall any tool at any time from onboarding or Settings.

1. Tools installed directly by Version Tracker (via Homebrew)

Homebrew will refuse to uninstall if other formulas depend on it — that is a safeguard, not an error.

Homebrew (last) — ⚠️ removes Homebrew and every package installed with it:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/uninstall.sh)"

The script lists any residual folders at the end (usually /opt/homebrew on Apple Silicon, /usr/local/Homebrew on Intel).

2. External tools (installed via their official guides)

If you installed any of these with Homebrew instead of the official installer, simply use brew uninstall <formula> instead.

Verify

For each uninstalled tool: command -v <tool> should print nothing (open a new Terminal window first).

❓ Frequently asked questions

📩 Contact

To report a bug, suggest an improvement, or simply share feedback: contact@version-tracker.app — or use the Feedback button right inside the app.