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

{keepassxc_cli-1.2.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.2.0/keepassxc_cli.egg-info → keepassxc_cli-1.4.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: keepassxc-cli
-Version: 1.2.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.1.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"
@@ -163,6 +163,33 @@ keepassxc-cli mkdir "Work/Projects"   # create Projects inside Work
 
 Use `/`-separated paths to create nested groups. KeePassXC creates any missing path segments automatically.
 
+#### `group-uuid` — Look up a group's UUID by path
+
+```bash
+keepassxc-cli group-uuid "Work"
+keepassxc-cli group-uuid "Work/Projects"
+keepassxc-cli group-uuid "Work/Projects" -j
+```
+
+Returns the UUID for the group at the given path (relative to the database root). Useful for scripting — pipe the UUID into `add --group-uuid`.
+
+JSON output (`-j`):
+```json
+{
+  "path": "Work/Projects",
+  "name": "Projects",
+  "uuid": "<uuid>"
+}
+```
+
+#### `version` — Show the CLI version
+
+```bash
+keepassxc-cli version
+```
+
+Does not require a running KeePassXC instance.
+
 ## Configuration
 
 ### CLI config (`~/.keepassxc/cli.json`)
@@ -187,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.2.0 → keepassxc_cli-1.4.0}/README.md

@@ -148,6 +148,33 @@ keepassxc-cli mkdir "Work/Projects"   # create Projects inside Work
 
 Use `/`-separated paths to create nested groups. KeePassXC creates any missing path segments automatically.
 
+#### `group-uuid` — Look up a group's UUID by path
+
+```bash
+keepassxc-cli group-uuid "Work"
+keepassxc-cli group-uuid "Work/Projects"
+keepassxc-cli group-uuid "Work/Projects" -j
+```
+
+Returns the UUID for the group at the given path (relative to the database root). Useful for scripting — pipe the UUID into `add --group-uuid`.
+
+JSON output (`-j`):
+```json
+{
+  "path": "Work/Projects",
+  "name": "Projects",
+  "uuid": "<uuid>"
+}
+```
+
+#### `version` — Show the CLI version
+
+```bash
+keepassxc-cli version
+```
+
+Does not require a running KeePassXC instance.
+
 ## Configuration
 
 ### CLI config (`~/.keepassxc/cli.json`)
@@ -172,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.2.0 → keepassxc_cli-1.4.0}/keepassxc_cli/__main__.py

@@ -8,10 +8,10 @@ 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
+from .commands import setup, status, show, add, edit, rm, totp, clip, lock, mkdir, group_uuid, version
 
 # Shared parent parser that injects -j/--json into each subparser that supports it.
 # Defined at module level so command modules can import it if needed.
@@ -55,11 +55,23 @@ def main() -> None:
     clip.add_parser(subparsers)
     lock.add_parser(subparsers)
     mkdir.add_parser(subparsers)
+    group_uuid.add_parser(subparsers, fmt_parent)
+    version.add_parser(subparsers)
 
     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)
@@ -72,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.2.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.2.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.2.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.4.0/keepassxc_cli/commands/group_uuid.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import argparse
+import json
+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 []
+    p = subparsers.add_parser(
+        "group-uuid",
+        parents=parents,
+        help="Look up the UUID of a group by its path",
+    )
+    p.add_argument(
+        "path",
+        help="Group path relative to the database root (e.g. 'Work/Projects')",
+    )
+    p.set_defaults(func=run)
+
+
+def run(
+    client: BrowserClient,
+    args: argparse.Namespace,
+    cli_config: CliConfig,
+    browser_config: BrowserConfig,
+    browser_config_path: Path,
+    *,
+    fmt: str = "table",
+) -> int:
+    groups = client.get_database_groups()
+    root = groups[0]
+    parts = args.path.split("/")
+
+    # Paths are root-relative: traverse root.children, not the root itself.
+    current = root.children
+    matched = None
+    for part in parts:
+        matched = next((g for g in current if g.name == part), None)
+        if matched is None:
+            logger.error("Group not found: %r", args.path)
+            return 1
+        current = matched.children
+
+    if fmt == "json":
+        print(json.dumps({"path": args.path, "name": matched.name, "uuid": matched.uuid}, indent=2))
+    else:
+        print(f"{args.path} [{matched.uuid}]")
+    return 0

