termux-sync 1.2.3__tar.gz → 1.2.6__tar.gz

{termux_sync-1.2.3 → termux_sync-1.2.6}/CHANGELOG.md

@@ -9,6 +9,33 @@ Version numbers follow [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+---
+
+## [1.2.6] - 2026-10-15
+
+### Changed
+- Errors are now shown as a clean panel (what happened, where, how to fix) instead of a raw Python traceback. The full traceback is written to the log file; use `--debug` to print it.
+- `termux-sync help` / `-h` now renders a grouped, readable help screen instead of the long argparse dump.
+- Unknown commands show "Did you mean ...?" suggestions (and point `update` to `tsctl updater`).
+- Closed input (EOF / Ctrl+D) during a prompt is reported clearly instead of crashing.
+
+### Fixed
+- Missing `rich` no longer causes a `NameError`; it is installed automatically on first run.
+- Invalid "Max backups" input in `setup` no longer crashes.
+- Error text containing square brackets can no longer break rich markup.
+
+---
+
+## [1.2.4] - 2026-07-28
+
+### Security
+
+- **`restore` — arbitrary file write via attacker-controlled `source` field in `manifest.json` (High, GHSA-259w-wmqg-fp76)** — during restore, `manifest["files"][key]["source"]` was taken from the backup archive itself (fully attacker-controlled) and used directly as the extraction destination, and `extract_archive()` called `tarfile.extract()` on every member with no path-containment check. A malicious or tampered backup could therefore write/overwrite arbitrary files anywhere the Termux user has write access, including shell startup files. Fixed by: (1) deriving the extraction destination only from the app's own known `BACKUP_ITEMS` roots instead of manifest content, refusing unknown manifest keys; (2) validating every tar member's resolved path (and symlink/hardlink targets) stays inside the destination before extraction, and rejecting device/fifo entries; (3) using Python's built-in `filter="data"` extraction filter on 3.12+; (4) sanitizing `backup_name` before it's used to build the temp restore path. Reported privately by [Niranj R Mahaswar](https://github.com/NiranjMahaswar).
+
+### Fixed
+
+- **`delete` (GitHub storage) — `Failed to delete backup from GitHub: Expecting value: line 1 column 1 (char 0)`** — `GitHubStorage._api()` unconditionally called `json.loads()` on every API response, but GitHub's REST API returns `204 No Content` with an empty body for `DELETE /releases/{id}` and `DELETE /git/refs/tags/{tag}`, so the empty body failed JSON parsing and the delete was reported as failed (even when it actually succeeded on GitHub's side). `_api()` now returns `{}` for empty/204 responses instead of trying to parse them as JSON.
+
 ### Planned
 
 - Archive encryption using a user-provided password
@@ -30,7 +57,7 @@ Version numbers follow [Semantic Versioning](https://semver.org/).
 
 ### Fixed
 
-- **`restore` — stuck retrying and failing with `HTTP Error 404: Not Found` when the GitHub backend points to a private repo** — `GitHubStorage.download()` and the `manifest.json` lookup in `list_backups()` downloaded release assets via `asset["browser_download_url"]` using the standard `Accept: application/vnd.github.v3+json` header. That URL only resolves without further authentication for public repos; for private repos GitHub returns 404 even with a valid token, since the download must go through the `/repos/{repo}/releases/assets/{id}` API endpoint with `Accept: application/octet-stream`. Added `GitHubStorage._asset_headers()` and `_asset_url()` and switched both call sites to use them, so restoring from a private-repo backend now downloads correctly instead of exhausting all 8 retries.
+- **`restore` — stuck retrying and failing with `HTTP Error 404: Not Found` when the GitHub backend points to a private repo** — `GitHubStorage.download()` and the `manifest.json` lookup in `list_backups()` downloaded release assets via `asset["browser_download_url"]` using the standard `Accept: application/vnd.github.v3+json` header. That URL only resolves without further authentication for public repos; for private repos GitHub returns 404 even with a valid token, since the download must go through the `/repos/{repo}/releases/assets/{id}` API endpoint with `Accept: application/octet-stream`. Added `GitHubStorage._asset_headers()` and `_asset_url()` and switched both call sites to use them, so restoring from a private-repo backend now downloads correctly instead of exhausting all 8 retries. [Issues #13](https://github.com/djunekz/termux-sync/issues/13)
 
 ---
 

{termux_sync-1.2.3 → termux_sync-1.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: termux-sync
-Version: 1.2.3
+Version: 1.2.6
 Summary: Backup and restore your entire Termux environment across devices
 Project-URL: Homepage, https://github.com/djunekz/termux-sync
 Project-URL: Repository, https://github.com/djunekz/termux-sync

{termux_sync-1.2.3 → termux_sync-1.2.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "termux-sync"
-version = "1.2.3"
+version = "1.2.6"
 description = "Backup and restore your entire Termux environment across devices"
 readme = "README.md"
 license = { file = "LICENSE" }

{termux_sync-1.2.3 → termux_sync-1.2.6}/src/termux_sync/__init__.py

@@ -9,8 +9,12 @@ Supports Local, Google Drive, and GitHub (private repo) storage.
 """
 
 import os
+import re
 import sys
 import json
+import errno
+import difflib
+import traceback
 import time
 import shutil
 import hashlib
@@ -39,11 +43,24 @@ try:
     from rich.rule import Rule
     from rich.syntax import Syntax
     from rich.align import Align
+    from rich.markup import escape
+    from rich.padding import Padding
     RICH_AVAILABLE = True
 except ImportError:
-    RICH_AVAILABLE = False
+    if os.environ.get("_TERMUX_SYNC_BOOTSTRAP") != "1":
+        sys.stderr.write("\n  termux-sync: installing required package 'rich' ...\n\n")
+        _r = subprocess.run([sys.executable, "-m", "pip", "install", "--quiet", "rich"])
+        if _r.returncode == 0:
+            os.environ["_TERMUX_SYNC_BOOTSTRAP"] = "1"
+            os.execv(sys.executable, [sys.executable] + sys.argv)
+    sys.stderr.write(
+        "\n  ERROR: the Python package 'rich' is required but could not be installed.\n"
+        "  Install it manually, then run termux-sync again:\n\n"
+        "      pip install rich\n\n"
+    )
+    sys.exit(1)
 
-VERSION       = "1.2.3"
+VERSION       = "1.2.6"
 APP_NAME      = "termux-sync"
 CONFIG_DIR    = Path.home() / ".config" / APP_NAME
 CONFIG_FILE   = CONFIG_DIR / "config.json"
@@ -101,8 +118,16 @@ DEFAULT_CONFIG = {
 def load_config() -> dict:
     CONFIG_DIR.mkdir(parents=True, exist_ok=True)
     if CONFIG_FILE.exists():
-        with open(CONFIG_FILE) as f:
-            data = json.load(f)
+        try:
+            with open(CONFIG_FILE) as f:
+                data = json.load(f)
+        except json.JSONDecodeError as e:
+            raise UserError(
+                f"The config file is not valid JSON (line {e.lineno}, column {e.colno}).\n"
+                f"File: {CONFIG_FILE}",
+                hint="Fix the file by hand, or delete it and run [bold]termux-sync setup[/bold] again.",
+                title="Config file is corrupted",
+            ) from e
         for k, v in DEFAULT_CONFIG.items():
             data.setdefault(k, v)
         return data
@@ -117,6 +142,121 @@ def save_config(cfg: dict):
 
 console = Console()
 
+DEBUG      = bool(os.environ.get("TERMUX_SYNC_DEBUG"))
+ISSUES_URL = "https://github.com/djunekz/termux-sync/issues"
+
+
+# ───────────────────────── Error handling ─────────────────────────
+class UserError(Exception):
+    """An expected, fixable problem. Shown as a clean message — no traceback."""
+
+    def __init__(self, message: str, hint: str = "", title: str = "Cannot continue"):
+        super().__init__(message)
+        self.message = message
+        self.hint    = hint      # may contain rich markup (written by us, not user input)
+        self.title   = title
+
+
+def print_error(title: str, message: str, hint: str = "", where: str = ""):
+    """Render one tidy error panel. `message` is escaped; `hint` may use markup."""
+    body = [f"[bold red]{escape(title)}[/bold red]", "", escape(message)]
+    if where:
+        body += ["", f"[dim]at {escape(where)}[/dim]"]
+    if hint:
+        body += ["", "[bold yellow]How to fix[/bold yellow]", hint]
+    console.print()
+    console.print(Panel(
+        "\n".join(body),
+        title="[bold red] ERROR [/bold red]",
+        border_style="red",
+        padding=(1, 2),
+        expand=False,
+    ))
+    console.print()
+
+
+def _origin(exc: BaseException) -> str:
+    """Last stack frame that lives in this file, e.g. 'termux-sync.py:1217 in cmd_setup()'."""
+    found, tb = "", exc.__traceback__
+    while tb is not None:
+        if tb.tb_frame.f_code.co_filename == __file__:
+            found = f"{Path(__file__).name}:{tb.tb_lineno} in {tb.tb_frame.f_code.co_name}()"
+        tb = tb.tb_next
+    return found
+
+
+def _explain(exc: Exception) -> tuple:
+    """Translate an exception into (title, message, hint)."""
+    import urllib.error
+    import socket
+
+    if isinstance(exc, UserError):
+        return exc.title, exc.message, exc.hint
+    if isinstance(exc, EOFError):
+        return (
+            "Input was closed",
+            "termux-sync asked a question, but no answer could be read "
+            "(the input stream ended, or you pressed Ctrl+D).",
+            "Run the command directly in the Termux terminal — not through a pipe, "
+            "script, or widget — and answer the prompts.",
+        )
+    if isinstance(exc, FileNotFoundError):
+        return ("File or folder not found", str(exc.filename or exc),
+                "Check that the path exists and is spelled correctly.")
+    if isinstance(exc, PermissionError):
+        return ("Permission denied", str(exc.filename or exc),
+                "Pick a path inside your home directory, or run "
+                "[bold]termux-setup-storage[/bold] to grant access to shared storage.")
+    if isinstance(exc, OSError) and exc.errno == errno.ENOSPC:
+        return ("Device is out of space", "There is not enough free storage to finish this.",
+                "Free some space with [bold]termux-sync clear-cache[/bold] "
+                "or check usage with [bold]termux-sync check[/bold].")
+    if isinstance(exc, urllib.error.HTTPError):
+        hint = "Check your token and repository name with [bold]termux-sync setup[/bold]."
+        if exc.code in (401, 403):
+            hint = "Your token is invalid, expired, or lacks the [bold]repo[/bold] scope. Create a new one and run [bold]termux-sync setup[/bold]."
+        elif exc.code == 404:
+            hint = "The repository or release was not found. Check the repo name in [bold]termux-sync setup[/bold]."
+        return f"GitHub returned HTTP {exc.code}", str(exc.reason), hint
+    if isinstance(exc, (urllib.error.URLError, socket.timeout, TimeoutError, ConnectionError)):
+        return ("Network problem", str(getattr(exc, "reason", None) or exc),
+                "Check your internet connection and try again.")
+    if isinstance(exc, subprocess.CalledProcessError):
+        cmd = exc.cmd if isinstance(exc.cmd, str) else " ".join(map(str, exc.cmd))
+        return ("A command failed", f"{cmd}\nexit code {exc.returncode}",
+                "Run that command by hand to see its full output.")
+    if isinstance(exc, (RuntimeError, ValueError)):
+        return "Operation failed", str(exc), "See the message above. Details are saved in the log."
+    return (
+        "Unexpected error",
+        f"{type(exc).__name__}: {exc}",
+        f"Run again with [bold]--debug[/bold] for the full traceback.\n"
+        f"If it keeps happening, please report it:  [cyan]{ISSUES_URL}[/cyan]",
+    )
+
+
+def handle_crash(exc: Exception):
+    """Log the full traceback to the log file; show a clean panel on screen."""
+    try:
+        log("ERROR", f"{type(exc).__name__}: {exc}")
+        for line in "".join(traceback.format_exception(type(exc), exc, exc.__traceback__)).splitlines():
+            log("TRACE", line)
+    except Exception:
+        pass
+
+    console.print()                        # leave the half-finished prompt line
+    title, message, hint = _explain(exc)
+    expected = isinstance(exc, UserError)
+    print_error(title, message, hint, where="" if expected and not DEBUG else _origin(exc))
+
+    if DEBUG:
+        console.print("[bold dim]Full traceback (--debug)[/bold dim]")
+        console.print_exception(show_locals=False, max_frames=10, suppress=[sys.modules["rich"]])
+        console.print()
+    else:
+        shown = str(LOG_FILE).replace(str(Path.home()), "~")
+        console.print(f"  [dim]Log: {shown}[/dim]\n")
+
 
 def print_banner():
     console.print(
@@ -277,18 +417,62 @@ def create_archive(
     return out
 
 
+def _safe_extract_member(member: tarfile.TarInfo, dest_path: Path):
+    dest_root = dest_path.resolve()
+
+    member_name = member.name
+    if member_name.startswith("/") or member_name.startswith("\\"):
+        raise ValueError(f"Unsafe absolute path in archive: {member_name!r}")
+    if any(part == ".." for part in Path(member_name).parts):
+        raise ValueError(f"Path traversal attempt in archive: {member_name!r}")
+
+    target = (dest_path / member_name).resolve()
+    try:
+        target.relative_to(dest_root)
+    except ValueError:
+        raise ValueError(f"Archive member escapes destination: {member_name!r} -> {target}")
+
+    if member.issym() or member.islnk():
+        link_target = member.linkname
+        if os.path.isabs(link_target):
+            raise ValueError(f"Unsafe absolute link target in archive: {member_name!r} -> {link_target!r}")
+        resolved_link = (target.parent / link_target).resolve()
+        try:
+            resolved_link.relative_to(dest_root)
+        except ValueError:
+            raise ValueError(f"Archive link escapes destination: {member_name!r} -> {link_target!r}")
+
+    if member.ischr() or member.isblk() or member.isfifo():
+        raise ValueError(f"Refusing device/fifo entry in archive: {member_name!r}")
+
+
 def extract_archive(archive_path: Path, dest_path: Path, label: str, progress: Progress):
     task = progress.add_task(f"[cyan]{label}", total=None)
     dest_path.mkdir(parents=True, exist_ok=True)
+
+    has_data_filter = hasattr(tarfile, "data_filter")
+
     with tarfile.open(archive_path, "r:*") as tf:
         for member in tf.getmembers():
             try:
-                tf.extract(member, dest_path, set_attrs=True)
+                _safe_extract_member(member, dest_path)
+            except ValueError as e:
+                log("WARNING", f"Skipped unsafe archive member during restore: {e}")
+                continue
+
+            try:
+                if has_data_filter:
+                    tf.extract(member, dest_path, set_attrs=True, filter="data")
+                else:
+                    tf.extract(member, dest_path, set_attrs=True)
             except Exception:
                 try:
                     member.uid = os.getuid()
                     member.gid = os.getgid()
-                    tf.extract(member, dest_path, set_attrs=False)
+                    if has_data_filter:
+                        tf.extract(member, dest_path, set_attrs=False, filter="data")
+                    else:
+                        tf.extract(member, dest_path, set_attrs=False)
                 except Exception:
                     pass
     progress.update(task, total=1, completed=1, description=f"[green]{label} ✓")
@@ -374,8 +558,12 @@ class GDriveStorage:
 
     def _check_rclone(self):
         if shutil.which("rclone") is None:
-            console.print("[red]rclone not found. Install: pkg install rclone[/red]")
-            sys.exit(1)
+            raise UserError(
+                "Google Drive storage needs rclone, but it is not installed.",
+                hint="Install it with [bold]pkg install rclone[/bold], then configure a remote "
+                     "named [bold]termux-sync-gdrive[/bold] using [bold]rclone config[/bold].",
+                title="rclone not found",
+            )
 
     def _remote_path(self, name: str = "") -> str:
         base = f"{self.REMOTE}:"
@@ -460,8 +648,12 @@ class GitHubStorage:
         self.repo   = cfg.get("github_repo", "")
         self.branch = cfg.get("github_branch", "main")
         if not self.token or not self.repo:
-            console.print("[red]GitHub token and repo are required. Run: termux-sync setup[/red]")
-            sys.exit(1)
+            raise UserError(
+                "GitHub storage is selected, but the token or repository is not set.",
+                hint="Run [bold]termux-sync setup[/bold] and enter your Personal Access Token "
+                     "and repo (owner/repo).",
+                title="GitHub is not configured",
+            )
 
     def _headers(self) -> dict:
         return {
@@ -485,7 +677,12 @@ class GitHubStorage:
         req  = urllib.request.Request(url, data=data, headers=self._headers(), method=method)
         try:
             with urllib.request.urlopen(req) as resp:
-                return json.loads(resp.read())
+                if resp.status == 204:
+                    return {}
+                body = resp.read()
+                if not body:
+                    return {}
+                return json.loads(body)
         except urllib.error.HTTPError as e:
             body = e.read().decode()
             raise RuntimeError(f"GitHub API error {e.code}: {body}") from e
@@ -828,7 +1025,7 @@ def cmd_backup(cfg: dict, label: str = ""):
                 }
                 log("INFO", f"Archived {src} → {actual_out.name} ({human_size(actual_out.stat().st_size)})")
             except Exception as e:
-                console.print(f"  [red]✗ Failed to archive {src}: {e}[/red]")
+                console.print(f"  [red]✗ Failed to archive {src}: {escape(str(e))}[/red]")
                 log("ERROR", f"Archive failed for {src}: {e}")
 
     console.print()
@@ -855,7 +1052,7 @@ def cmd_backup(cfg: dict, label: str = ""):
             _cleanup_tmp()
             raise
         except Exception as e:
-            console.print(f"  [red]✗ Upload failed: {e}[/red]")
+            console.print(f"  [red]✗ Upload failed: {escape(str(e))}[/red]")
             log("ERROR", f"Upload failed: {e}")
             _cleanup_tmp()
             return
@@ -930,6 +1127,12 @@ def cmd_restore(cfg: dict, backup_name: str = ""):
         except ValueError:
             backup_name = choice
 
+    safe_backup_name = os.path.basename(str(backup_name).replace("\\", "/")).strip()
+    if not safe_backup_name or safe_backup_name in (".", "..") or "/" in safe_backup_name:
+        console.print(f"  [red]✗ Invalid backup name: {backup_name!r}[/red]")
+        return
+    backup_name = safe_backup_name
+
     tmp_dir = Path(os.environ.get("TMPDIR", "/data/data/com.termux/files/usr/tmp")) / f"restore_{backup_name}"
     tmp_dir.mkdir(parents=True, exist_ok=True)
 
@@ -945,7 +1148,7 @@ def cmd_restore(cfg: dict, backup_name: str = ""):
         try:
             storage.download(backup_name, tmp_dir, progress)
         except Exception as e:
-            console.print(f"  [red]✗ Download failed: {e}[/red]")
+            console.print(f"  [red]✗ Download failed: {escape(str(e))}[/red]")
             log("ERROR", f"Download failed: {e}")
             shutil.rmtree(tmp_dir, ignore_errors=True)
             return
@@ -1003,14 +1206,31 @@ def cmd_restore(cfg: dict, backup_name: str = ""):
         TimeElapsedColumn(),
         console=console,
     ) as progress:
+        # Build the set of destinations this app is actually willing to restore into.
+        # Manifest-supplied "source" values are attacker-controlled backup content
+        # and must never be trusted as an extraction root — only used to double
+        # check they agree with the known-safe root for that item key.
+        allowed_roots = {}
+        for item_key, _label, item_root in BACKUP_ITEMS:
+            if item_root is not None:
+                allowed_roots[item_key] = Path(item_root).resolve().parent
+
         for key, info in manifest.get("files", {}).items():
             archive = tmp_dir / info["archive"]
-            src_dir = Path(info.get("source", str(TERMUX_FILES))).parent
+
+            src_dir = allowed_roots.get(key)
+            if src_dir is None:
+                # Unknown key not part of this app's known backup items — refuse
+                # to derive a destination from untrusted manifest content.
+                console.print(f"  [red]✗ Refusing unknown/untrusted restore target for {key!r}[/red]")
+                log("WARNING", f"Refused restore for unknown manifest key: {key!r}")
+                continue
+
             try:
                 extract_archive(archive, src_dir, info["archive"], progress)
                 log("INFO", f"Extracted {info['archive']} → {src_dir}")
             except Exception as e:
-                console.print(f"  [red]✗ Extract failed: {e}[/red]")
+                console.print(f"  [red]✗ Extract failed: {escape(str(e))}[/red]")
                 log("ERROR", f"Extract failed for {info['archive']}: {e}")
 
     pkgs = manifest.get("packages", [])
@@ -1126,7 +1346,7 @@ def cmd_delete(cfg: dict, backup_name: str = ""):
         console.print(f"\n  [bold green]✓ Backup '{backup_name}' deleted successfully.[/bold green]\n")
         log("INFO", f"Deleted backup: {backup_name}")
     except Exception as e:
-        console.print(f"\n  [red]✗ Failed to delete backup: {e}[/red]\n")
+        console.print(f"\n  [red]✗ Failed to delete backup: {escape(str(e))}[/red]\n")
         log("ERROR", f"Delete failed for {backup_name}: {e}")
 
 
@@ -1210,9 +1430,12 @@ def cmd_setup():
         "  Compression (gz=fast, bz2=balanced, xz=best)",
         choices=["gz", "bz2", "xz"], default=cfg.get("compression", "gz")
     )
-    cfg["max_backups"] = int(Prompt.ask(
-        "  Max backups to keep", default=str(cfg.get("max_backups", 5))
-    ))
+    while True:
+        raw = Prompt.ask("  Max backups to keep", default=str(cfg.get("max_backups", 5))).strip()
+        if raw.isdigit() and int(raw) >= 1:
+            cfg["max_backups"] = int(raw)
+            break
+        console.print("  [red]✗ Enter a whole number of 1 or more.[/red]")
 
     console.print()
     current_patterns = cfg.get("exclude_patterns", [])
@@ -1407,14 +1630,25 @@ def cmd_logs(lines: int = 40):
     if not LOG_FILE.exists():
         console.print("  [dim]No log file yet.[/dim]")
         return
-    log_lines = LOG_FILE.read_text().splitlines()[-lines:]
+    all_lines = LOG_FILE.read_text().splitlines()
+    if not DEBUG:
+        all_lines = [ln for ln in all_lines if "[TRACE]" not in ln]
+    log_lines = all_lines[-lines:]
+    if not log_lines:
+        console.print("  [dim]No log entries.[/dim]")
+        return
+    if not DEBUG:
+        console.print("  [dim]Tip: add --debug to also show saved tracebacks.[/dim]\n")
     for line in log_lines:
+        safe = escape(line)
         if "[ERROR]" in line:
-            console.print(f"  [red]{line}[/red]")
+            console.print(f"  [red]{safe}[/red]")
         elif "[WARN]" in line:
-            console.print(f"  [yellow]{line}[/yellow]")
+            console.print(f"  [yellow]{safe}[/yellow]")
+        elif "[TRACE]" in line:
+            console.print(f"  [dim red]{safe}[/dim red]")
         else:
-            console.print(f"  [dim]{line}[/dim]")
+            console.print(f"  [dim]{safe}[/dim]")
 
 
 def cmd_clear_logs():
@@ -1644,7 +1878,7 @@ def cmd_clear_cache():
                             else:
                                 child.unlink(missing_ok=True)
                         except Exception as e:
-                            log("WARN", f"Could not remove {child}: {e}")
+                            log("WARN", f"Could not remove {child}: {escape(str(e))}")
                 prog.update(task, total=1, completed=1,
                             description=f"[green]{label} cleared ({human_size(size)}) ✓")
                 cleared += size
@@ -1692,15 +1926,17 @@ def cmd_import_config(input_path: str = ""):
 
     src = Path(input_path).expanduser()
     if not src.exists():
-        console.print(f"  [red]File not found: {src}[/red]\n")
-        return
+        raise UserError(str(src), hint="Check the path and try again.", title="File not found")
 
     try:
         with open(src) as f:
             new_cfg = json.load(f)
     except json.JSONDecodeError as e:
-        console.print(f"  [red]Invalid JSON file: {e}[/red]\n")
-        return
+        raise UserError(
+            f"{src}\nLine {e.lineno}, column {e.colno}: {e.msg}",
+            hint="Make sure the file is a valid JSON export from [bold]termux-sync export-config[/bold].",
+            title="Not a valid JSON file",
+        ) from e
 
     existing = load_config()
 
@@ -1717,117 +1953,127 @@ def cmd_import_config(input_path: str = ""):
     log("INFO", f"Config imported from {src}")
 
 
-def ensure_dependencies():
-    try:
-        import rich
-    except ImportError:
-        print("Installing required Python packages (rich)…")
-        subprocess.run([sys.executable, "-m", "pip", "install", "--quiet", "rich"], check=True)
-        print("Done. Please re-run termux-sync.")
-        sys.exit(0)
-
-
-def main():
-    ensure_dependencies()
-
-    parser = argparse.ArgumentParser(
-        prog="termux-sync",
-        description="Termux Backup & Restore — sync your environment across devices",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""\
-Commands:
-  backup         Create a new backup
-  restore        Restore from a backup
-  list           List all available backups
-  delete         Delete a specific backup
-  setup          Interactive configuration wizard
-  schedule       Configure auto-backup schedule
-  daemon         Run background scheduler (called by Termux:Boot)
-  status         Show current config and environment
-  logs           Show recent log entries
-  clear-logs     Clear / reset the log file
-  check          Show disk usage (check ~, $PREFIX, or a custom path)
-  clear-cache    Remove temporary and cached files
-  export-config  Export config to a file (tokens redacted)
-  import-config  Import config from a file
-
-Examples:
-  termux-sync setup
-  termux-sync backup --label "before-new-phone"
-  termux-sync list
-  termux-sync restore
-  termux-sync delete
-  termux-sync delete --name termux_backup_20240501_120000
-  termux-sync schedule
-  termux-sync status
-  termux-sync logs --lines 100
-  termux-sync clear-logs
-  termux-sync check
-  termux-sync check ~
-  termux-sync check $PREFIX
-  termux-sync clear-cache
-  termux-sync export-config
-  termux-sync import-config ~/termux-sync-config-export.json
-        """,
-    )
-    parser.add_argument("command", nargs="?", default="help",
-                        choices=["backup", "restore", "list", "delete", "setup", "schedule",
-                                 "daemon", "status", "logs", "clear-logs", "check",
-                                 "clear-cache", "export-config", "import-config", "help"])
-    parser.add_argument("target",  nargs="?", default="",  help="Optional path for check / import-config")
-    parser.add_argument("--label",   "-l", default="",    help="Label for this backup")
-    parser.add_argument("--name",    "-n", default="",    help="Backup name to restore / delete")
-    parser.add_argument("--lines",         default=40, type=int, help="Lines to show in logs")
-    parser.add_argument("--version", "-v", action="store_true",  help="Print version and exit")
-
-    args = parser.parse_args()
+# ───────────────────────── Command line ─────────────────────────
+COMMAND_GROUPS = [
+    ("Backup & Restore", [
+        ("backup",        "Create a new backup"),
+        ("restore",       "Restore from a backup"),
+        ("list",          "List all available backups"),
+        ("delete",        "Delete a specific backup"),
+    ]),
+    ("Configuration", [
+        ("setup",         "Interactive configuration wizard"),
+        ("schedule",      "Configure auto-backup schedule"),
+        ("daemon",        "Run background scheduler (used by Termux:Boot)"),
+        ("export-config", "Export config to a file (tokens redacted)"),
+        ("import-config", "Import config from a file"),
+    ]),
+    ("Maintenance", [
+        ("status",        "Show current config and environment"),
+        ("logs",          "Show recent log entries"),
+        ("clear-logs",    "Clear / reset the log file"),
+        ("check",         "Show disk usage (~, $PREFIX, or a custom path)"),
+        ("clear-cache",   "Remove temporary and cached files"),
+        ("help",          "Show this help"),
+    ]),
+]
+COMMANDS = [name for _, items in COMMAND_GROUPS for name, _ in items]
+
+OPTIONS = [
+    ("-l, --label LABEL", "Label for this backup"),
+    ("-n, --name NAME",   "Backup name to restore / delete"),
+    ("--lines N",         "Lines to show in logs (default 40)"),
+    ("--debug",           "Show the full traceback if something fails"),
+    ("-v, --version",     "Print version and exit"),
+    ("-h, --help",        "Show this help"),
+]
 
-    if args.version:
-        print(f"termux-sync v{VERSION}")
-        return
+EXAMPLES = [
+    ("termux-sync setup",                              "first-time configuration"),
+    ("termux-sync backup --label before-new-phone",    "create a labelled backup"),
+    ("termux-sync list",                               "see all backups"),
+    ("termux-sync restore",                            "pick a backup to restore"),
+    ("termux-sync delete --name <backup-name>",        "delete a specific backup"),
+    ("termux-sync logs --lines 100",                   "show the last 100 log lines"),
+    ("termux-sync check ~",                            "disk usage of your home"),
+    ("termux-sync import-config <file>",               "load a config file"),
+]
 
-    if args.command == "help" or args.command is None:
-        print_banner()
-        parser.print_help()
-        return
+# Commands people commonly try that live elsewhere.
+COMMAND_HINTS = {
+    "update":  "termux-sync has no built-in update command. Use [bold]tsctl updater[/bold] to update.",
+    "upgrade": "To update, use [bold]tsctl updater[/bold].",
+    "install": "To install or reinstall, use the install script, or [bold]tsctl[/bold].",
+    "remove":  "To delete a backup use [bold]termux-sync delete[/bold]. To uninstall the tool use [bold]tsctl uninstall[/bold].",
+    "config":  "Use [bold]termux-sync setup[/bold] to change settings, or [bold]termux-sync status[/bold] to view them.",
+    "sync":    "Use [bold]termux-sync backup[/bold] to upload, or [bold]termux-sync restore[/bold] to download.",
+}
 
-    cfg = load_config()
 
-    try:
-        if args.command == "setup":
-            cmd_setup()
-        elif args.command == "backup":
-            cmd_backup(cfg, label=args.label)
-        elif args.command == "restore":
-            cmd_restore(cfg, backup_name=args.name)
-        elif args.command == "list":
-            cmd_list(cfg)
-        elif args.command == "delete":
-            cmd_delete(cfg, backup_name=args.name)
-        elif args.command == "schedule":
-            cmd_schedule()
-        elif args.command == "daemon":
-            cmd_daemon(cfg)
-        elif args.command == "status":
-            cmd_status(cfg)
-        elif args.command == "logs":
-            cmd_logs(args.lines)
-        elif args.command == "clear-logs":
-            cmd_clear_logs()
-        elif args.command == "check":
-            cmd_check(args.target or "")
-        elif args.command == "clear-cache":
-            cmd_clear_cache()
-        elif args.command == "export-config":
-            cmd_export_config(args.target or "")
-        elif args.command == "import-config":
-            cmd_import_config(args.target or "")
-    except KeyboardInterrupt:
-        _abort()
+def print_help():
+    print_banner()
+    console.print(f"  [bold]Usage:[/bold]  termux-sync [cyan]<command>[/cyan] [dim]{escape('[target] [options]')}[/dim]")
+    console.print()
+
+    for group, items in COMMAND_GROUPS:
+        table = Table(box=None, show_header=False, padding=(0, 2), pad_edge=False)
+        table.add_column(style="bold cyan", no_wrap=True)
+        table.add_column()
+        for name, desc in items:
+            table.add_row(name, escape(desc))
+        console.print(f"  [bold yellow]{group}[/bold yellow]")
+        console.print(Padding(table, (0, 0, 1, 2)))
+
+    table = Table(box=None, show_header=False, padding=(0, 2), pad_edge=False)
+    table.add_column(style="green", no_wrap=True)
+    table.add_column()
+    for flag, desc in OPTIONS:
+        table.add_row(escape(flag), escape(desc))
+    console.print("  [bold yellow]Options[/bold yellow]")
+    console.print(Padding(table, (0, 0, 1, 2)))
+
+    console.print("  [bold yellow]Examples[/bold yellow]")
+    for cmd, _ in EXAMPLES:
+        console.print(f"    [dim]$[/dim] [white]{escape(cmd)}[/white]", soft_wrap=True)
+    console.print()
+
+
+class FriendlyParser(argparse.ArgumentParser):
+    """argparse, but errors are shown as a tidy panel instead of a usage dump."""
+
+    def error(self, message):
+        m = re.search(r"invalid choice: '([^']*)'", message)
+        if m:
+            bad = m.group(1)
+            hint_lines = []
+            if bad in COMMAND_HINTS:
+                hint_lines.append(COMMAND_HINTS[bad])
+            close = [] if bad in COMMAND_HINTS else difflib.get_close_matches(bad, COMMANDS, n=3, cutoff=0.6)
+            if close:
+                hint_lines.append("Did you mean:  " + "   ".join(f"[bold cyan]{c}[/bold cyan]" for c in close))
+            hint_lines.append("Run [bold]termux-sync help[/bold] to see all commands.")
+            print_error("Unknown command", f"'{bad}' is not a termux-sync command.", "\n\n".join(hint_lines))
+        else:
+            nice = message.replace("argument --lines/", "--lines").replace("argument ", "")
+            print_error("Invalid usage", nice,
+                        "Run [bold]termux-sync help[/bold] to see the correct usage.")
+        sys.exit(2)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = FriendlyParser(prog="termux-sync", add_help=False)
+    parser.add_argument("command", nargs="?", default="help", choices=COMMANDS, metavar="command")
+    parser.add_argument("target", nargs="?", default="")
+    parser.add_argument("--label", "-l", default="")
+    parser.add_argument("--name",  "-n", default="")
+    parser.add_argument("--lines", default=40, type=int)
+    parser.add_argument("--debug", action="store_true")
+    parser.add_argument("--version", "-v", action="store_true")
+    parser.add_argument("--help", "-h", action="store_true")
+    return parser
 
 
 def _abort():
-    console.print()
     console.print()
     console.print(
         Panel(
@@ -1837,9 +2083,49 @@ def _abort():
             "  Run the command again whenever you're ready.",
             border_style="yellow",
             padding=(1, 2),
+            expand=False,
         )
     )
-    sys.exit(0)
+    sys.exit(130)
+
+
+def main(argv=None):
+    global DEBUG
+    args = build_parser().parse_args(argv)
+    DEBUG = DEBUG or args.debug
+
+    if args.version:
+        print(f"termux-sync v{VERSION}")
+        return
+
+    if args.help or args.command in (None, "help"):
+        print_help()
+        return
+
+    try:
+        cfg = load_config()
+        handlers = {
+            "setup":         lambda: cmd_setup(),
+            "backup":        lambda: cmd_backup(cfg, label=args.label),
+            "restore":       lambda: cmd_restore(cfg, backup_name=args.name),
+            "list":          lambda: cmd_list(cfg),
+            "delete":        lambda: cmd_delete(cfg, backup_name=args.name),
+            "schedule":      lambda: cmd_schedule(),
+            "daemon":        lambda: cmd_daemon(cfg),
+            "status":        lambda: cmd_status(cfg),
+            "logs":          lambda: cmd_logs(args.lines),
+            "clear-logs":    lambda: cmd_clear_logs(),
+            "check":         lambda: cmd_check(args.target or ""),
+            "clear-cache":   lambda: cmd_clear_cache(),
+            "export-config": lambda: cmd_export_config(args.target or ""),
+            "import-config": lambda: cmd_import_config(args.target or ""),
+        }
+        handlers[args.command]()
+    except KeyboardInterrupt:
+        _abort()
+    except Exception as exc:
+        handle_crash(exc)
+        sys.exit(1)
 
 
 if __name__ == "__main__":