aethervault-py 6.4.0__tar.gz

aethervault_py-6.4.0/LICENSE

@@ -0,0 +1,17 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2026 AetherLock Contributors
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.

aethervault_py-6.4.0/MANIFEST.in

@@ -0,0 +1,10 @@
+# Created: 2026-07-27
+# Last Edited: 2026-08-05 16:46 CT (America/Chicago)
+# Path: MANIFEST.in
+# Purpose: Include package data files in the source distribution for pip builds.
+
+include aethervault/docs/USER_GUIDE.md
+include aethervault/docs/USER_GUIDE.html
+include aethervault/assets/aethersol.ico
+include aethervault/assets/aethersol_logo.png
+recursive-include aethervault/assets/screens *.png *.gif

aethervault_py-6.4.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: aethervault-py
+Version: 6.4.0
+Summary: A secure, local-first password manager with AES-256 encryption
+Author: AetherVault Team
+License: GPL-3.0-only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PySide6>=6.5.0
+Requires-Dist: cryptography>=41.0.0
+Dynamic: license-file
+
+<pre align="center">
+╔══════════════════════════════╗
+║       A E T H E R V A U L T  ║
+║   Encrypted Password Vault   ║
+╚══════════════════════════════╝
+</pre>
+
+<h1 align="center">AetherVault</h1>
+
+<p align="center">
+  <em>Encrypted, local-first password manager</em>
+  <br>
+  Store, organize, and protect your credentials — encrypted with AES-256, right on your machine.
+  <br>
+  <strong><em>Your data stays yours. No cloud. No servers.</em></strong>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Linux-%E2%9C%93-informational?logo=linux&logoColor=white" alt="Linux">
+  <img src="https://img.shields.io/badge/macOS-%E2%9C%93-informational?logo=apple&logoColor=white" alt="macOS">
+  <img src="https://img.shields.io/badge/Windows-%E2%9C%93-informational?logo=windows&logoColor=white" alt="Windows">
+  <img src="https://img.shields.io/badge/python-3.10+-blue?logo=python" alt="Python 3.10+">
+  <img src="https://img.shields.io/badge/license-GPLv3-blue" alt="GPLv3">
+  <img src="https://img.shields.io/badge/PySide6-6.5+-green" alt="PySide6 6.5+">
+  <img src="https://img.shields.io/pypi/v/aethervault-py?logo=pypi&logoColor=white&color=3776AB" alt="PyPI">
+  <img src="https://github.com/AetherSolDev/AetherVault/actions/workflows/build.yml/badge.svg" alt="Build">
+</p>
+
+---
+
+## Screenshots
+
+![Demo](aethervault/assets/screens/aethervault-demo.gif)
+
+![Login](aethervault/assets/screens/login.png)
+![Vault](aethervault/assets/screens/vault.png)
+![Entry](aethervault/assets/screens/entry.png)
+![Generator](aethervault/assets/screens/generator.png)
+![Health](aethervault/assets/screens/health.png)
+
+---
+
+## Features
+
+- **AES-256 encryption** — every password encrypted with Fernet (cryptography library), key derived with PBKDF2-SHA256
+- **Master password auth** — setup/login flow; only the PBKDF2 hash is stored
+- **Credential management** — add, edit, delete, search, sort, filter
+- **Password generator** — configurable length and character sets
+- **Password strength meter** — real-time scoring as you type
+- **Password health report** — scan for weak, reused, or short passwords
+- **Category & tag filters** — dynamic dropdowns, category click-to-filter
+- **Custom fields** — key/value pairs on any entry (JSON-backed)
+- **Rich text notes** — bold / italic / underline formatting toolbar
+- **Favicon auto-fetch** — site icons pulled from Google's service
+- **System tray** — minimize to tray, quick-lock from the tray menu
+- **Dark / light theme** — toggle in Settings, persists across sessions
+- **Auto-lock** — configurable 1/3/5/10/30 minutes or never
+- **Duress password** *(optional)* — entering it at login permanently destroys the vault and all backups, indistinguishable from a failed login
+- **Clipboard auto-clear** — copied passwords clear after 15 seconds
+- **One-click backup** — timestamped filenames, auto-rotation keeps the 5 most recent
+- **CSV import / export** — bulk add or migrate from other managers
+- **Duplicate detection** — find and remove entries with matching title + username
+- **Portable mode** — all data stays in the app directory (`.portable` marker)
+- **Startup integrity check** — auto-detects corruption and recovers from backup
+
+---
+
+## Download a Pre-Built Executable
+
+No Python or pip needed. Grab the binary for your platform from the
+[Releases](https://github.com/AetherSolDev/AetherVault/releases) page
+(or the latest [Actions build](https://github.com/AetherSolDev/AetherVault/actions) artifacts):
+
+> Prefer a package manager? **`pip install aethervault-py`** (PyPI) works on Linux, macOS, and Windows.
+
+| Platform | Download |
+|----------|----------|
+| Windows (x86_64) | [aethervault-windows-x86_64.exe](https://github.com/AetherSolDev/AetherVault/releases/latest/download/aethervault-windows-x86_64.exe) |
+| Linux (x86_64) | [aethervault-linux-x86_64](https://github.com/AetherSolDev/AetherVault/releases/latest/download/aethervault-linux-x86_64) |
+| macOS (Apple Silicon) | [aethervault-macos-arm64](https://github.com/AetherSolDev/AetherVault/releases/latest/download/aethervault-macos-arm64) |
+| macOS (Intel) | [aethervault-macos-x86_64](https://github.com/AetherSolDev/AetherVault/releases/latest/download/aethervault-macos-x86_64) |
+
+> The binaries are unsigned, so Windows SmartScreen and macOS Gatekeeper may warn on first run.
+> Windows: click **More info → Run anyway**. macOS: `xattr -d com.apple.quarantine aethervault-macos`.
+> Linux: the binary expects standard Qt/X11 system libraries.
+
+---
+
+## Quick Start
+
+### Install
+
+AetherVault is on **PyPI** (`aethervault-py`) and published to GitHub Releases on every version tag.
+
+**Option 1 — pip (recommended, all platforms):**
+```bash
+pip install aethervault-py
+# or
+pip install --user aethervault-py
+```
+
+**Option 2 — Global install (editable):**
+```bash
+git clone https://github.com/AetherSolDev/AetherVault.git
+cd AetherVault
+pip install --user --break-system-packages -e .
+```
+
+**Option 3 — Virtual environment:**
+```bash
+git clone https://github.com/AetherSolDev/AetherVault.git
+cd AetherVault
+python -m venv venv
+source venv/bin/activate   # Windows: venv\Scripts\activate
+pip install -e .
+```
+
+**Option 4 — Build yourself (PyInstaller):**
+```bash
+pip install pyinstaller
+pyinstaller aethervault.spec
+# Output in dist/aethervault/
+```
+
+### Run
+
+```bash
+aethervault            # Launch GUI (auto-detaches from terminal on Unix)
+aethervault --version  # Show installed version
+aethervault --help     # CLI usage
+```
+
+---
+
+## Usage
+
+1. **First launch** — set a master password (minimum 8 characters)
+2. **Login** — enter your master password to unlock the vault
+3. **Add entries** — click "Add New" and fill in the form
+4. **Generate passwords** — click "Generate" next to the password field
+5. **Copy to clipboard** — double-click a table cell or click the "Copy" buttons
+6. **Organize** — categories and tags group your entries
+7. **Backup** — File → Backup Vault (or auto-backup on save/shutdown)
+
+| CLI Command | Description |
+|-------------|-------------|
+| `aethervault` | Launch the GUI (auto-detaches on Unix) |
+| `aethervault --version` | Show installed version |
+| `aethervault --debug` | Launch with debug logging |
+| `aethervault --upgrade` / `-u` | Check for updates and auto-upgrade |
+| `aethervault --foreground` / `-f` | Keep terminal attached (debugging) |
+
+---
+
+## Security
+
+- Passwords are **never stored in plain text** — AES-256 via Fernet
+- Master password is **never stored** — only its PBKDF2-SHA256 hash
+- Encryption key derived from the master password hash (PBKDF2, 480K iterations)
+- Clipboard **auto-cleared** after 15 seconds
+- Auto-lock on **inactivity** or window focus loss
+- SQLite with **parameterized queries** (no SQL injection)
+- Startup **integrity check** with automatic recovery from backup
+- Optional **duress password** — destroys the vault on coercion
+
+---
+
+## Data
+
+| Data | Location |
+|------|----------|
+| Encrypted vault | `data/aethervault.db` |
+| Master password hash | `data/.master.key` |
+| App settings | `data/.app_settings.json` |
+| Portable marker | `.portable` (enables portable mode) |
+
+---
+
+## Documentation
+
+Full user guide: [`aethervault/docs/USER_GUIDE.md`](aethervault/docs/USER_GUIDE.md)
+
+---
+
+## License
+
+[GPLv3](LICENSE) — Free as in freedom.

aethervault_py-6.4.0/README.md

@@ -0,0 +1,187 @@
+<pre align="center">
+╔══════════════════════════════╗
+║       A E T H E R V A U L T  ║
+║   Encrypted Password Vault   ║
+╚══════════════════════════════╝
+</pre>
+
+<h1 align="center">AetherVault</h1>
+
+<p align="center">
+  <em>Encrypted, local-first password manager</em>
+  <br>
+  Store, organize, and protect your credentials — encrypted with AES-256, right on your machine.
+  <br>
+  <strong><em>Your data stays yours. No cloud. No servers.</em></strong>
+</p>
+
+<p align="center">
+  <img src="https://img.shields.io/badge/Linux-%E2%9C%93-informational?logo=linux&logoColor=white" alt="Linux">
+  <img src="https://img.shields.io/badge/macOS-%E2%9C%93-informational?logo=apple&logoColor=white" alt="macOS">
+  <img src="https://img.shields.io/badge/Windows-%E2%9C%93-informational?logo=windows&logoColor=white" alt="Windows">
+  <img src="https://img.shields.io/badge/python-3.10+-blue?logo=python" alt="Python 3.10+">
+  <img src="https://img.shields.io/badge/license-GPLv3-blue" alt="GPLv3">
+  <img src="https://img.shields.io/badge/PySide6-6.5+-green" alt="PySide6 6.5+">
+  <img src="https://img.shields.io/pypi/v/aethervault-py?logo=pypi&logoColor=white&color=3776AB" alt="PyPI">
+  <img src="https://github.com/AetherSolDev/AetherVault/actions/workflows/build.yml/badge.svg" alt="Build">
+</p>
+
+---
+
+## Screenshots
+
+![Demo](aethervault/assets/screens/aethervault-demo.gif)
+
+![Login](aethervault/assets/screens/login.png)
+![Vault](aethervault/assets/screens/vault.png)
+![Entry](aethervault/assets/screens/entry.png)
+![Generator](aethervault/assets/screens/generator.png)
+![Health](aethervault/assets/screens/health.png)
+
+---
+
+## Features
+
+- **AES-256 encryption** — every password encrypted with Fernet (cryptography library), key derived with PBKDF2-SHA256
+- **Master password auth** — setup/login flow; only the PBKDF2 hash is stored
+- **Credential management** — add, edit, delete, search, sort, filter
+- **Password generator** — configurable length and character sets
+- **Password strength meter** — real-time scoring as you type
+- **Password health report** — scan for weak, reused, or short passwords
+- **Category & tag filters** — dynamic dropdowns, category click-to-filter
+- **Custom fields** — key/value pairs on any entry (JSON-backed)
+- **Rich text notes** — bold / italic / underline formatting toolbar
+- **Favicon auto-fetch** — site icons pulled from Google's service
+- **System tray** — minimize to tray, quick-lock from the tray menu
+- **Dark / light theme** — toggle in Settings, persists across sessions
+- **Auto-lock** — configurable 1/3/5/10/30 minutes or never
+- **Duress password** *(optional)* — entering it at login permanently destroys the vault and all backups, indistinguishable from a failed login
+- **Clipboard auto-clear** — copied passwords clear after 15 seconds
+- **One-click backup** — timestamped filenames, auto-rotation keeps the 5 most recent
+- **CSV import / export** — bulk add or migrate from other managers
+- **Duplicate detection** — find and remove entries with matching title + username
+- **Portable mode** — all data stays in the app directory (`.portable` marker)
+- **Startup integrity check** — auto-detects corruption and recovers from backup
+
+---
+
+## Download a Pre-Built Executable
+
+No Python or pip needed. Grab the binary for your platform from the
+[Releases](https://github.com/AetherSolDev/AetherVault/releases) page
+(or the latest [Actions build](https://github.com/AetherSolDev/AetherVault/actions) artifacts):
+
+> Prefer a package manager? **`pip install aethervault-py`** (PyPI) works on Linux, macOS, and Windows.
+
+| Platform | Download |
+|----------|----------|
+| Windows (x86_64) | [aethervault-windows-x86_64.exe](https://github.com/AetherSolDev/AetherVault/releases/latest/download/aethervault-windows-x86_64.exe) |
+| Linux (x86_64) | [aethervault-linux-x86_64](https://github.com/AetherSolDev/AetherVault/releases/latest/download/aethervault-linux-x86_64) |
+| macOS (Apple Silicon) | [aethervault-macos-arm64](https://github.com/AetherSolDev/AetherVault/releases/latest/download/aethervault-macos-arm64) |
+| macOS (Intel) | [aethervault-macos-x86_64](https://github.com/AetherSolDev/AetherVault/releases/latest/download/aethervault-macos-x86_64) |
+
+> The binaries are unsigned, so Windows SmartScreen and macOS Gatekeeper may warn on first run.
+> Windows: click **More info → Run anyway**. macOS: `xattr -d com.apple.quarantine aethervault-macos`.
+> Linux: the binary expects standard Qt/X11 system libraries.
+
+---
+
+## Quick Start
+
+### Install
+
+AetherVault is on **PyPI** (`aethervault-py`) and published to GitHub Releases on every version tag.
+
+**Option 1 — pip (recommended, all platforms):**
+```bash
+pip install aethervault-py
+# or
+pip install --user aethervault-py
+```
+
+**Option 2 — Global install (editable):**
+```bash
+git clone https://github.com/AetherSolDev/AetherVault.git
+cd AetherVault
+pip install --user --break-system-packages -e .
+```
+
+**Option 3 — Virtual environment:**
+```bash
+git clone https://github.com/AetherSolDev/AetherVault.git
+cd AetherVault
+python -m venv venv
+source venv/bin/activate   # Windows: venv\Scripts\activate
+pip install -e .
+```
+
+**Option 4 — Build yourself (PyInstaller):**
+```bash
+pip install pyinstaller
+pyinstaller aethervault.spec
+# Output in dist/aethervault/
+```
+
+### Run
+
+```bash
+aethervault            # Launch GUI (auto-detaches from terminal on Unix)
+aethervault --version  # Show installed version
+aethervault --help     # CLI usage
+```
+
+---
+
+## Usage
+
+1. **First launch** — set a master password (minimum 8 characters)
+2. **Login** — enter your master password to unlock the vault
+3. **Add entries** — click "Add New" and fill in the form
+4. **Generate passwords** — click "Generate" next to the password field
+5. **Copy to clipboard** — double-click a table cell or click the "Copy" buttons
+6. **Organize** — categories and tags group your entries
+7. **Backup** — File → Backup Vault (or auto-backup on save/shutdown)
+
+| CLI Command | Description |
+|-------------|-------------|
+| `aethervault` | Launch the GUI (auto-detaches on Unix) |
+| `aethervault --version` | Show installed version |
+| `aethervault --debug` | Launch with debug logging |
+| `aethervault --upgrade` / `-u` | Check for updates and auto-upgrade |
+| `aethervault --foreground` / `-f` | Keep terminal attached (debugging) |
+
+---
+
+## Security
+
+- Passwords are **never stored in plain text** — AES-256 via Fernet
+- Master password is **never stored** — only its PBKDF2-SHA256 hash
+- Encryption key derived from the master password hash (PBKDF2, 480K iterations)
+- Clipboard **auto-cleared** after 15 seconds
+- Auto-lock on **inactivity** or window focus loss
+- SQLite with **parameterized queries** (no SQL injection)
+- Startup **integrity check** with automatic recovery from backup
+- Optional **duress password** — destroys the vault on coercion
+
+---
+
+## Data
+
+| Data | Location |
+|------|----------|
+| Encrypted vault | `data/aethervault.db` |
+| Master password hash | `data/.master.key` |
+| App settings | `data/.app_settings.json` |
+| Portable marker | `.portable` (enables portable mode) |
+
+---
+
+## Documentation
+
+Full user guide: [`aethervault/docs/USER_GUIDE.md`](aethervault/docs/USER_GUIDE.md)
+
+---
+
+## License
+
+[GPLv3](LICENSE) — Free as in freedom.

aethervault_py-6.4.0/aethervault/__init__.py

@@ -0,0 +1,49 @@
+# Created: 2026-07-24
+# Last Edited: 2026-08-05 17:06 CT (America/Chicago)
+# Path: aethervault/__init__.py
+# Purpose: Package init for AetherVault source. Defines PROJECT_ROOT and portable mode.
+
+"""Package initializer providing PROJECT_ROOT, version constants, and portable mode controls."""
+
+__version__ = "6.4.0"
+VERSION = __version__
+__app_name__ = "AetherVault"
+APP_NAME = __app_name__
+
+import os
+import sys
+
+if getattr(sys, "frozen", False):
+    PROJECT_ROOT = os.getcwd()
+else:
+    PROJECT_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+
+PORTABLE_MARKER = ".portable"
+
+
+def is_portable() -> bool:
+    """Return True if the portable marker file exists in PROJECT_ROOT."""
+    return os.path.exists(os.path.join(PROJECT_ROOT, PORTABLE_MARKER))
+
+
+def enable_portable_mode() -> bool:
+    """Create the portable marker file and return True, or return False on failure."""
+    try:
+        path = os.path.join(PROJECT_ROOT, PORTABLE_MARKER)
+        if not os.path.exists(path):
+            with open(path, "w") as f:
+                f.write("Portable mode enabled\n")
+        return True
+    except OSError:
+        return False
+
+
+def disable_portable_mode() -> bool:
+    """Remove the portable marker file and return True, or return False on failure."""
+    try:
+        path = os.path.join(PROJECT_ROOT, PORTABLE_MARKER)
+        if os.path.exists(path):
+            os.remove(path)
+        return True
+    except OSError:
+        return False

aethervault_py-6.4.0/aethervault/__main__.py

@@ -0,0 +1,214 @@
+# Created: 2026-07-24
+# Last Edited: 2026-08-01 01:55 CT (America/Chicago)
+# Path: aethervault/__main__.py
+# Purpose: Application entry point with CLI switches (--version, --debug, --upgrade, --foreground).
+
+"""Application entry point with CLI switches (--version, --debug, --upgrade, --foreground)."""
+
+import argparse
+import json
+import logging
+import os
+import subprocess
+import sys
+import urllib.request
+import urllib.error
+from typing import Optional
+
+from PySide6.QtCore import QTimer
+from PySide6.QtWidgets import QApplication
+
+from aethervault import PROJECT_ROOT, VERSION
+from aethervault.gui.app import PySidePWManager
+
+GITHUB_TAGS_API = "https://api.github.com/repos/AetherSolDev/AetherVault/tags"
+
+
+GIT_REPO_URL = "https://github.com/AetherSolDev/AetherVault.git"
+RELEASES_URL = "https://github.com/AetherSolDev/AetherVault/releases/latest"
+
+
+def _is_git_repo() -> bool:
+    """Return True if PROJECT_ROOT contains a .git directory."""
+    return os.path.isdir(os.path.join(PROJECT_ROOT, ".git"))
+
+
+def _get_pip_command() -> str:
+    """Return the appropriate pip command (venv or system)."""
+    in_venv = sys.prefix != sys.base_prefix
+    if in_venv:
+        return os.path.join(sys.prefix, "bin", "pip")
+    return "pip"
+
+
+def _fetch_latest_tag() -> Optional[str]:
+    """Fetch the latest version tag from GitHub. Returns tag string or None."""
+    try:
+        req = urllib.request.Request(GITHUB_TAGS_API, headers={"User-Agent": "AetherVault"})
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            tags = json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        print(f"Upgrade check failed (HTTP {e.code})")
+        return None
+    except (urllib.error.URLError, json.JSONDecodeError, OSError) as e:
+        print(f"Upgrade check failed: {e}")
+        return None
+
+    if not tags:
+        print("No version tags found on GitHub.")
+        return None
+
+    latest_tag = tags[0].get("name", "").lstrip("v")
+    if not latest_tag:
+        print("Could not determine latest version.")
+        return None
+
+    return latest_tag
+
+
+def _perform_upgrade(latest_tag: str) -> bool:
+    """Perform the actual upgrade. Returns True on success."""
+    print(f"Upgrading AetherVault v{VERSION} → v{latest_tag} ...")
+    print()
+
+    try:
+        git_env = os.environ.copy()
+        git_env["GIT_DISCOVERY_ACROSS_FILESYSTEM"] = "1"
+
+        if _is_git_repo():
+            print("1. Pulling latest code via git ...", end=" ", flush=True)
+            result = subprocess.run(
+                ["git", "pull"],
+                cwd=PROJECT_ROOT,
+                capture_output=True, text=True, timeout=60,
+                env=git_env,
+            )
+            if result.returncode != 0:
+                print("FAILED")
+                print(result.stderr)
+                print("Tip: Set git safe.directory or GIT_DISCOVERY_ACROSS_FILESYSTEM")
+                return False
+            print("done")
+
+            print("2. Reinstalling package ...", end=" ", flush=True)
+            pip_cmd = _get_pip_command()
+            result = subprocess.run(
+                [pip_cmd, "install", "-e", "."],
+                cwd=PROJECT_ROOT,
+                capture_output=True, text=True, timeout=120,
+            )
+            if result.returncode != 0:
+                print("FAILED")
+                print(result.stderr)
+                return False
+            print("done")
+        else:
+            print("1. Upgrading via pip ...", end=" ", flush=True)
+            pip_cmd = _get_pip_command()
+            result = subprocess.run(
+                [pip_cmd, "install", "--upgrade", f"git+{GIT_REPO_URL}"],
+                capture_output=True, text=True, timeout=120,
+            )
+            if result.returncode != 0:
+                print("FAILED")
+                print(result.stderr)
+                return False
+            print("done")
+
+        print(f"\nUpgrade to v{latest_tag} complete!")
+        return True
+
+    except (subprocess.TimeoutExpired, OSError) as e:
+        print(f"FAILED — {e}")
+        return False
+
+
+def check_for_upgrades() -> bool:
+    """Check GitHub tags for a newer version and upgrade if available. Returns True on success."""
+    latest_tag = _fetch_latest_tag()
+    if latest_tag is None:
+        return False
+
+    def parse_ver(v: str):
+        parts = v.split(".")
+        return tuple(int(p) if p.isdigit() else 0 for p in parts[:3])
+
+    current = parse_ver(VERSION)
+    latest = parse_ver(latest_tag)
+
+    if latest <= current:
+        print(f"You're up to date! (v{VERSION})")
+        return False
+
+    return _perform_upgrade(latest_tag)
+
+
+def detach_from_terminal():
+    """Fork and release the terminal (Unix only). Parent exits, child continues."""
+    try:
+        pid = os.fork()
+        if pid > 0:
+            sys.exit(0)
+        os.setsid()
+        devnull = os.open(os.devnull, os.O_RDWR)
+        os.dup2(devnull, 0)
+        os.dup2(devnull, 1)
+        os.dup2(devnull, 2)
+        os.close(devnull)
+    except OSError:
+        pass
+
+
+def run():
+    """Parse CLI arguments and run the application."""
+    parser = argparse.ArgumentParser(description="AetherVault — secure password manager")
+    parser.add_argument(
+        "--version", "-v",
+        action="store_true",
+        help="Show version and exit",
+    )
+    parser.add_argument(
+        "--debug", "-d",
+        action="store_true",
+        help="Enable debug logging to terminal",
+    )
+    parser.add_argument(
+        "--upgrade", "-u",
+        action="store_true",
+        help="Check for updates and auto-upgrade (git pull + pip install)",
+    )
+    parser.add_argument(
+        "--foreground", "-f",
+        action="store_true",
+        help="Keep terminal attached (for debugging)",
+    )
+    args = parser.parse_args()
+
+    if args.version:
+        print(f"AetherVault v{VERSION}")
+        sys.exit(0)
+
+    if args.upgrade:
+        check_for_upgrades()
+        sys.exit(0)
+
+    if args.debug:
+        logging.basicConfig(
+            level=logging.DEBUG,
+            stream=sys.stderr,
+            format="%(levelname)s:%(name)s:%(message)s",
+        )
+
+    if not args.foreground and sys.platform != "win32":
+        detach_from_terminal()
+
+    app = QApplication(sys.argv)
+    app.setStyle("Fusion")
+    window = PySidePWManager()
+    window.show()
+    QTimer.singleShot(500, window.check_setup_state)
+    sys.exit(app.exec())
+
+
+if __name__ == "__main__":
+    run()