termux-sync 1.2.4__tar.gz → 1.2.8__tar.gz

{termux_sync-1.2.4 → termux_sync-1.2.8}/CHANGELOG.md

@@ -11,6 +11,34 @@ Version numbers follow [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.2.8] - 2026-10-15
+
+## Fixed
+- `status` tables fit narrow phone screens: long paths are shortened (`$PREFIX/bin/tar`, `~/.config/...`), the ✓/✗ sits in its own column, and `rclone` is shown as "not needed" unless Google Drive is the selected storage.
+- **GitHub backups no longer need room for the whole archive.** The archive is streamed and uploaded in 200 MB parts, each deleted right after it is sent (before, the full archive *plus* a split copy were written to disk, which caused "No space left on device"). The backup format is unchanged, so `restore` works as before. Needs about 250 MB free.
+- Upload retry logic: permanent HTTP errors (bad token, etc.) now stop immediately instead of retrying for minutes; "already uploaded" (422) is handled again.
+- Running out of disk space during `backup` stops with a clear message instead of continuing with a broken backup.
+- `backup` to GitHub now checks the repository (token, name, not empty) *before* the long archive step, instead of failing after the archive is built.
+- GitHub API errors are shown as short readable messages (e.g. "repository is empty") instead of raw JSON.
+- If an upload fails, the finished archives are kept in the temp folder instead of being deleted.
+
+---
+
+## [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
@@ -42,7 +70,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.4 → termux_sync-1.2.8}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: termux-sync
-Version: 1.2.4
+Version: 1.2.8
 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.4 → termux_sync-1.2.8}/pyproject.toml

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

{termux_sync-1.2.4 → termux_sync-1.2.8}/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.4"
+VERSION       = "1.2.8"
 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,123 @@ 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, StreamAbort):          # upload failure while streaming