{keepassxc_cli-1.2.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.2.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.2.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.2.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.2.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.2.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.2.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.4.0/keepassxc_cli/commands/version.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import argparse
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from keepassxc_browser_api import BrowserClient, BrowserConfig
+
+from keepassxc_cli.config import CliConfig
+
+
+def add_parser(subparsers: argparse._SubParsersAction) -> None:
+    p = subparsers.add_parser("version", help="Show the keepassxc-cli version")
+    p.set_defaults(func=run)
+
+
+def run(
+    client: BrowserClient,
+    args: argparse.Namespace,
+    cli_config: CliConfig,
+    browser_config: BrowserConfig,
+    browser_config_path: Path,
+    *,
+    fmt: str = "table",
+) -> int:
+    try:
+        ver = version("keepassxc-cli")
+    except PackageNotFoundError:
+        ver = "unknown"
+    print(f"keepassxc-cli {ver}")
+    return 0

{keepassxc_cli-1.2.0 → keepassxc_cli-1.4.0/keepassxc_cli.egg-info}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: keepassxc-cli
-Version: 1.2.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.1.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"
@@ -163,6 +163,33 @@ keepassxc-cli mkdir "Work/Projects"   # create Projects inside Work
 
 Use `/`-separated paths to create nested groups. KeePassXC creates any missing path segments automatically.
 
+#### `group-uuid` — Look up a group's UUID by path
+
+```bash
+keepassxc-cli group-uuid "Work"
+keepassxc-cli group-uuid "Work/Projects"
+keepassxc-cli group-uuid "Work/Projects" -j
+```
+
+Returns the UUID for the group at the given path (relative to the database root). Useful for scripting — pipe the UUID into `add --group-uuid`.
+
+JSON output (`-j`):
+```json
+{
+  "path": "Work/Projects",
+  "name": "Projects",
+  "uuid": "<uuid>"
+}
+```
+
+#### `version` — Show the CLI version
+
+```bash
+keepassxc-cli version
+```
+
+Does not require a running KeePassXC instance.
+
 ## Configuration
 
 ### CLI config (`~/.keepassxc/cli.json`)
@@ -187,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.2.0 → keepassxc_cli-1.4.0}/keepassxc_cli.egg-info/SOURCES.txt

@@ -21,6 +21,7 @@ keepassxc_cli/commands/__init__.py
 keepassxc_cli/commands/add.py
 keepassxc_cli/commands/clip.py
 keepassxc_cli/commands/edit.py
+keepassxc_cli/commands/group_uuid.py
 keepassxc_cli/commands/lock.py
 keepassxc_cli/commands/mkdir.py
 keepassxc_cli/commands/rm.py
@@ -28,6 +29,7 @@ keepassxc_cli/commands/setup.py
 keepassxc_cli/commands/show.py
 keepassxc_cli/commands/status.py
 keepassxc_cli/commands/totp.py
+keepassxc_cli/commands/version.py
 tests/conftest.py
 tests/test_commands.py
 tests/test_config.py

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

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

{keepassxc_cli-1.2.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.1.0",
+    "keepassxc-browser-api==1.3.0",
     "pyperclip==1.8.0",
 ]
 

{keepassxc_cli-1.2.0 → keepassxc_cli-1.4.0}/tests/conftest.py

@@ -71,6 +71,7 @@ def mock_client():
     client.get_logins.return_value = [make_entry()]
     client.set_login.return_value = True
     client.create_group.return_value = make_group(uuid="new-uuid", name="NewGroup")
