keepassxc-cli 1.3.0__tar.gz → 1.4.0__tar.gz

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/CLAUDE.md

@@ -95,8 +95,18 @@ ruff check --ignore=E501 --exclude=__init__.py ./keepassxc_cli
 - **`from __future__ import annotations`** must be the first line of every `.py` source file.
 - **Ruff**: `ruff check --ignore=E501 --exclude=__init__.py ./keepassxc_cli`
 - **No async code**: Everything is synchronous. No threads in the CLI.
-- **Output**: Use `print()` for normal output, `sys.stderr` for errors.
-- **Exit codes**: `run()` functions return `int` (0 = success, 1 = failure).
+- **Output**: Use `print()` for normal (stdout) output. Error/warning messages use `logger.error()` / `logger.warning()` — never `print(file=sys.stderr)` directly.
+- **Logging config**: Set by `__main__.py`. Non-verbose: `WARNING` level, `"%(message)s"` format, to `sys.stderr`. Verbose (`-v`): `DEBUG` level with timestamp format to `sys.stderr`.
+- **Exit codes**: `run()` functions return `int` (0 = success, non-zero = failure). `__main__.py` maps exceptions to exit codes:
+
+  | Code | Meaning |
+  |---|---|
+  | `0` | Success |
+  | `1` | Generic error (`KeePassXCError`, `OSError`, `JSONDecodeError`, unknown `ProtocolError`) |
+  | `2` | `ConnectionError` — KeePassXC not running / socket not found |
+  | `3` | `DatabaseLockedError` — unlock timeout exceeded |
+  | `4` | `ProtocolError(error_code=6 or 19)` — access denied by user |
+
 - **Config permissions**: Config files are written with `0o600` (owner read/write only).
 - **Venv**: Always use `.venv` for development.
 - **Python ≥ 3.10** required.

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: keepassxc-cli
-Version: 1.3.0
+Version: 1.4.0
 Summary: CLI for KeePassXC using the browser extension protocol with biometric unlock
 License-Expression: MIT
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: keepassxc-browser-api==1.2.0
+Requires-Dist: keepassxc-browser-api==1.3.0
 Requires-Dist: pyperclip==1.8.0
 Provides-Extra: dev
 Requires-Dist: pytest>=7.0; extra == "dev"
@@ -214,6 +214,26 @@ Shared with `keepassxc-browser-api`. Contains the association keys created durin
 
 Both config files are stored with `0o600` permissions (owner read/write only).
 
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Generic error (unexpected KeePassXC error, OS error, config parse error) |
+| `2` | KeePassXC is not running or the socket is not found (`ConnectionError`) |
+| `3` | Database unlock timed out (`DatabaseLockedError`) |
+| `4` | Access denied by user — either the access prompt was cancelled or "Allow access to all entries" was denied |
+
+These codes are stable and suitable for scripting, e.g.:
+
+```bash
+keepassxc-cli show https://example.com || case $? in
+  2) echo "Start KeePassXC first" ;;
+  3) echo "Unlock timed out" ;;
+  4) echo "Access denied" ;;
+esac
+```
+
 ## Development
 
 ```bash

keepassxc_cli-1.3.0/keepassxc_cli.egg-info/PKG-INFO → keepassxc_cli-1.4.0/README.md

@@ -1,18 +1,3 @@
-Metadata-Version: 2.4
-Name: keepassxc-cli
-Version: 1.3.0
-Summary: CLI for KeePassXC using the browser extension protocol with biometric unlock
-License-Expression: MIT
-Requires-Python: >=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: keepassxc-browser-api==1.2.0
-Requires-Dist: pyperclip==1.8.0
-Provides-Extra: dev
-Requires-Dist: pytest>=7.0; extra == "dev"
-Requires-Dist: pytest-cov>=4.0; extra == "dev"
-Dynamic: license-file
-
 # keepassxc-cli
 
 A command-line interface for [KeePassXC](https://keepassxc.org/) that communicates via the browser extension protocol, supporting biometric (TouchID/fingerprint) unlock on supported platforms.
@@ -214,6 +199,26 @@ Shared with `keepassxc-browser-api`. Contains the association keys created durin
 
 Both config files are stored with `0o600` permissions (owner read/write only).
 
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Generic error (unexpected KeePassXC error, OS error, config parse error) |
+| `2` | KeePassXC is not running or the socket is not found (`ConnectionError`) |
+| `3` | Database unlock timed out (`DatabaseLockedError`) |
+| `4` | Access denied by user — either the access prompt was cancelled or "Allow access to all entries" was denied |
+
+These codes are stable and suitable for scripting, e.g.:
+
+```bash
+keepassxc-cli show https://example.com || case $? in
+  2) echo "Start KeePassXC first" ;;
+  3) echo "Unlock timed out" ;;
+  4) echo "Access denied" ;;
+esac
+```
+
 ## Development
 
 ```bash

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/keepassxc_cli/__main__.py

