Add nrfcloud-util base command (#84)

Several changes, related to adding a base command named `nrfcloud-util`, so
users can run it via eg `uvx nrfcloud-util blahblah`, for aiding
discoverability.

- add the base command, and collect subcommand args into it
  - this is a bit awkward, because we want to preserve the old names for
    the base commands (don't require running each as `nrfcloud-utils
    claim_and_provision_device ...`, keep the old direct names
    `claim_and_provision_device ...`)

- fix up pyproject.toml to adhere to PEP 621 (instead of using
  poetry-specific configs), so we can use `uv` as tooling if we want to
  instead of being fixed to `poetry` (poetry since version 2.0 has
  supported these, so there's no loss)

- update poetry version to latest since I'm touching everything anyway!

Author: noahp

.github/workflows/python.yml

@@ -11,7 +11,7 @@ on:
 env:
   REGISTRY_NAME: ${{ vars.REGISTRY_NAME }}
   REGISTRY_URI: ${{ vars.REGISTRY_URI }}
-  POETRY_VERSION: 2.2.1
+  POETRY_VERSION: 2.3.4
 
 jobs:
   build:

poetry.lock

@@ -2,36 +2,33 @@
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
 
-[tool.poetry]
+[project]
 name = "nrfcloud-utils"
 version = "0.0.1"
 description = "Scripts and utilities for working with the nRF Cloud"
-authors = ["Nordic Semiconductor ASA"]
 license = "BSD-3-Clause"
 readme = "README.md"
-repository = "https://github.com/nRFCloud/utils"
-packages = [
-    { include = "nrfcloud_utils", from = "src" }
+requires-python = ">=3.10,<4.0"
+authors = [
+    { name = "Nordic Semiconductor ASA" }
+]
+dependencies = [
+    "cbor2>=5.4.2.post1",
+    "cryptography>=46.0.5",
+    "cffi>=2.0.0",
+    "requests>=2.32.0",
+    "urllib3>=2.2.2",
+    "semver>=3.0.0",
+    "pyjwt>=2.3.0",
+    "inquirer>=3.4.0",
+    "nrfcredstore>=2.0.9",
 ]
 
-[tool.poetry.dependencies]
-python = "^3.10"
-cbor2 = "^5.4.2.post1"
-cryptography = "^46.0.5"
-cffi = "^2.0.0"
-requests = "^2.32.0"
-urllib3 = "^2.2.2"
-semver = "^3.0.0"
-pyjwt = "^2.3.0"
-inquirer = "^3.4.0"
-nrfcredstore = "^2.0.9"
-
-[tool.poetry.group.dev.dependencies]
-pytest = "^7.3.1"
-pytest-cov = "^4.0.0"
-pytest-watch = "^4.2.0"
+[project.urls]
+repository = "https://github.com/nRFCloud/utils"
 
-[tool.poetry.scripts]
+[project.scripts]
+nrfcloud-utils = "nrfcloud_utils.cli:run"
 claim_and_provision_device = "nrfcloud_utils.claim_and_provision_device:run"
 claim_devices = "nrfcloud_utils.claim_devices:run"
 create_ca_cert = "nrfcloud_utils.create_ca_cert:run"
@@ -44,5 +41,18 @@ nrf_cloud_device_mgmt = "nrfcloud_utils.nrf_cloud_device_mgmt:run"
 nrf_cloud_onboard = "nrfcloud_utils.nrf_cloud_onboard:run"
 nrf93_onboard = "nrfcloud_utils.nrf93_onboard:run"
 
+[dependency-groups]
+dev = [
+    "pytest>=7.3.1",
+    "pytest-cov>=4.0.0",
+    "pytest-watch>=4.2.0",
+    "poetry (>=2.3.4,<3.0.0)",  # used for development today. might be migrated to uv in the future.
+]
+
+[tool.poetry]
+packages = [
+    { include = "nrfcloud_utils", from = "src" }
+]
+
 [tool.pytest.ini_options]
 addopts = ["--import-mode=importlib"]

pyproject.toml

@@ -27,9 +27,10 @@
 IMEI_LEN = 15
 DEV_ID_MAX_LEN = 64
 
-def parse_args(in_args):
+def get_parser():
     parser = argparse.ArgumentParser(description="nRF Cloud Claim and Provision",
-                                     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+                                     formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+                                     add_help=False)
     parser_add_comms_args(parser)
     parser.add_argument("--dv", type=int, help="Number of days cert is valid",
                         default=(10 * 365))
@@ -81,6 +82,11 @@ def parse_args(in_args):
                         choices=['debug', 'info', 'warning', 'error', 'critical'],
                         help='Set the logging level'
     )
+    return parser
+
+def parse_args(in_args):
+    _p = get_parser()
+    parser = argparse.ArgumentParser(parents=[_p], description=_p.description, formatter_class=_p.formatter_class)
     args = parser.parse_args(in_args)
     setup_logging(level=args.log_level, use_color=not args.plain)
     return args

src/nrfcloud_utils/claim_and_provision_device.py

@@ -17,9 +17,10 @@
 IMEI_LEN = 15
 MAX_CSV_ROWS = 1000
 
-def parse_args(in_args):
+def get_parser():
     parser = argparse.ArgumentParser(description="nRF Cloud Claim Devices",
-                                     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+                                     formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+                                     add_help=False)
 
     parser.add_argument("--csv", type=str,
                         help="Filepath to attestation token CSV file",
@@ -39,6 +40,11 @@ def parse_args(in_args):
                         choices=['debug', 'info', 'warning', 'error', 'critical'],
                         help='Set the logging level'
     )
+    return parser
+
+def parse_args(in_args):
+    _p = get_parser()
+    parser = argparse.ArgumentParser(parents=[_p], description=_p.description, formatter_class=_p.formatter_class)
     args = parser.parse_args(in_args)
     setup_logging(level=args.log_level, use_color=not args.plain)
     return args

src/nrfcloud_utils/claim_devices.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+#
+# Copyright (c) 2025 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: BSD-3-Clause
+import argparse
+import sys
+
+from nrfcloud_utils import (
+    claim_and_provision_device,
+    claim_devices,
+    create_ca_cert,
+    create_device_credentials,
+    create_proxy_jwt,
+    device_credentials_installer,
+    gather_attestation_tokens,
+    modem_credentials_parser,
+    nrf_cloud_device_mgmt,
+    nrf_cloud_onboard,
+    nrf93_onboard,
+)
+
+_MODULES = {
+    "claim_and_provision_device": claim_and_provision_device,
+    "claim_devices": claim_devices,
+    "create_ca_cert": create_ca_cert,
+    "create_device_credentials": create_device_credentials,
+    "create_proxy_jwt": create_proxy_jwt,
+    "device_credentials_installer": device_credentials_installer,
+    "gather_attestation_tokens": gather_attestation_tokens,
+    "modem_credentials_parser": modem_credentials_parser,
+    "nrf_cloud_device_mgmt": nrf_cloud_device_mgmt,
+    "nrf_cloud_onboard": nrf_cloud_onboard,
+    "nrf93_onboard": nrf93_onboard,
+}
+
+
+def _build_parser():
+    parser = argparse.ArgumentParser(
+        prog="nrfcloud-utils",
+        description="Scripts and utilities for working with nRF Cloud",
+    )
+    subparsers = parser.add_subparsers(dest="command", metavar="command", required=False)
+    for name, mod in _MODULES.items():
+        _p = mod.get_parser()
+        subparsers.add_parser(
+            name,
+            parents=[_p],
+            description=_p.description,
+            formatter_class=_p.formatter_class,
+            help=_p.description,
+        )
+    return parser
+
+
+def run():
+    parser = _build_parser()
+    # parse_args() handles --help at both levels and validates the subcommand name
+    # and its args (using each module's get_parser() for the subparser definition).
+    # We then re-dispatch to the module's own main() so setup_logging and other
+    # module init runs exactly as it does when the command is called standalone.
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(0)
+
+    cmd = args.command
+    sys.argv = [cmd] + sys.argv[2:]
+    _MODULES[cmd].main(sys.argv[1:])
+
+
+if __name__ == "__main__":
+    run()

src/nrfcloud_utils/cli.py

@@ -27,8 +27,9 @@
 
 logger = logging.getLogger(__name__)
 
-def parse_args(in_args):
-    parser = argparse.ArgumentParser(description="Create CA Certificate")
+def get_parser():
+    parser = argparse.ArgumentParser(description="Create CA Certificate",
+                                     add_help=False)
     parser.add_argument("-c", type=str, help="2 character country code", default="NO")
     parser.add_argument("--st", type=str, help="State or Province", default="")
     parser.add_argument("-l", type=str, help="Locality", default="")
@@ -50,6 +51,11 @@ def parse_args(in_args):
                         choices=['debug', 'info', 'warning', 'error', 'critical'],
                         help='Set the logging level'
     )
+    return parser
+
+def parse_args(in_args):
+    _p = get_parser()
+    parser = argparse.ArgumentParser(parents=[_p], description=_p.description, formatter_class=_p.formatter_class)
     args = parser.parse_args(in_args)
     setup_logging(level=args.log_level)
     return args

src/nrfcloud_utils/create_ca_cert.py

@@ -24,8 +24,9 @@
 
 logger = logging.getLogger(__name__)
 
-def parse_args(in_args):
-    parser = argparse.ArgumentParser(description="Create Device Credentials")
+def get_parser():
+    parser = argparse.ArgumentParser(description="Create Device Credentials",
+                                     add_help=False)
     parser.add_argument("--ca", type=str, required=True, help="Filepath to your CA cert PEM", default="")
     parser.add_argument("--ca-key", type=str, required=True, help="Filepath to your CA's private key PEM", default="")
     parser.add_argument("-c", type=str, help="2 character country code; required if CSR is not provided", default="NO")
@@ -55,6 +56,11 @@ def parse_args(in_args):
                         choices=['debug', 'info', 'warning', 'error', 'critical'],
                         help='Set the logging level'
     )
+    return parser
+
+def parse_args(in_args):
+    _p = get_parser()
+    parser = argparse.ArgumentParser(parents=[_p], description=_p.description, formatter_class=_p.formatter_class)
     args = parser.parse_args(in_args)
     setup_logging(level=args.log_level)
     if len(args.csr) == 0 and len(args.cn) == 0:

src/nrfcloud_utils/create_device_credentials.py

@@ -14,9 +14,10 @@
 
 logger = logging.getLogger(__name__)
 
-def parse_args(in_args):
+def get_parser():
     parser = argparse.ArgumentParser(description="Create JWT for proxy (cloud-to-cloud) requests to nRF Cloud",
-                                     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+                                     formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+                                     add_help=False)
 
     parser.add_argument("--key", type=str, required=True,
                         help="Required filepath to the ES256 private key PEM (Service Key) used for JWT signing. \
@@ -43,6 +44,11 @@ def parse_args(in_args):
                         choices=['debug', 'info', 'warning', 'error', 'critical'],
                         help='Set the logging level'
     )
+    return parser
+
+def parse_args(in_args):
+    _p = get_parser()
+    parser = argparse.ArgumentParser(parents=[_p], description=_p.description, formatter_class=_p.formatter_class)
     args = parser.parse_args(in_args)
     setup_logging(level=args.log_level)
     return args

src/nrfcloud_utils/create_proxy_jwt.py

@@ -27,9 +27,10 @@
 MIN_REQD_MFW_VER = "1.3.0"
 MIN_REQD_MFW_VER_FOR_VERIFY = "1.3.2"
 
-def parse_args(in_args):
+def get_parser():
     parser = argparse.ArgumentParser(description="Device Credentials Installer",
-                                     formatter_class=argparse.ArgumentDefaultsHelpFormatter)
+                                     formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+                                     add_help=False)
     parser_add_comms_args(parser)
     parser.add_argument("--dv", type=int, help="Number of days cert is valid",
                         default=(10 * 365))
@@ -105,6 +106,11 @@ def parse_args(in_args):
                         choices=['debug', 'info', 'warning', 'error', 'critical'],
                         help='Set the logging level'
     )
+    return parser
+
+def parse_args(in_args):
+    _p = get_parser()
+    parser = argparse.ArgumentParser(parents=[_p], description=_p.description, formatter_class=_p.formatter_class)
     args = parser.parse_args(in_args)
     setup_logging(level=args.log_level, use_color=not args.plain)
     return args