feat(cli): add CLI with CI convenience functions

- Add nipyapi CLI using Google Fire (optional install: nipyapi[cli])
- Add nipyapi.ci module with 9 CI convenience functions
- CLI features: JSON output, log capture, error wrapping, CI auto-detect
- Add docs/cli_quickstart.md for quick testing

Author: Chaffelson

docs/cli_quickstart.md

@@ -0,0 +1,46 @@
+# nipyapi CLI Quickstart
+
+## Prerequisites
+
+```bash
+brew install uv
+```
+
+## Install
+
+```bash
+uv pip install "nipyapi[cli] @ git+https://github.com/Chaffelson/nipyapi.git@feature/cli"
+```
+
+## Configure
+
+```bash
+export NIFI_API_ENDPOINT="https://your-nifi-host/nifi-api"
+export NIFI_BEARER_TOKEN="your-jwt-token"
+```
+
+## Explore
+
+```bash
+# Check connection
+nipyapi system get_nifi_version_info
+
+# List registry clients
+nipyapi versioning list_registry_clients
+
+# Get a specific registry client by name
+nipyapi versioning get_registry_client "ConnectorFlowRegistryClient"
+```
+
+## Deploy a Flow
+
+```bash
+# Get the registry client ID
+REGISTRY_ID=$(nipyapi versioning get_registry_client "ConnectorFlowRegistryClient" | jq -r '.id')
+
+# Deploy a flow from the registry
+nipyapi ci deploy_flow \
+  --registry_client_id "$REGISTRY_ID" \
+  --bucket "connectors" \
+  --flow "postgresql"
+```

nipyapi/ci/__init__.py

@@ -0,0 +1,38 @@
+"""
+CI convenience functions for NiFi flow management.
+
+These functions wrap nipyapi operations with:
+- Environment variable support for CI/CD platforms
+- Sensible defaults
+- Simplified interfaces
+
+They return plain dicts and raise exceptions on error.
+The CLI handles output formatting, logging capture, and exit codes.
+
+Example:
+    nipyapi ci ensure_registry --repo owner/repo
+    nipyapi ci deploy_flow --bucket flows --flow my-flow
+    nipyapi ci start_flow
+"""
+
+from .change_version import change_version
+from .cleanup import cleanup
+from .configure_params import configure_params
+from .deploy_flow import deploy_flow
+from .ensure_registry import ensure_registry
+from .get_status import get_status
+from .revert_flow import revert_flow
+from .start_flow import start_flow
+from .stop_flow import stop_flow
+
+__all__ = [
+    "ensure_registry",
+    "deploy_flow",
+    "start_flow",
+    "stop_flow",
+    "get_status",
+    "configure_params",
+    "change_version",
+    "revert_flow",
+    "cleanup",
+]

nipyapi/ci/change_version.py