@@ -8,7 +8,7 @@ import sys
 from pathlib import Path
 
 from keepassxc_browser_api import BrowserClient, BrowserConfig
-from keepassxc_browser_api.exceptions import KeePassXCError, ConnectionError
+from keepassxc_browser_api.exceptions import ConnectionError, DatabaseLockedError, KeePassXCError, ProtocolError
 
 from .config import CliConfig, DEFAULT_CLI_CONFIG_PATH
 from .commands import setup, status, show, add, edit, rm, totp, clip, lock, mkdir, group_uuid, version
@@ -61,7 +61,17 @@ def main() -> None:
     args = parser.parse_args()
 
     if args.verbose:
-        logging.basicConfig(level=logging.DEBUG)
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+            datefmt="%H:%M:%S",
+        )
+    else:
+        logging.basicConfig(
+            level=logging.WARNING,
+            format="%(message)s",
+            stream=sys.stderr,
+        )
 
     cli_config_path = Path(args.config)
     cli_config = CliConfig.load(cli_config_path)
@@ -74,7 +84,16 @@ def main() -> None:
     client = BrowserClient(browser_config)
     try:
         rc = args.func(client, args, cli_config, browser_config, browser_api_config_path, fmt=fmt)
-    except (KeePassXCError, ConnectionError, OSError, json.JSONDecodeError) as e:
+    except ConnectionError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        rc = 2
+    except DatabaseLockedError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        rc = 3
+    except ProtocolError as e:
+        print(f"Error: {e}", file=sys.stderr)
+        rc = 4 if e.error_code in (6, 19) else 1
+    except (KeePassXCError, OSError, json.JSONDecodeError) as e:
         print(f"Error: {e}", file=sys.stderr)
         rc = 1
     sys.exit(rc)

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/keepassxc_cli/commands/add.py

@@ -2,13 +2,15 @@ from __future__ import annotations
 
 import argparse
 import getpass
-import sys
+import logging
 from pathlib import Path
 
 from keepassxc_browser_api import BrowserClient, BrowserConfig
 
 from keepassxc_cli.config import CliConfig
 
+logger = logging.getLogger(__name__)
+
 
 def add_parser(subparsers: argparse._SubParsersAction) -> None:
     p = subparsers.add_parser("add", help="Add a new entry")
