Promote the MFA script to a packaged CLI: uvx evnex auth

- evnex.cli exposes an 'evnex' console script (evnex auth
  status/signin/enroll-totp/confirm-totp/disable), so 'uvx evnex auth'
  works with nothing installed
- qrcode becomes an optional extra; without it the CLI still prints the
  otpauth:// URI and secret, with a hint to run 'uvx --with qrcode evnex'
- README documents the CLI including answering sign-in challenges from
  a password manager via --code-command (1Password CLI v2 example)
- Replace a real account UUID in test fixtures with a synthetic one

Author: hardbyte

README.md

@@ -134,6 +134,35 @@ await auth.set_mfa_preference()               # disable MFA entirely
 Completing a new TOTP enrollment replaces the previously registered
 authenticator device.
 
+## Command line
+
+Everything above is also available as a CLI, runnable directly with
+[uv](https://docs.astral.sh/uv/):
+
+```shell
+export EVNEX_CLIENT_USERNAME=you@example.com
+export EVNEX_CLIENT_PASSWORD=<your password>
+
+uvx evnex auth status                # which MFA methods are enabled
+uvx evnex auth enroll-totp           # start enrolling a (new) TOTP device
+uvx evnex auth confirm-totp 123456 --device-name "My phone"
+uvx evnex auth disable               # turn MFA off entirely
+```
+
+`enroll-totp` prints an `otpauth://` URI you can paste straight into a
+password manager's one-time password field. For a scannable QR code (in the
+terminal, or the browser with `--browser`), include the optional qrcode
+dependency: `uvx --with qrcode evnex auth enroll-totp`.
+
+Session tokens are cached (mode 0600, `~/.cache/evnex/tokens.json` by
+default) so an MFA sign-in is only needed occasionally. To answer sign-in
+challenges from a password manager instead of typing codes — for example
+with the [1Password CLI](https://developer.1password.com/docs/cli/) v2+:
+
+```shell
+uvx evnex auth --code-command 'op item get Evnex --otp' signin
+```
+
 ## Examples
 
 `python-evnex` is intended as a library, but a few example scripts are provided in the `examples` folder.

examples/manage_mfa.py evnex/cli.pyexamples/manage_mfa.py renamed to evnex/cli.py

@@ -1,26 +1,15 @@
-#!/usr/bin/env -S uv run --script
-# /// script
-# requires-python = ">=3.11"
-# dependencies = [
-#     "evnex",
-#     "qrcode>=8.0",
-# ]
-#
-# [tool.uv.sources]
-# evnex = { path = "..", editable = true }
-# ///
-"""Manage MFA on your EVNEX account: view status, enroll or replace a TOTP
-device, or disable MFA — none of which the EVNEX app currently exposes.
-
-Usage (credentials via EVNEX_CLIENT_USERNAME / EVNEX_CLIENT_PASSWORD):
-
-    uv run examples/manage_mfa.py status
-    uv run examples/manage_mfa.py enroll-totp [--browser]
-    uv run examples/manage_mfa.py confirm-totp CODE [--device-name NAME]
-    uv run examples/manage_mfa.py disable --yes
-
-Session tokens are cached (0600) so MFA sign-in is only needed once; pass
---code to answer a sign-in challenge non-interactively.
+"""Command line interface for the EVNEX Cloud API client.
+
+Run without installing anything via uv:
+
+    uvx evnex auth status
+    uvx evnex auth enroll-totp
+    uvx evnex auth confirm-totp CODE --device-name NAME
+    uvx evnex auth disable
+
+Credentials come from EVNEX_CLIENT_USERNAME / EVNEX_CLIENT_PASSWORD (or are
+prompted for). Session tokens are cached with 0600 permissions so an MFA
+sign-in is only needed occasionally, not per command.
 """
 
 from __future__ import annotations
@@ -35,9 +24,6 @@
 import webbrowser
 from pathlib import Path
 
-import qrcode
-import qrcode.image.svg
-
 from evnex.auth import AuthChallenge, EvnexAuth, TokenSet
 from evnex.errors import EvnexAuthError, ReauthenticationRequiredError
 
@@ -66,6 +52,20 @@ def _load_tokens(cache: Path) -> TokenSet | None:
     return None
 
 
+async def _challenge_code(args: argparse.Namespace, challenge: AuthChallenge) -> str:
+    if args.code:
+        code, args.code = args.code, None  # a code is single-use
+        return str(code)
+    if args.code_command:
+        proc = await asyncio.create_subprocess_shell(
+            args.code_command, stdout=asyncio.subprocess.PIPE
+        )
+        stdout, _ = await proc.communicate()
+        print("Code obtained from --code-command", file=sys.stderr)
+        return stdout.decode().strip()
+    return input(f"Enter the 6-digit code ({challenge.name}): ")
+
+
 async def signed_in_auth(args: argparse.Namespace) -> EvnexAuth:
     """Return an EvnexAuth with a usable session, signing in if needed."""
     cache: Path = args.token_cache
@@ -85,23 +85,26 @@ async def signed_in_auth(args: argparse.Namespace) -> EvnexAuth:
     )
     result = await auth.start_authentication(username, password)
     while isinstance(result, AuthChallenge):
-        if args.code:
-            code, args.code = args.code, None  # a code is single-use
-        elif args.code_command:
-            proc = await asyncio.create_subprocess_shell(
-                args.code_command, stdout=asyncio.subprocess.PIPE
-            )
-            stdout, _ = await proc.communicate()
-            code = stdout.decode().strip()
-            print("Code obtained from --code-command", file=sys.stderr)
-        else:
-            code = input(f"Enter the 6-digit code ({result.name}): ")
-        result = await auth.respond_to_challenge(result, code)
+        result = await auth.respond_to_challenge(
+            result, await _challenge_code(args, result)
+        )
     print(f"Signed in as {username}; session cached at {cache}", file=sys.stderr)
     return auth
 
 
 def show_qr(uri: str, open_browser: bool) -> None:
+    """Render the enrollment QR in the terminal, and optionally a browser."""
+    try:
+        import qrcode
+        import qrcode.image.svg
+    except ImportError:
+        print(
+            "(for a scannable QR code, run with the qrcode package:"
+            " uvx --with qrcode evnex ...)",
+            file=sys.stderr,
+        )
+        return
+
     qr = qrcode.QRCode(border=2)
     qr.add_data(uri)
     qr.print_ascii(tty=sys.stdout.isatty())
@@ -130,15 +133,12 @@ async def cmd_enroll_totp(args: argparse.Namespace) -> None:
     account = os.environ.get("EVNEX_CLIENT_USERNAME", "evnex-account")
     uri = enrollment.provisioning_uri(account)
 
-    print("Scan this QR code with your authenticator app, or paste the")
+    print("Scan the QR code with your authenticator app, or paste the")
     print("otpauth URI into a password manager's one-time password field:\n")
     print(f"  {uri}\n")
     print(f"(bare secret for manual entry: {enrollment.secret})\n")
     show_qr(uri, open_browser=args.browser)
-    print(
-        "\nThen run: uv run examples/manage_mfa.py confirm-totp CODE"
-        " [--device-name NAME]"
-    )
+    print("\nThen run: evnex auth confirm-totp CODE [--device-name NAME]")
 
 
 async def cmd_confirm_totp(args: argparse.Namespace) -> None:
@@ -166,31 +166,64 @@ async def cmd_signin(args: argparse.Namespace) -> None:
     await signed_in_auth(args)
 
 
-def main() -> None:
-    parser = argparse.ArgumentParser(description=__doc__)
-    parser.add_argument(
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="evnex",
+        description="Command line interface for the EVNEX Cloud API.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    auth = sub.add_parser(
+        "auth",
+        help="manage authentication and MFA for your EVNEX account",
+        description=(
+            "Sign in and manage MFA for your EVNEX account. Credentials come "
+            "from EVNEX_CLIENT_USERNAME / EVNEX_CLIENT_PASSWORD or prompts; "
+            "session tokens are cached so an MFA code is only needed once."
+        ),
+    )
+    auth.add_argument(
         "--token-cache",
         type=Path,
         default=DEFAULT_CACHE,
         help=f"where to cache session tokens (default: {DEFAULT_CACHE})",
     )
-    parser.add_argument("--code", help="6-digit code to answer a sign-in MFA challenge")
-    parser.add_argument(
+    auth.add_argument(
+        "--code",
+        help="6-digit code to answer a sign-in MFA challenge non-interactively",
+    )
+    auth.add_argument(
         "--code-command",
-        help="shell command that prints a current MFA code, e.g. "
-        "'op item get Evnex --otp' for 1Password",
+        help="shell command printing a current MFA code, e.g. "
+        "'op item get Evnex --otp' with the 1Password CLI",
+    )
+    auth_sub = auth.add_subparsers(dest="auth_command", required=True)
+
+    auth_sub.add_parser("status", help="show which MFA methods are enabled")
+    auth_sub.add_parser("signin", help="sign in and cache session tokens")
+
+    enroll = auth_sub.add_parser(
+        "enroll-totp",
+        help="enroll a new TOTP authenticator device",
+        description=(
+            "Start enrolling a TOTP device: prints the otpauth:// URI (paste "
+            "into a password manager's one-time password field) and a QR code. "
+            "Completing enrollment with confirm-totp replaces any previously "
+            "registered device."
+        ),
     )
-    sub = parser.add_subparsers(dest="command", required=True)
-
-    sub.add_parser("status", help="show which MFA methods are enabled")
-    sub.add_parser("signin", help="sign in and cache session tokens")
-
-    enroll = sub.add_parser("enroll-totp", help="enroll a (new) TOTP device")
     enroll.add_argument(
         "--browser", action="store_true", help="also open the QR code in a browser"
     )
 
-    confirm = sub.add_parser("confirm-totp", help="confirm the new TOTP device")
+    confirm = auth_sub.add_parser(
+        "confirm-totp",
+        help="verify the new TOTP device and enable it",
+        description=(
+            "Verify a code generated by the newly enrolled device. By default "
+            "this also makes TOTP the preferred MFA method."
+        ),
+    )
     confirm.add_argument("totp_code", help="6-digit code from the new device")
     confirm.add_argument("--device-name", default="", help="friendly device name")
     confirm.add_argument(
@@ -200,22 +233,34 @@ def main() -> None:
         help="register the device without changing the MFA preference",
     )
 
-    disable = sub.add_parser("disable", help="turn MFA off for the account")
+    disable = auth_sub.add_parser(
+        "disable",
+        help="turn MFA off for the account",
+        description="Disable all MFA methods for the account.",
+    )
     disable.add_argument("--yes", action="store_true", help="skip confirmation")
 
-    args = parser.parse_args()
-    handler = {
-        "status": cmd_status,
-        "signin": cmd_signin,
-        "enroll-totp": cmd_enroll_totp,
-        "confirm-totp": cmd_confirm_totp,
-        "disable": cmd_disable,
-    }[args.command]
+    return parser
+
+
+HANDLERS = {
+    "status": cmd_status,
+    "signin": cmd_signin,
+    "enroll-totp": cmd_enroll_totp,
+    "confirm-totp": cmd_confirm_totp,
+    "disable": cmd_disable,
+}
+
+
+def main() -> None:
+    args = build_parser().parse_args()
     try:
-        asyncio.run(handler(args))
+        asyncio.run(HANDLERS[args.auth_command](args))
     except EvnexAuthError as err:
         print(f"Authentication error: {err}", file=sys.stderr)
         sys.exit(1)
+    except KeyboardInterrupt:
+        sys.exit(130)
 
 
 if __name__ == "__main__":

pyproject.toml

@@ -19,6 +19,12 @@ dependencies = [
     "pydantic-settings>=2.2,<3.0",
 ]
 
+[project.optional-dependencies]
+cli = ["qrcode>=8.0"]
+
+[project.scripts]
+evnex = "evnex.cli:main"
+
 [dependency-groups]
 dev = [
     "ruff>=0.12.10",

tests/test_auth.py

@@ -36,7 +36,7 @@
 
 USER_PAYLOAD = {
     "data": {
-        "id": "b102b5e3-2b00-4f6b-9b0c-b579c609f969",
+        "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
         "createdDate": "2022-01-01T00:00:00Z",
         "updatedDate": "2022-01-01T00:00:00Z",
         "name": "Test User",

tests/test_cli.py

@@ -0,0 +1,31 @@
+"""Smoke tests for the CLI parser wiring."""
+
+import pytest
+
+from evnex.cli import HANDLERS, build_parser
+
+
+def test_all_auth_commands_parse_and_have_handlers():
+    parser = build_parser()
+    for command, argv in [
+        ("status", ["auth", "status"]),
+        ("signin", ["auth", "signin"]),
+        ("enroll-totp", ["auth", "enroll-totp", "--browser"]),
+        ("confirm-totp", ["auth", "confirm-totp", "123456", "--device-name", "x"]),
+        ("disable", ["auth", "disable", "--yes"]),
+    ]:
+        args = parser.parse_args(argv)
+        assert args.auth_command == command
+        assert command in HANDLERS
+
+
+def test_code_command_option_parses():
+    args = build_parser().parse_args(
+        ["auth", "--code-command", "op item get Evnex --otp", "status"]
+    )
+    assert args.code_command == "op item get Evnex --otp"
+
+
+def test_missing_subcommand_errors():
+    with pytest.raises(SystemExit):
+        build_parser().parse_args(["auth"])

tests/test_schema.py

@@ -8,7 +8,7 @@
 def test_user_without_name_validates():
     payload = {
         "data": {
-            "id": "b102b5e3-2b00-4f6b-9b0c-b579c609f969",
+            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
             "createdDate": "2022-01-01T00:00:00Z",
             "updatedDate": "2022-01-01T00:00:00Z",
             "email": "user@example.com",