@@ -0,0 +1,86 @@
+"""
+change_version - change the version of a deployed flow.
+"""
+
+import logging
+import os
+from typing import Optional
+
+import nipyapi
+
+log = logging.getLogger(__name__)
+
+
+def change_version(
+    process_group_id: Optional[str] = None,
+    target_version: Optional[str] = None,
+    branch: Optional[str] = None,
+) -> dict:
+    """
+    Change the version of a deployed flow.
+
+    Args:
+        process_group_id: ID of the process group. Env: NIFI_PROCESS_GROUP_ID
+        target_version: Version to change to (commit SHA, tag, branch).
+                       Env: NIFI_TARGET_VERSION. If None, changes to latest.
+        branch: Branch to use. Env: NIFI_FLOW_BRANCH
+
+    Returns:
+        dict with previous_version, new_version, version_state
+
+    Raises:
+        ValueError: Missing required parameters or not under version control
+    """
+    process_group_id = process_group_id or os.environ.get("NIFI_PROCESS_GROUP_ID")
+    target_version = target_version or os.environ.get("NIFI_TARGET_VERSION") or None
+    branch = branch or os.environ.get("NIFI_FLOW_BRANCH") or None
+
+    if not process_group_id:
+        raise ValueError("process_group_id is required (or set NIFI_PROCESS_GROUP_ID)")
+
+    nipyapi.profiles.switch("env")
+
+    log.info("Changing version for: %s", process_group_id)
+
+    # Get process group
+    process_group = nipyapi.canvas.get_process_group(process_group_id, "id")
+    if not process_group:
+        raise ValueError(f"Process group not found: {process_group_id}")
+
+    # Get current version info
+    version_info = nipyapi.versioning.get_version_info(process_group)
+    if not version_info or not version_info.version_control_information:
+        raise ValueError(
+            f"Process group '{process_group.component.name}' is not under version control"
+        )
+
+    current_vci = version_info.version_control_information
+    previous_version = current_vci.version
+
+    log.debug("Current version: %s (%s)", previous_version, current_vci.state)
+
+    if target_version:
+        log.info("Target version: %s", target_version)
+    else:
+        log.info("Target version: latest")
+
+    # Change version
+    nipyapi.versioning.update_git_flow_ver(
+        process_group=process_group,
+        target_version=target_version,
+        branch=branch,
+    )
+
+    # Get updated version info
+    updated_pg = nipyapi.canvas.get_process_group(process_group_id, "id")
+    updated_vci = nipyapi.versioning.get_version_info(updated_pg)
+    new_version = updated_vci.version_control_information.version
+    new_state = updated_vci.version_control_information.state
+
+    log.info("Changed from %s to %s (%s)", previous_version[:12], new_version[:12], new_state)
+
+    return {
+        "previous_version": previous_version,
+        "new_version": new_version,
+        "version_state": new_state,
+    }

nipyapi/ci/cleanup.py

@@ -0,0 +1,96 @@
+# pylint: disable=broad-exception-caught,duplicate-code
+"""
+cleanup - stop and delete a deployed process group.
+"""
+
+import logging
+import os
+from typing import Optional
+
+import nipyapi
+
+log = logging.getLogger(__name__)
+
+
+def cleanup(
+    process_group_id: Optional[str] = None,
+    force: bool = True,
+    delete_parameter_context: bool = True,
+) -> dict:
+    """
+    Stop and delete a process group, optionally including its parameter context.
+
+    Args:
+        process_group_id: ID of the process group. Env: NIFI_PROCESS_GROUP_ID
+        force: Force deletion even with running components (default: True)
+        delete_parameter_context: Delete parameter context too (default: True)
+
+    Returns:
+        dict with deleted, deleted_name
+
+    Raises:
+        ValueError: Missing required parameters
+    """
+    process_group_id = process_group_id or os.environ.get("NIFI_PROCESS_GROUP_ID")
+
+    if not process_group_id:
+        raise ValueError("process_group_id is required (or set NIFI_PROCESS_GROUP_ID)")
+
+    nipyapi.profiles.switch("env")
+
+    log.info("Cleaning up process group: %s", process_group_id)
+
+    # Get process group
+    try:
+        process_group = nipyapi.canvas.get_process_group(process_group_id, "id")
+    except nipyapi.nifi.rest.ApiException as e:
+        if e.status == 404:
+            log.info("Process group not found - may already be deleted")
+            return {
+                "deleted": "false",
+                "deleted_name": "",
+                "message": "Process group not found",
+            }
+        raise
+
+    if not process_group:
+        return {
+            "deleted": "false",
+            "deleted_name": "",
+            "message": "Process group not found",
+        }
+
+    pg_name = process_group.component.name
+    log.debug("Found process group: %s", pg_name)
+
+    # Get parameter context reference before deletion
+    param_ctx_id = None
+    param_ctx_name = None
+    if delete_parameter_context and process_group.component.parameter_context:
+        param_ctx_id = process_group.component.parameter_context.id
+        param_ctx_name = process_group.component.parameter_context.component.name
+        log.debug("Found parameter context: %s", param_ctx_name)
+
+    # Stop first
+    log.debug("Stopping process group...")
+    nipyapi.canvas.schedule_process_group(process_group_id, scheduled=False)
+
+    # Delete process group
+    log.debug("Deleting process group...")
+    nipyapi.canvas.delete_process_group(process_group, force=force)
+    log.info("Deleted process group: %s", pg_name)
+
+    # Delete parameter context if requested
+    if delete_parameter_context and param_ctx_id:
+        try:
+            log.debug("Deleting parameter context: %s", param_ctx_name)
+            ctx = nipyapi.parameters.get_parameter_context(param_ctx_id, identifier_type="id")
+            nipyapi.parameters.delete_parameter_context(ctx)
+            log.info("Deleted parameter context: %s", param_ctx_name)
+        except Exception as e:
+            log.warning("Could not delete parameter context: %s", e)
+
+    return {
+        "deleted": "true",
+        "deleted_name": pg_name,
+    }