@@ -32,15 +34,11 @@ def run(
     if password is None:
         password = getpass.getpass("Password: ")
 
-    success = client.set_login(
+    client.set_login(
         url=args.url,
         username=args.username,
         password=password,
         group_uuid=args.group_uuid,
     )
-    if success:
-        print("Entry added successfully.")
-        return 0
-    else:
-        print("Failed to add entry.", file=sys.stderr)
-        return 1
+    print("Entry added successfully.")
+    return 0

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/keepassxc_cli/commands/clip.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
 import argparse
-import sys
+import logging
 from pathlib import Path
 
 from keepassxc_browser_api import BrowserClient, BrowserConfig
 
 from keepassxc_cli.config import CliConfig
 
+logger = logging.getLogger(__name__)
+
 
 def add_parser(subparsers: argparse._SubParsersAction) -> None:
     p = subparsers.add_parser("clip", help="Copy a field to clipboard")
@@ -32,12 +34,12 @@ def run(
     try:
         import pyperclip
     except ImportError:
-        print("Error: pyperclip is required for clipboard support. Install it with: pip install pyperclip", file=sys.stderr)
+        logger.error("pyperclip is required for clipboard support. Install it with: pip install pyperclip")
         return 1
 
     entries = client.get_logins(args.url)
     if not entries:
-        print(f"No entries found for: {args.url}", file=sys.stderr)
+        logger.warning("No entries found for: %s", args.url)
         return 1
 
     entry = entries[0]
@@ -49,10 +51,10 @@ def run(
     elif args.field == "totp":
         value = client.get_totp(entry.uuid)
         if value is None:
-            print(f"No TOTP configured for: {entry.name}", file=sys.stderr)
+            logger.warning("No TOTP configured for: %s", entry.name)
             return 1
     else:
-        print(f"Unknown field: {args.field}", file=sys.stderr)
+        logger.error("Unknown field: %s", args.field)
         return 1
 
     pyperclip.copy(value)

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/keepassxc_cli/commands/edit.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
 import argparse
-import sys
+import logging
 from pathlib import Path
 
 from keepassxc_browser_api import BrowserClient, BrowserConfig
 
 from keepassxc_cli.config import CliConfig
 
+logger = logging.getLogger(__name__)
+
 
 def add_parser(subparsers: argparse._SubParsersAction) -> None:
     p = subparsers.add_parser(
@@ -39,14 +41,13 @@ def run(
     entries = client.get_logins(args.url)
     entry = next((e for e in entries if e.uuid == args.uuid), None)
     if entry is None:
-        print(
-            f"Entry {args.uuid} not found for URL: {args.url}\n"
-            "Hint: use 'keepassxc-cli show <url>' to look up the UUID.",
-            file=sys.stderr,
+        logger.error(
+            "Entry %s not found for URL: %s\nHint: use 'keepassxc-cli show <url>' to look up the UUID.",
+            args.uuid, args.url,
         )
         return 1
 
-    success = client.set_login(
+    client.set_login(
         url=args.url,
         username=args.username if args.username is not None else entry.login,
         password=args.password if args.password is not None else entry.password,
@@ -54,9 +55,5 @@ def run(
         uuid=entry.uuid,
         group_uuid=entry.group_uuid,
     )
-    if success:
-        print("Entry updated successfully.")
-        return 0
-    else:
-        print("Failed to update entry.", file=sys.stderr)
-        return 1
+    print("Entry updated successfully.")
+    return 0

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/keepassxc_cli/commands/group_uuid.py

@@ -2,13 +2,15 @@ from __future__ import annotations
 
 import argparse
 import json
-import sys
+import logging
 from pathlib import Path
 
 from keepassxc_browser_api import BrowserClient, BrowserConfig
 
 from keepassxc_cli.config import CliConfig
 
+logger = logging.getLogger(__name__)
+
 
 def add_parser(subparsers: argparse._SubParsersAction, fmt_parent: argparse.ArgumentParser | None = None) -> None:
     parents = [fmt_parent] if fmt_parent else []
@@ -34,10 +36,6 @@ def run(
     fmt: str = "table",
 ) -> int:
     groups = client.get_database_groups()
-    if not groups:
-        print("Failed to retrieve group tree.", file=sys.stderr)
-        return 1
-
     root = groups[0]
     parts = args.path.split("/")
 
@@ -47,7 +45,7 @@ def run(
     for part in parts:
         matched = next((g for g in current if g.name == part), None)
         if matched is None:
-            print(f"Group not found: {args.path!r}", file=sys.stderr)
+            logger.error("Group not found: %r", args.path)
             return 1
         current = matched.children
 

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/keepassxc_cli/commands/lock.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
 import argparse
-import sys
+import logging
 from pathlib import Path
 
 from keepassxc_browser_api import BrowserClient, BrowserConfig
 
 from keepassxc_cli.config import CliConfig
 
+logger = logging.getLogger(__name__)
+
 
 def add_parser(subparsers: argparse._SubParsersAction) -> None:
     p = subparsers.add_parser("lock", help="Lock the KeePassXC database")
@@ -28,5 +30,5 @@ def run(
         print("Database locked.")
         return 0
     else:
-        print("Failed to lock database.", file=sys.stderr)
+        logger.error("Failed to lock database.")
         return 1

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/keepassxc_cli/commands/mkdir.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
 import argparse
-import sys
+import logging
 from pathlib import Path
 
 from keepassxc_browser_api import BrowserClient, BrowserConfig
 
 from keepassxc_cli.config import CliConfig
 
+logger = logging.getLogger(__name__)
+
 
 def add_parser(subparsers: argparse._SubParsersAction) -> None:
     p = subparsers.add_parser("mkdir", help="Create a new group")
@@ -28,8 +30,5 @@ def run(
     fmt: str = "table",
 ) -> int:
     group = client.create_group(args.name)
-    if group is None:
-        print("Failed to create group.", file=sys.stderr)
-        return 1
     print(f"Group created: {group.name} [{group.uuid}]")
     return 0

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/keepassxc_cli/commands/rm.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
 import argparse
-import sys
+import logging
 from pathlib import Path
 
 from keepassxc_browser_api import BrowserClient, BrowserConfig
 
 from keepassxc_cli.config import CliConfig
 
+logger = logging.getLogger(__name__)
+
 
 def add_parser(subparsers: argparse._SubParsersAction) -> None:
     p = subparsers.add_parser("rm", help="Delete an entry by UUID")
@@ -31,10 +33,6 @@ def run(
             print("Aborted.")
             return 1
 
-    success = client.delete_entry(args.uuid)
-    if success:
-        print("Entry deleted.")
-        return 0
-    else:
-        print("Failed to delete entry.", file=sys.stderr)
-        return 1
+    client.delete_entry(args.uuid)
+    print("Entry deleted.")
+    return 0

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/keepassxc_cli/commands/setup.py

@@ -1,13 +1,15 @@
 from __future__ import annotations
 
 import argparse
-import sys
+import logging
 from pathlib import Path
 
 from keepassxc_browser_api import BrowserClient, BrowserConfig
 
 from keepassxc_cli.config import CliConfig
 
+logger = logging.getLogger(__name__)
+
 
 def add_parser(subparsers: argparse._SubParsersAction) -> None:
     p = subparsers.add_parser("setup", help="Associate with KeePassXC (key exchange)")
@@ -23,11 +25,7 @@ def run(
     *,
     fmt: str = "table",
 ) -> int:
-    success = client.setup()
-    if success:
-        browser_config.save(browser_config_path)
-        print("Successfully associated with KeePassXC.")
-        return 0
-    else:
-        print("Failed to associate with KeePassXC.", file=sys.stderr)
-        return 1
+    client.setup()
+    browser_config.save(browser_config_path)
+    print("Successfully associated with KeePassXC.")
+    return 0

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/keepassxc_cli/commands/show.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import argparse
-import sys
+import logging
 from pathlib import Path
 
 from keepassxc_browser_api import BrowserClient, BrowserConfig
@@ -9,6 +9,8 @@ from keepassxc_browser_api import BrowserClient, BrowserConfig
 from keepassxc_cli.config import CliConfig
 from keepassxc_cli.output import print_entry_detail
 
+logger = logging.getLogger(__name__)
+
 
 def add_parser(subparsers: argparse._SubParsersAction, fmt_parent: argparse.ArgumentParser | None = None) -> None:
     parents = [fmt_parent] if fmt_parent else []
@@ -30,7 +32,7 @@ def run(
 ) -> int:
     entries = client.get_logins(args.url)
     if not entries:
-        print(f"No entries found for: {args.url}", file=sys.stderr)
+        logger.warning("No entries found for: %s", args.url)
         return 1
     for entry in entries:
         print_entry_detail(entry, fmt, show_password=args.show_password, show_kph_prefix=getattr(args, "show_kph_prefix", False))

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/keepassxc_cli/commands/status.py

@@ -1,14 +1,17 @@
 from __future__ import annotations
 
 import argparse
+import logging
 from pathlib import Path
 
 from keepassxc_browser_api import BrowserClient, BrowserConfig
-from keepassxc_browser_api.exceptions import KeePassXCError
+from keepassxc_browser_api.exceptions import ConnectionError, KeePassXCError
 
 from keepassxc_cli.config import CliConfig
 from keepassxc_cli.output import print_status
 
+logger = logging.getLogger(__name__)
+
 
 def add_parser(subparsers: argparse._SubParsersAction, fmt_parent: argparse.ArgumentParser | None = None) -> None:
     parents = [fmt_parent] if fmt_parent else []
@@ -27,10 +30,11 @@ def run(
 ) -> int:
     info: dict = {}
 
-    connected = client.connect()
-    info["Connected"] = "yes" if connected else "no"
-
-    if not connected:
+    try:
+        client.connect()
+        info["Connected"] = "yes"
+    except ConnectionError:
+        info["Connected"] = "no"
         print_status(info, fmt)
         return 1
 

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/keepassxc_cli/commands/totp.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import argparse
-import sys
+import logging
 from pathlib import Path
 
 from keepassxc_browser_api import BrowserClient, BrowserConfig
@@ -9,6 +9,8 @@ from keepassxc_browser_api import BrowserClient, BrowserConfig
 from keepassxc_cli.config import CliConfig
 from keepassxc_cli.output import print_totp
 
+logger = logging.getLogger(__name__)
+
 
 def add_parser(subparsers: argparse._SubParsersAction, fmt_parent: argparse.ArgumentParser | None = None) -> None:
     parents = [fmt_parent] if fmt_parent else []
@@ -28,12 +30,12 @@ def run(
 ) -> int:
     entries = client.get_logins(args.url)
     if not entries:
-        print(f"No entries found for: {args.url}", file=sys.stderr)
+        logger.warning("No entries found for: %s", args.url)
         return 1
     entry = entries[0]
     totp = client.get_totp(entry.uuid)
     if totp is None:
-        print(f"No TOTP configured for: {entry.name}", file=sys.stderr)
+        logger.warning("No TOTP configured for: %s", entry.name)
         return 1
     print_totp(totp, fmt)
     return 0

keepassxc_cli-1.3.0/README.md → keepassxc_cli-1.4.0/keepassxc_cli.egg-info/PKG-INFO

@@ -1,3 +1,18 @@
+Metadata-Version: 2.4
+Name: keepassxc-cli
+Version: 1.4.0
+Summary: CLI for KeePassXC using the browser extension protocol with biometric unlock
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: keepassxc-browser-api==1.3.0
+Requires-Dist: pyperclip==1.8.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Dynamic: license-file
+
 # keepassxc-cli
 
 A command-line interface for [KeePassXC](https://keepassxc.org/) that communicates via the browser extension protocol, supporting biometric (TouchID/fingerprint) unlock on supported platforms.
@@ -199,6 +214,26 @@ Shared with `keepassxc-browser-api`. Contains the association keys created durin
 
 Both config files are stored with `0o600` permissions (owner read/write only).
 
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Success |
+| `1` | Generic error (unexpected KeePassXC error, OS error, config parse error) |
+| `2` | KeePassXC is not running or the socket is not found (`ConnectionError`) |
+| `3` | Database unlock timed out (`DatabaseLockedError`) |
+| `4` | Access denied by user — either the access prompt was cancelled or "Allow access to all entries" was denied |
+
+These codes are stable and suitable for scripting, e.g.:
+
+```bash
+keepassxc-cli show https://example.com || case $? in
+  2) echo "Start KeePassXC first" ;;
+  3) echo "Unlock timed out" ;;
+  4) echo "Access denied" ;;
+esac
+```
+
 ## Development
 
 ```bash

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/keepassxc_cli.egg-info/requires.txt

@@ -1,4 +1,4 @@
-keepassxc-browser-api==1.2.0
+keepassxc-browser-api==1.3.0
 pyperclip==1.8.0
 
 [dev]

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/pyproject.toml

@@ -10,7 +10,7 @@ readme = "README.md"
 requires-python = ">=3.10"
 license = "MIT"
 dependencies = [
-    "keepassxc-browser-api==1.2.0",
+    "keepassxc-browser-api==1.3.0",
     "pyperclip==1.8.0",
 ]
 

{keepassxc_cli-1.3.0 → keepassxc_cli-1.4.0}/tests/test_commands.py

@@ -8,6 +8,7 @@ from unittest.mock import MagicMock, patch
 import pytest
 
 from keepassxc_browser_api import Entry, BrowserConfig, Association
+from keepassxc_browser_api.exceptions import ConnectionError, DatabaseLockedError, ProtocolError
 from keepassxc_cli.config import CliConfig
 from keepassxc_cli.commands import (
     setup, status, show, add, edit, rm, totp, clip, lock, mkdir, group_uuid, version,
@@ -50,19 +51,18 @@ def make_args(**kwargs) -> argparse.Namespace:
 # --- setup ---
 
 class TestSetupCommand:
-    def test_success(self, mock_client, cli_config, browser_config, browser_config_path):
-        mock_client.setup.return_value = True
+    def test_success(self, mock_client, cli_config, browser_config, browser_config_path, capsys):
+        mock_client.setup.return_value = None
         args = make_args()
         rc = setup.run(mock_client, args, cli_config, browser_config, browser_config_path)
         assert rc == 0
         mock_client.setup.assert_called_once()
 
-    def test_failure(self, mock_client, cli_config, browser_config, browser_config_path, capsys):
-        mock_client.setup.return_value = False
+    def test_failure_propagates(self, mock_client, cli_config, browser_config, browser_config_path):
+        mock_client.setup.side_effect = ConnectionError("KeePassXC not running")
         args = make_args()
-        rc = setup.run(mock_client, args, cli_config, browser_config, browser_config_path)
-        assert rc == 1
-        assert "Failed" in capsys.readouterr().err
+        with pytest.raises(ConnectionError):
+            setup.run(mock_client, args, cli_config, browser_config, browser_config_path)
 
 
 # --- status ---
@@ -78,7 +78,7 @@ class TestStatusCommand:
         assert "yes" in out
 
     def test_not_connected(self, mock_client, cli_config, browser_config, browser_config_path, capsys):
-        mock_client.connect.return_value = False
+        mock_client.connect.side_effect = ConnectionError("not available")
         args = make_args()
         rc = status.run(mock_client, args, cli_config, browser_config, browser_config_path)
         assert rc == 1
@@ -128,12 +128,12 @@ class TestShowCommand:
         assert rc == 0
         assert "KPH: url: https://github.com" in capsys.readouterr().out
 
-    def test_no_entries(self, mock_client, cli_config, browser_config, browser_config_path, capsys):
+    def test_no_entries(self, mock_client, cli_config, browser_config, browser_config_path, caplog):
         mock_client.get_logins.return_value = []
         args = make_args(url="https://notfound.com")
         rc = show.run(mock_client, args, cli_config, browser_config, browser_config_path)
         assert rc == 1
-        assert "No entries" in capsys.readouterr().err
+        assert any("No entries" in r.message for r in caplog.records)
 
 
 # --- add ---
@@ -147,11 +147,11 @@ class TestAddCommand:
         mock_client.set_login.assert_called_once()
         assert "added" in capsys.readouterr().out.lower()
 
-    def test_failure(self, mock_client, cli_config, browser_config, browser_config_path, capsys):
-        mock_client.set_login.return_value = False
+    def test_failure_propagates(self, mock_client, cli_config, browser_config, browser_config_path):
+        mock_client.set_login.side_effect = ProtocolError("access denied", error_code=6)
         args = make_args(url="https://example.com", username="u", password="p", group_uuid="")
-        rc = add.run(mock_client, args, cli_config, browser_config, browser_config_path)
-        assert rc == 1
+        with pytest.raises(ProtocolError):
+            add.run(mock_client, args, cli_config, browser_config, browser_config_path)
 
 
 # --- edit ---
@@ -166,12 +166,12 @@ class TestEditCommand:
         assert rc == 0
         assert "updated" in capsys.readouterr().out.lower()
 
-    def test_entry_not_found(self, mock_client, cli_config, browser_config, browser_config_path, capsys):
+    def test_entry_not_found(self, mock_client, cli_config, browser_config, browser_config_path, caplog):
         mock_client.get_logins.return_value = []
         args = make_args(uuid="nonexistent-uuid", url="https://example.com", username=None, password=None, title=None)
         rc = edit.run(mock_client, args, cli_config, browser_config, browser_config_path)
         assert rc == 1
-        assert "not found" in capsys.readouterr().err.lower()
+        assert any("not found" in r.message.lower() for r in caplog.records)
 
 
 # --- rm ---
@@ -185,11 +185,11 @@ class TestRmCommand:
         mock_client.delete_entry.assert_called_once_with("some-uuid")
         assert "deleted" in capsys.readouterr().out.lower()
 
-    def test_failure(self, mock_client, cli_config, browser_config, browser_config_path, capsys):
-        mock_client.delete_entry.return_value = False
+    def test_failure_propagates(self, mock_client, cli_config, browser_config, browser_config_path):
+        mock_client.delete_entry.side_effect = ProtocolError("access denied", error_code=6)
         args = make_args(uuid="some-uuid", yes=True)
-        rc = rm.run(mock_client, args, cli_config, browser_config, browser_config_path)
-        assert rc == 1
+        with pytest.raises(ProtocolError):
+            rm.run(mock_client, args, cli_config, browser_config, browser_config_path)
 
 
 # --- totp ---
@@ -238,12 +238,12 @@ class TestClipCommand:
             rc = clip.run(mock_client, args, cli_config, browser_config, browser_config_path)
         assert rc == 1
 
-    def test_pyperclip_missing(self, mock_client, cli_config, browser_config, browser_config_path, capsys):
+    def test_pyperclip_missing(self, mock_client, cli_config, browser_config, browser_config_path, caplog):
         args = make_args(url="https://example.com", field="password")
         with patch.dict("sys.modules", {"pyperclip": None}):
             rc = clip.run(mock_client, args, cli_config, browser_config, browser_config_path)
         assert rc == 1
-        assert "pyperclip" in capsys.readouterr().err
+        assert any("pyperclip" in r.message for r in caplog.records)
 
 
 # --- lock ---
@@ -283,11 +283,11 @@ class TestMkdirCommand:
         assert rc == 0
         mock_client.create_group.assert_called_once_with("Work/Projects")
 
-    def test_failure(self, mock_client, cli_config, browser_config, browser_config_path, capsys):
-        mock_client.create_group.return_value = None
+    def test_failure_propagates(self, mock_client, cli_config, browser_config, browser_config_path):
+        mock_client.create_group.side_effect = ConnectionError("KeePassXC not running")
         args = make_args(name="MyGroup")
-        rc = mkdir.run(mock_client, args, cli_config, browser_config, browser_config_path)
-        assert rc == 1
+        with pytest.raises(ConnectionError):
+            mkdir.run(mock_client, args, cli_config, browser_config, browser_config_path)
 
 
 # --- group-uuid ---
@@ -318,13 +318,12 @@ class TestGroupUuidCommand:
         out = capsys.readouterr().out
         assert "projects-uuid" in out
 
-    def test_not_found(self, mock_client, cli_config, browser_config, browser_config_path, capsys, mock_group):
+    def test_not_found(self, mock_client, cli_config, browser_config, browser_config_path, caplog, mock_group):
         mock_client.get_database_groups.return_value = self._make_tree(mock_group)
         args = make_args(path="Nonexistent")
         rc = group_uuid.run(mock_client, args, cli_config, browser_config, browser_config_path)
         assert rc == 1
-        err = capsys.readouterr().err
-        assert "not found" in err.lower()
+        assert any("not found" in r.message.lower() for r in caplog.records)
 
     def test_not_found_mid_path(self, mock_client, cli_config, browser_config, browser_config_path, capsys, mock_group):
         mock_client.get_database_groups.return_value = self._make_tree(mock_group)
@@ -343,12 +342,11 @@ class TestGroupUuidCommand:
         assert data["name"] == "Projects"
         assert data["uuid"] == "projects-uuid"
 
-    def test_get_database_groups_failure(self, mock_client, cli_config, browser_config, browser_config_path, capsys):
-        mock_client.get_database_groups.return_value = []
+    def test_get_database_groups_failure_propagates(self, mock_client, cli_config, browser_config, browser_config_path, mock_group):
+        mock_client.get_database_groups.side_effect = ConnectionError("KeePassXC not running")
         args = make_args(path="Work")
-        rc = group_uuid.run(mock_client, args, cli_config, browser_config, browser_config_path)
-        assert rc == 1
-
+        with pytest.raises(ConnectionError):
+            group_uuid.run(mock_client, args, cli_config, browser_config, browser_config_path)
 
 # --- version ---
 
@@ -371,3 +369,50 @@ class TestVersionCommand:
         assert rc == 0
         out = capsys.readouterr().out
         assert "unknown" in out
+
+
+# --- exit codes ---
+
+class TestExitCodes:
+    """Test that __main__.main() maps exceptions to the correct exit codes."""
+
+    def _run_main(self, exception, monkeypatch, capsys, tmp_path):
+        from keepassxc_cli.__main__ import main
+
+        config_path = tmp_path / "cli.json"
+        monkeypatch.setattr("sys.argv", [
+            "keepassxc-cli", "--config", str(config_path),
+            "show", "https://example.com",
+        ])
+
+        mock_client_instance = MagicMock()
+        mock_client_instance.get_logins.side_effect = exception
+
+        with patch("keepassxc_cli.__main__.BrowserClient", return_value=mock_client_instance):
+            with patch("keepassxc_cli.__main__.BrowserConfig"):
+                with patch("keepassxc_cli.__main__.CliConfig"):
+                    with pytest.raises(SystemExit) as exc_info:
+                        main()
+
+        return exc_info.value.code, capsys.readouterr()
+
+    def test_connection_error_rc2(self, monkeypatch, capsys, tmp_path):
+        rc, out = self._run_main(ConnectionError("not running"), monkeypatch, capsys, tmp_path)
+        assert rc == 2
+        assert "Error:" in out.err
+
+    def test_database_locked_rc3(self, monkeypatch, capsys, tmp_path):
+        rc, out = self._run_main(DatabaseLockedError("locked"), monkeypatch, capsys, tmp_path)
+        assert rc == 3
+
+    def test_access_denied_rc4(self, monkeypatch, capsys, tmp_path):
+        rc, out = self._run_main(ProtocolError("denied", error_code=6), monkeypatch, capsys, tmp_path)
+        assert rc == 4
+
+    def test_access_denied_code19_rc4(self, monkeypatch, capsys, tmp_path):
+        rc, out = self._run_main(ProtocolError("denied", error_code=19), monkeypatch, capsys, tmp_path)
+        assert rc == 4
+
+    def test_other_protocol_error_rc1(self, monkeypatch, capsys, tmp_path):
+        rc, out = self._run_main(ProtocolError("other error", error_code=7), monkeypatch, capsys, tmp_path)
+        assert rc == 1