+    client.get_database_groups.return_value = [make_group()]
     client.get_totp.return_value = "123456"
     client.delete_entry.return_value = True
     client.lock_database.return_value = True

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

@@ -8,9 +8,10 @@ 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,
+    setup, status, show, add, edit, rm, totp, clip, lock, mkdir, group_uuid, version,
 )
 
 
@@ -41,6 +42,7 @@ def make_args(**kwargs) -> argparse.Namespace:
         "group_uuid": "",
         "uuid": "abcdef12-0000-0000-0000-000000000000",
         "name": "NewGroup",
+        "path": "Work",
     }
     defaults.update(kwargs)
     return argparse.Namespace(**defaults)
@@ -49,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 ---
@@ -77,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
@@ -127,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 ---
@@ -146,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 ---
@@ -165,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 ---
@@ -184,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 ---
@@ -237,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 ---
@@ -282,8 +283,136 @@ 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)
+        with pytest.raises(ConnectionError):
+            mkdir.run(mock_client, args, cli_config, browser_config, browser_config_path)
+
+
+# --- group-uuid ---
+
+
+class TestGroupUuidCommand:
+    def _make_tree(self, mock_group):
+        from keepassxc_browser_api import Group
+        projects = mock_group(uuid="projects-uuid", name="Projects")
+        work = mock_group(uuid="work-uuid", name="Work", children=[projects])
+        root = mock_group(uuid="root-uuid", name="Root", children=[work])
+        return [root]
+
+    def test_found_top_level(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)
+        args = make_args(path="Work")
+        rc = group_uuid.run(mock_client, args, cli_config, browser_config, browser_config_path)
+        assert rc == 0
+        out = capsys.readouterr().out
+        assert "work-uuid" in out
+        assert "Work" in out
+
+    def test_found_nested_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)
+        args = make_args(path="Work/Projects")
+        rc = group_uuid.run(mock_client, args, cli_config, browser_config, browser_config_path)
+        assert rc == 0
+        out = capsys.readouterr().out
+        assert "projects-uuid" in out
+
+    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
+        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)
+        args = make_args(path="Work/Nope/Projects")
+        rc = group_uuid.run(mock_client, args, cli_config, browser_config, browser_config_path)
+        assert rc == 1
+
+    def test_json_output(self, mock_client, cli_config, browser_config, browser_config_path, capsys, mock_group):
+        import json
+        mock_client.get_database_groups.return_value = self._make_tree(mock_group)
+        args = make_args(path="Work/Projects")
+        rc = group_uuid.run(mock_client, args, cli_config, browser_config, browser_config_path, fmt="json")
+        assert rc == 0
+        data = json.loads(capsys.readouterr().out)
+        assert data["path"] == "Work/Projects"
+        assert data["name"] == "Projects"
+        assert data["uuid"] == "projects-uuid"
+
+    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")
+        with pytest.raises(ConnectionError):
+            group_uuid.run(mock_client, args, cli_config, browser_config, browser_config_path)
+
+# --- version ---
+
+
+class TestVersionCommand:
+    def test_prints_version(self, mock_client, cli_config, browser_config, browser_config_path, capsys):
+        with patch("keepassxc_cli.commands.version.version", return_value="1.3.0"):
+            args = make_args()
+            rc = version.run(mock_client, args, cli_config, browser_config, browser_config_path)
+        assert rc == 0
+        out = capsys.readouterr().out
+        assert "keepassxc-cli" in out
+        assert "1.3.0" in out
+
+    def test_package_not_found(self, mock_client, cli_config, browser_config, browser_config_path, capsys):
+        from importlib.metadata import PackageNotFoundError
+        with patch("keepassxc_cli.commands.version.version", side_effect=PackageNotFoundError):
+            args = make_args()
+            rc = version.run(mock_client, args, cli_config, browser_config, browser_config_path)
+        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