+        exc = exc.original
+    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(getattr(exc, "original", 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(
@@ -208,7 +350,10 @@ def create_archive(
     excludes: list[str],
     label: str,
     progress: Progress,
+    sink=None,
 ) -> Path:
+    """Create a tar archive. With `sink` (a file-like object) the archive is streamed
+    into it and nothing is written to `archive_path`."""
     valid_compressions = {"gz", "bz2", "xz"}
     if compression not in valid_compressions:
         compression = "gz"
@@ -226,6 +371,8 @@ def create_archive(
         out = archive_path.parent / (stem + ext)
 
     task = progress.add_task(f"[cyan]{label}", total=None)
+    if sink is not None and hasattr(sink, "attach"):
+        sink.attach(progress, task, label)
 
     def _filter(tarinfo):
         for pat in excludes:
@@ -265,7 +412,11 @@ def create_archive(
     try:
         if source_path.is_dir():
             _unlock(source_path)
-        with tarfile.open(out, mode) as tf:
+        if sink is not None:
+            opened = tarfile.open(fileobj=sink, mode=f"w|{compression}")
+        else:
+            opened = tarfile.open(out, mode)
+        with opened as tf:
             if source_path.is_dir():
                 tf.add(source_path, arcname=source_path.name, filter=_filter)
             else:
@@ -418,8 +569,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}:"
@@ -504,8 +659,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 {
@@ -536,8 +695,90 @@ class GitHubStorage:
                     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
+            raise self._http_error(e.code, e.read().decode(errors="replace")) from e
+
+    def _http_error(self, code: int, raw: str) -> Exception:
+        """Turn a GitHub API error response into a short, human-readable exception."""
+        try:
+            data   = json.loads(raw)
+            msg    = str(data.get("message", "")).strip()
+            extras = "; ".join(
+                str(x.get("message")) for x in data.get("errors", [])
+                if isinstance(x, dict) and x.get("message")
+            )
+        except Exception:
+            msg, extras = raw.strip()[:300], ""
+        blob = f"{msg} {extras}".lower()
+
+        if code in (409, 422) and "empty" in blob:
+            return UserError(
+                f"The repository '{self.repo}' has no commits yet, and GitHub cannot "
+                "create a release in an empty repository.",
+                hint="Open the repository on GitHub, click [bold]Add a README[/bold] (or create "
+                     "any file) and commit it. Then run the command again.",
+                title="GitHub repository is empty",
+            )
+        if code == 401:
+            return UserError(
+                "GitHub rejected the token (bad credentials).",
+                hint="Create a new token with the [bold]repo[/bold] scope at "
+                     "[cyan]https://github.com/settings/tokens[/cyan], then run "
+                     "[bold]termux-sync setup[/bold].",
+                title="Invalid GitHub token",
+            )
+        if code == 403 and "rate limit" in blob:
+            return UserError(
+                "GitHub is limiting requests from this token for now.",
+                hint="Wait a few minutes and try again.",
+                title="GitHub rate limit reached",
+            )
+        if code == 403:
+            return UserError(
+                msg or "The token is not allowed to do this.",
+                hint="Make sure the token has the [bold]repo[/bold] scope and can write to this repository.",
+                title="GitHub denied access",
+            )
+        if code == 404:
+            return UserError(
+                f"Repository '{self.repo}' was not found, or the token cannot see it.",
+                hint="Check the spelling (owner/repo) in [bold]termux-sync setup[/bold]. "
+                     "For a private repository the token needs the [bold]repo[/bold] scope.",
+                title="GitHub repository not found",
+            )
+        detail = ": ".join(x for x in (msg, extras) if x) or "no details"
+        return RuntimeError(f"GitHub API error {code}: {detail}")
+
+    def preflight(self):
+        """Fail fast — before a long archive step — if the repo cannot hold a release."""
+        self._api("GET", f"/repos/{self.repo}")                     # token + repo name
+        self._api("GET", f"/repos/{self.repo}/commits?per_page=1")  # 409 if empty
+
+    # ── streaming backup: parts are uploaded and deleted one by one ──
+    def begin_stream(self, backup_name: str, work_dir: Path):
+        work_dir.mkdir(parents=True, exist_ok=True)
+        need = int(self.CHUNK_SIZE * 1.2)
+        free = shutil.disk_usage(work_dir).free
+        if free < need:
+            raise UserError(
+                f"Only {human_size(free)} is free, but about {human_size(need)} is needed "
+                "to hold one upload part.",
+                hint="Free some space with [bold]termux-sync clear-cache[/bold], or remove "
+                     "files you no longer need, then try again.",
+                title="Not enough free space",
+            )
+        release = self._get_release_by_tag(backup_name) or self._create_release(backup_name)
+        self._stream = {"release_id": release["id"], "work_dir": work_dir}
+
+    def stream_sink(self, base_name: str, progress: Progress):
+        return _PartWriter(self, self._stream["release_id"], base_name,
+                           self._stream["work_dir"], progress)
+
+    def abort_stream(self, backup_name: str):
+        """Best effort: remove a half-finished release so it never counts as a backup."""
+        try:
+            self.delete_backup(backup_name)
+        except Exception:
+            pass
 
     def _push_file(self, local_path: Path, remote_path: str, message: str):
         import base64
@@ -626,19 +867,28 @@ class GitHubStorage:
                     result = json.loads(resp.read())
                 progress.update(progress_task, completed=file_size)
                 return result
+            except urllib.error.HTTPError as e:
+                # (HTTPError is a URLError subclass, so it must be handled first)
+                body = e.read().decode(errors="replace")
+                if e.code == 422:
+                    progress.update(progress_task, completed=file_size,
+                                    description=f"[yellow]{local_path.name} already uploaded, skipping")
+                    return {}
+                if e.code >= 500 or e.code == 429:      # temporary: retry
+                    last_err = e
+                    progress.update(progress_task,
+                        description=f"[yellow]Retry {attempt+1}/{self.MAX_RETRIES} ({local_path.name})...")
+                    _time.sleep(15 * (attempt + 1))
+                    continue
+                raise self._http_error(e.code, body) from e   # permanent: stop now
             except (urllib.error.URLError, OSError, ConnectionError) as e:
+                if getattr(e, "errno", None) == errno.ENOSPC:
+                    raise
                 last_err = e
                 wait = 15 * (attempt + 1)
                 progress.update(progress_task,
                     description=f"[yellow]Retry {attempt+1}/{self.MAX_RETRIES} ({local_path.name})...")
                 _time.sleep(wait)
-            except urllib.error.HTTPError as e:
-                body = e.read().decode()
-                if e.code == 422:
-                    progress.update(progress_task, completed=file_size,
-                                    description=f"[yellow]{local_path.name} already uploaded, skipping")
-                    return {}
-                raise RuntimeError(f"Asset upload failed {e.code}: {body}") from e
 
         raise RuntimeError(
             f"Failed to upload {local_path.name} after {self.MAX_RETRIES} attempts: {last_err}"
@@ -792,6 +1042,103 @@ class GitHubStorage:
             raise RuntimeError(f"Failed to delete backup from GitHub: {e}") from e
 
 
+class StreamAbort(Exception):
+    """Raised when an upload fails while the archive is being streamed."""
+    def __init__(self, original: Exception):
+        super().__init__(str(original))
+        self.original = original
+
+
+class _PartWriter:
+    """File-like sink for tarfile. Cuts the stream into CHUNK_SIZE parts and uploads
+    each part as soon as it is full, then deletes it — so the device never needs room
+    for the whole archive. Part names match what `restore` already reassembles."""
+
+    def __init__(self, storage, release_id: int, base_name: str, work_dir: Path, progress: Progress):
+        self.storage, self.release_id, self.base = storage, release_id, base_name
+        self.work_dir, self.progress = work_dir, progress
+        self.limit = storage.CHUNK_SIZE
+        self.idx = 0                       # parts uploaded so far
+        self.total = 0                     # bytes of the whole archive
+        self.sha = hashlib.sha256()        # checksum of the whole archive
+        self._fh = None
+        self._path = None
+        self._size = 0
+        self._task = None
+        self._label = base_name
+        self._next_note = 0
+
+    def attach(self, progress, task, label):
+        self.progress, self._task, self._label = progress, task, label
+
+    def _note(self):
+        if self._task is not None:
+            self.progress.update(
+                self._task,
+                description=f"[cyan]{self._label}  [dim]{human_size(self.total)} sent[/dim]",
+            )
+
+    def writable(self):
+        return True
+
+    def flush(self):
+        pass
+
+    def write(self, data) -> int:
+        view, pos, n = memoryview(data), 0, len(data)
+        while pos < n:
+            if self._fh is not None and self._size >= self.limit:
+                self._flush(final=False)
+            if self._fh is None:
+                self._path = self.work_dir / f"{self.base}.part{self.idx:04d}"
+                self._fh, self._size = open(self._path, "wb"), 0
+            piece = view[pos: pos + (self.limit - self._size)]
+            self._fh.write(piece)
+            self._size += len(piece)
+            self.total += len(piece)
+            self.sha.update(piece)
+            pos += len(piece)
+        if self.total >= self._next_note:
+            self._next_note = self.total + (8 << 20)
+            self._note()
+        return n
+
+    def _flush(self, final: bool):
+        self._fh.close()
+        self._fh = None
+        path = self._path
+        if final and self.idx == 0:        # small archive: one plain file, no ".part"
+            plain = self.work_dir / self.base
+            path.rename(plain)
+            path = plain
+        task = self.progress.add_task(f"[cyan]{path.name}…", total=max(path.stat().st_size, 1))
+        try:
+            self.storage._upload_one_asset(self.release_id, path, task, self.progress)
+        except Exception as e:
+            raise StreamAbort(e) from e
+        finally:
+            self.progress.remove_task(task)
+            path.unlink(missing_ok=True)
+        self.idx += 1
+        self._note()
+
+    def finish(self):
+        """Upload the last (possibly partial) part."""
+        if self._fh is not None:
+            self._flush(final=True)
+
+    def abort(self):
+        """Drop whatever is still on disk."""
+        try:
+            if self._fh is not None:
+                self._fh.close()
+                self._fh = None
+            if self._path is not None:
+                Path(self._path).unlink(missing_ok=True)
+        except Exception:
+            pass
+
+
 def get_storage(cfg: dict):
     s = cfg.get("storage", "local")
     if s == "gdrive":
@@ -815,6 +1162,11 @@ def cmd_backup(cfg: dict, label: str = ""):
     def _cleanup_tmp():
         shutil.rmtree(tmp_dir, ignore_errors=True)
 
+    def _abort_backup():
+        if streaming:
+            storage.abort_stream(backup_name)
+        _cleanup_tmp()
+
     compression = cfg.get("compression", "gz")
     if compression not in ("gz", "bz2", "xz"):
         console.print(f"  [yellow]⚠ Compression '{compression}' is invalid, falling back to 'gz'.[/yellow]")
@@ -823,6 +1175,28 @@ def cmd_backup(cfg: dict, label: str = ""):
     excludes = cfg.get("exclude_patterns", [])
     storage  = get_storage(cfg)
 
+    check_storage = getattr(storage, "preflight", None)
+    if check_storage:
+        console.print("  [bold]Check[/bold]   Verifying GitHub repository…")
+        try:
+            check_storage()
+        except BaseException:
+            _cleanup_tmp()
+            raise
+        console.print(f"  {status_icon(True)} Repository is ready\n")
+
+    streaming = hasattr(storage, "begin_stream")
+    if streaming:
+        try:
+            storage.begin_stream(backup_name, tmp_dir / ".parts")
+        except BaseException:
+            _cleanup_tmp()
+            raise
+        console.print(
+            f"  {status_icon(True)} Streaming upload: the archive is sent in parts, "
+            "so your device never holds a full copy\n"
+        )
+
     meta = {
         "name":        backup_name,
         "date":        datetime.datetime.now().isoformat(),
@@ -845,7 +1219,8 @@ def cmd_backup(cfg: dict, label: str = ""):
     log("INFO", f"Collected {len(pkgs)} packages")
 
     console.print()
-    console.print("  [bold]Step 2/4[/bold]  Archiving directories…")
+    console.print("  [bold]Step 2/4[/bold]  " +
+                  ("Archiving & uploading directories…" if streaming else "Archiving directories…"))
     console.print()
 
     with Progress(
@@ -866,18 +1241,44 @@ def cmd_backup(cfg: dict, label: str = ""):
                 console.print(f"  [yellow]⚠ Skipping {src} (not found)[/yellow]")
                 continue
             out_path = tmp_dir / f"{key}.tar.{compression}"
+            sink = storage.stream_sink(out_path.name, progress) if streaming else None
             try:
-                actual_out = create_archive(src, out_path, compression, excludes, label_text, progress)
-                checksum = sha256(actual_out)
+                actual_out = create_archive(src, out_path, compression, excludes, label_text,
+                                            progress, sink=sink)
+                if sink is not None:
+                    sink.finish()
+                    archive_size, checksum = sink.total, sink.sha.hexdigest()
+                else:
+                    checksum     = sha256(actual_out)
+                    archive_size = actual_out.stat().st_size
                 meta["files"][key] = {
                     "archive":  actual_out.name,
-                    "size":     actual_out.stat().st_size,
+                    "size":     archive_size,
                     "checksum": checksum,
                     "source":   str(src),
                 }
-                log("INFO", f"Archived {src} → {actual_out.name} ({human_size(actual_out.stat().st_size)})")
+                log("INFO", f"Archived {src} → {actual_out.name} ({human_size(archive_size)})")
+            except (StreamAbort, KeyboardInterrupt):
+                if sink is not None:
+                    sink.abort()
+                for t in list(progress.tasks):
+                    progress.remove_task(t.id)
+                _abort_backup()
+                raise
+            except OSError as e:
+                if sink is not None:
+                    sink.abort()
+                if e.errno == errno.ENOSPC:             # out of space: stop, don't continue silently
+                    for t in list(progress.tasks):
+                        progress.remove_task(t.id)
+                    _abort_backup()
+                    raise
+                console.print(f"  [red]✗ Failed to archive {src}: {escape(str(e))}[/red]")
+                log("ERROR", f"Archive failed for {src}: {e}")
             except Exception as e:
-                console.print(f"  [red]✗ Failed to archive {src}: {e}[/red]")
+                if sink is not None:
+                    sink.abort()
+                console.print(f"  [red]✗ Failed to archive {src}: {escape(str(e))}[/red]")
                 log("ERROR", f"Archive failed for {src}: {e}")
 
     console.print()
@@ -890,6 +1291,7 @@ def cmd_backup(cfg: dict, label: str = ""):
     console.print()
 
     location = ""
+    upload_error = None
     with Progress(
         SpinnerColumn(),
         TextColumn("  {task.description}"),
@@ -901,13 +1303,26 @@ def cmd_backup(cfg: dict, label: str = ""):
             location = storage.upload(tmp_dir, backup_name, progress)
             storage.delete_old(cfg.get("max_backups", 5))
         except KeyboardInterrupt:
-            _cleanup_tmp()
+            _abort_backup()
             raise
         except Exception as e:
-            console.print(f"  [red]✗ Upload failed: {e}[/red]")
-            log("ERROR", f"Upload failed: {e}")
-            _cleanup_tmp()
-            return
+            upload_error = e
+            for t in list(progress.tasks):          # drop the half-finished spinner line
+                progress.remove_task(t.id)
+
+    if upload_error is not None:
+        log("ERROR", f"Upload failed: {upload_error}")
+        title, message, hint = _explain(upload_error)
+        print_error(f"Upload failed — {title}", message, hint)
+        if streaming:
+            _abort_backup()        # remove the incomplete release so it never counts as a backup
+            console.print("  [dim]The incomplete backup was removed from GitHub.[/dim]\n")
+        else:
+            console.print("  [bold]Your backup files were kept[/bold] so the work is not lost:")
+            console.print(f"  [white]{escape(str(tmp_dir))}[/white]", soft_wrap=True)
+            console.print("  [dim]Delete them when you no longer need them:[/dim]")
+            console.print(f"  rm -rf {escape(str(tmp_dir))}\n", soft_wrap=True)
+        return
 
     shutil.rmtree(tmp_dir, ignore_errors=True)
 
@@ -1000,7 +1415,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
@@ -1082,7 +1497,7 @@ def cmd_restore(cfg: dict, backup_name: str = ""):
                 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", [])
@@ -1198,7 +1613,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}")
 
 
@@ -1282,9 +1697,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", [])
@@ -1412,18 +1830,30 @@ def cmd_daemon(cfg: dict):
             log("ERROR", f"Daemon backup failed: {e}")
 
 
+def short_path(p) -> str:
+    """Shorten long Termux paths for narrow screens: $PREFIX/bin/tar, ~/.config/..."""
+    text   = str(p)
+    prefix = os.environ.get("PREFIX", "/data/data/com.termux/files/usr")
+    home   = str(Path.home())
+    if text == prefix or text.startswith(prefix + "/"):
+        return "$PREFIX" + text[len(prefix):]
+    if text == home or text.startswith(home + "/"):
+        return "~" + text[len(home):]
+    return text
+
+
 def cmd_status(cfg: dict):
     print_section("STATUS", "Current configuration and environment")
 
     sched = load_schedule()
 
-    cfg_table = Table(box=box.ROUNDED, show_header=False, padding=(0, 2))
-    cfg_table.add_column("Key",   style="dim cyan",   min_width=20)
-    cfg_table.add_column("Value", style="bold white")
+    cfg_table = Table(box=box.ROUNDED, show_header=False, padding=(0, 1))
+    cfg_table.add_column("Key",   style="dim cyan",   no_wrap=True)
+    cfg_table.add_column("Value", style="bold white", overflow="fold")
 
     cfg_table.add_row("Storage backend", cfg.get("storage", "local").upper())
     if cfg["storage"] == "local":
-        cfg_table.add_row("Local path",    cfg.get("local_path", "—"))
+        cfg_table.add_row("Local path",    short_path(cfg.get("local_path", "—")))
     elif cfg["storage"] == "gdrive":
         cfg_table.add_row("Drive folder",  cfg.get("gdrive_folder_id", "(root)") or "(root)")
     elif cfg["storage"] == "github":
@@ -1435,30 +1865,35 @@ def cmd_status(cfg: dict):
     if sched.get("enabled"):
         cfg_table.add_row("Schedule",    f"Daily at {sched['hour']:02d}:{sched['minute']:02d}")
     cfg_table.add_row("App version",     f"v{VERSION}")
-    cfg_table.add_row("Config file",     str(CONFIG_FILE))
-    cfg_table.add_row("Log file",        str(LOG_FILE))
+    for key, path in (("Config file", CONFIG_FILE), ("Log file", LOG_FILE)):
+        folder, _, fname = short_path(path).rpartition("/")
+        cfg_table.add_row(key, f"{escape(folder)}/\n{escape(fname)}")
 
     console.print(cfg_table)
     console.print()
 
-    env_table = Table(box=box.ROUNDED, show_header=False, padding=(0, 2),
+    env_table = Table(box=box.ROUNDED, show_header=False, padding=(0, 1),
                       title="[bold yellow]Environment[/bold yellow]")
-    env_table.add_column("Tool",   style="dim cyan", min_width=20)
-    env_table.add_column("Status")
+    env_table.add_column("Tool",   style="dim cyan", no_wrap=True)
+    env_table.add_column("",       no_wrap=True, width=1)
+    env_table.add_column("Path",   overflow="fold")
 
+    storage = cfg.get("storage", "local")
     checks = [
-        ("python3", shutil.which("python3")),
-        ("dpkg",    shutil.which("dpkg")),
-        ("tar",     shutil.which("tar")),
-        ("rclone",  shutil.which("rclone")),
-        ("git",     shutil.which("git")),
-        ("curl",    shutil.which("curl")),
+        ("python3", shutil.which("python3"), True),
+        ("dpkg",    shutil.which("dpkg"),    True),
+        ("tar",     shutil.which("tar"),     True),
+        ("rclone",  shutil.which("rclone"),  storage == "gdrive"),   # only needed for Google Drive
+        ("git",     shutil.which("git"),     True),
+        ("curl",    shutil.which("curl"),    True),
     ]
-    for name, path in checks:
+    for name, path, needed in checks:
         if path:
-            env_table.add_row(name, f"[green]✓ {path}[/green]")
+            env_table.add_row(name, "[green]✓[/green]", f"[green]{escape(short_path(path))}[/green]")
+        elif needed:
+            env_table.add_row(name, "[red]✗[/red]", f"[red]missing[/red] [dim]— pkg install {name}[/dim]")
         else:
-            env_table.add_row(name, "[red]✗ not found[/red]")
+            env_table.add_row(name, "[dim]–[/dim]", f"[dim]not needed for {storage.upper()}[/dim]")
 
     console.print(env_table)
 
@@ -1479,14 +1914,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():
@@ -1716,7 +2162,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
@@ -1764,15 +2210,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()
 
@@ -1789,117 +2237,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(
@@ -1909,9 +2367,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__":