nipyapi/ci/configure_params.py

@@ -0,0 +1,98 @@
+"""
+configure_params - set parameter values on a process group.
+"""
+
+import json
+import logging
+import os
+from typing import Any, Dict, Optional, Union
+
+import nipyapi
+
+log = logging.getLogger(__name__)
+
+
+def configure_params(
+    process_group_id: Optional[str] = None,
+    parameters: Optional[Union[str, Dict[str, Any]]] = None,
+) -> dict:
+    """
+    Configure parameters on a process group's parameter context.
+
+    Args:
+        process_group_id: ID of the process group. Env: NIFI_PROCESS_GROUP_ID
+        parameters: JSON string or dict of parameter name -> value pairs.
+                   Env: NIFI_PARAMETERS
+
+    Returns:
+        dict with parameters_updated, parameters_count, context_name
+
+    Raises:
+        ValueError: Missing required parameters or invalid JSON
+    """
+    process_group_id = process_group_id or os.environ.get("NIFI_PROCESS_GROUP_ID")
+    parameters = parameters or os.environ.get("NIFI_PARAMETERS")
+
+    if not process_group_id:
+        raise ValueError("process_group_id is required (or set NIFI_PROCESS_GROUP_ID)")
+    if not parameters:
+        raise ValueError("parameters is required (or set NIFI_PARAMETERS)")
+
+    # Parse JSON string if provided
+    if isinstance(parameters, str):
+        try:
+            parameters = json.loads(parameters)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in parameters: {e}") from e
+
+    if not isinstance(parameters, dict):
+        raise ValueError("parameters must be a JSON object with key-value pairs")
+
+    nipyapi.profiles.switch("env")
+
+    log.info("Configuring %d parameter(s) on %s", len(parameters), process_group_id)
+
+    # Get process group
+    pg = nipyapi.canvas.get_process_group(process_group_id, identifier_type="id")
+    if not pg:
+        raise ValueError(f"Process group not found: {process_group_id}")
+
+    log.debug("Found process group: %s", pg.component.name)
+
+    # Check for parameter context
+    if not pg.component.parameter_context:
+        raise ValueError(
+            f"Process group '{pg.component.name}' has no parameter context. "
+            "Attach a parameter context before configuring parameters."
+        )
+
+    ctx_ref = pg.component.parameter_context
+    ctx_name = ctx_ref.component.name
+    log.debug("Parameter context: %s", ctx_name)
+
+    # Get full context
+    ctx = nipyapi.parameters.get_parameter_context(ctx_ref.id, identifier_type="id")
+
+    # Prepare parameters
+    prepared_params = []
+    for param_name, param_value in parameters.items():
+        param = nipyapi.parameters.prepare_parameter(
+            name=param_name,
+            value=str(param_value),
+            sensitive=False,
+        )
+        prepared_params.append(param)
+        log.debug("Setting %s = %s", param_name, param_value)
+
+    # Apply parameters
+    ctx.component.parameters = prepared_params
+    nipyapi.parameters.update_parameter_context(ctx)
+
+    updated_params = list(parameters.keys())
+    log.info("Updated %d parameter(s): %s", len(updated_params), ", ".join(updated_params))
+
+    return {
+        "parameters_updated": ",".join(updated_params),
+        "parameters_count": str(len(updated_params)),
+        "context_name": ctx_name,
+    }