Command-Line Interface

NiPyAPI provides a command-line interface (CLI) for automating Apache NiFi operations. The CLI exposes all nipyapi modules and functions, making it suitable for shell scripting, CI/CD pipelines, and interactive exploration.

Installation

With pip (standard installation):

pip install "nipyapi[cli]"

With uv (faster installation):

uv pip install "nipyapi[cli]"

Without installation (ephemeral):

uvx --from "nipyapi[cli]" nipyapi system get_nifi_version_info

From source (development):

pip install "nipyapi[cli] @ git+https://github.com/Chaffelson/nipyapi.git@feature/cli"

Configuration

The CLI auto-detects configuration using this priority:

--profile argument (explicit profile selection)
Environment variables (if NIFI_API_ENDPOINT is set)
NIPYAPI_PROFILE env var (selects named profile from profiles file)
First profile in ~/.nipyapi/profiles.yml
No configuration (commands will fail with helpful error)

Environment Variables

For CI/CD environments, configure using environment variables:

# Required - NiFi connection
export NIFI_API_ENDPOINT="https://nifi.example.com/nifi-api"

# Authentication (choose one method)
export NIFI_BEARER_TOKEN="eyJhbGciOiJSUzI1NiI..."  # JWT token
# OR
export NIFI_USERNAME="admin"
export NIFI_PASSWORD="password"

# Optional - SSL/TLS
export NIFI_VERIFY_SSL="true"  # Set to "false" for self-signed certs

User Profiles File

For interactive use, create ~/.nipyapi/profiles.yml:

production:
  nifi_url: "https://nifi.production.example.com/nifi-api"
  nifi_bearer_token: "eyJhbGciOiJSUzI1NiI..."
  nifi_verify_ssl: true

development:
  nifi_url: "https://localhost:9443/nifi-api"
  nifi_user: "admin"
  nifi_pass: "password"
  nifi_verify_ssl: false

See Environment Profiles with NiPyAPI for complete configuration options.

Profile Selection

Use the --profile option to explicitly select a profile:

# Explicit profile selection (recommended for multi-profile setups)
nipyapi --profile production system get_nifi_version_info
nipyapi --profile development ci get_status

# The --profile option must come before the subcommand
nipyapi --profile <profile_name> <module> <command> [args]

Discovering Commands

The CLI is built on Google Fire, which provides built-in help and introspection:

# List all available modules
nipyapi --help

# List all functions in a module
nipyapi canvas --help
nipyapi versioning --help

# Get help for a specific function (shows parameters and docstring)
nipyapi canvas get_process_group --help
nipyapi ci deploy_flow --help

# Show function signature
nipyapi versioning list_registry_clients -- --help

Use --help at any level to explore available commands and their parameters.

Available Modules

The CLI exposes nipyapi’s high-level helper modules, which provide user-friendly abstractions over the NiFi and Registry APIs. Use nipyapi <module> --help to see the complete list of functions for any module.

Note: The low-level nipyapi.nifi and nipyapi.registry API clients are not exposed via CLI as they require complex object inputs better suited for Python usage. See API Reference for the complete API including low-level clients.

For full API documentation including all parameters, types, and detailed descriptions, see API Reference.

ci - CI/CD Operations

High-level operations for flow deployment and management in CI/CD pipelines. See CI Operations for complete documentation of all CI functions.

nipyapi ci --help                    # List all CI operations
nipyapi ci deploy_flow --help        # Help for specific operation

canvas - Process Groups and Processors

Core NiFi canvas operations: process groups, processors, connections, ports.

nipyapi canvas --help                # List all canvas functions
nipyapi canvas get_root_pg_id
nipyapi canvas list_all_process_groups
nipyapi canvas get_process_group PG_ID id

See Canvas for full API reference.

versioning - Flow Registry

Flow versioning, registry clients, and version control operations.

nipyapi versioning --help            # List all versioning functions
nipyapi versioning list_registry_clients
nipyapi versioning get_version_info PROCESS_GROUP

See Versioning for full API reference.

parameters - Parameter Contexts

Parameter context management, inheritance, and assets.

nipyapi parameters --help            # List all parameter functions
nipyapi parameters list_all_parameter_contexts
nipyapi parameters get_parameter_context CONTEXT_ID id

See Parameters for full API reference.

security - Users and Policies

User, group, and access policy management.

nipyapi security --help              # List all security functions
nipyapi security list_service_users

See Security for full API reference.

system - Cluster Information

System diagnostics, cluster status, and NiFi information.

nipyapi system --help                # List all system functions
nipyapi system get_nifi_version_info

See System for full API reference.

layout - Canvas Layout

Utilities for arranging and organizing components on the canvas.

nipyapi layout --help                # List all layout functions
nipyapi layout align_pg_grid PG_ID --sort_by_name=True

config - Configuration

Access to nipyapi configuration settings.

nipyapi config --help                # List config attributes

See Config for full API reference.

profiles - Profile Management

Profile loading and switching functions.

nipyapi profiles --help              # List profile functions

See Profiles for full API reference.

utils - Utilities

Helper functions for common operations.

nipyapi utils --help                 # List utility functions

See Utils for full API reference.

Output Formatting

The CLI automatically formats output based on the execution environment:

JSON (default)

Structured JSON output for programmatic parsing.

nipyapi system get_nifi_version_info
# Output: {"niFi_version": "2.0.0", ...}

GitHub Actions

Auto-detected when GITHUB_ACTIONS env var is set. Outputs key=value pairs compatible with $GITHUB_OUTPUT. Keys are converted from snake_case to kebab-case.

# In GitHub Actions workflow
nipyapi ci deploy_flow ... >> $GITHUB_OUTPUT
# Output: process-group-id=abc-123

GitLab CI (dotenv)

Auto-detected when GITLAB_CI env var is set. Outputs KEY=VALUE pairs for dotenv artifact format. Keys are converted to UPPER_SNAKE_CASE.

# In GitLab CI job
nipyapi ci deploy_flow ... > deploy.env
# Output: PROCESS_GROUP_ID=abc-123

Manual Override

Force a specific format using NIFI_OUTPUT_FORMAT:

export NIFI_OUTPUT_FORMAT=json    # JSON (default)
export NIFI_OUTPUT_FORMAT=github  # GitHub Actions format
export NIFI_OUTPUT_FORMAT=dotenv  # GitLab dotenv format

Log Level Control

Control log verbosity using NIFI_LOG_LEVEL:

export NIFI_LOG_LEVEL=WARNING  # Default - only warnings and errors
export NIFI_LOG_LEVEL=ERROR    # Only errors
export NIFI_LOG_LEVEL=INFO     # Normal operational info
export NIFI_LOG_LEVEL=DEBUG    # Full debug output

On error, logs are included in the output by default. Disable with:

export NIFI_LOG_ON_ERROR=false

Usage Examples

Test connectivity:

nipyapi system get_nifi_version_info

List all process groups:

nipyapi canvas list_all_process_groups

Get process group by ID:

nipyapi canvas get_process_group "abc-123-def" id

Get registry client by name:

nipyapi versioning get_registry_client "MyRegistryClient"

Deploy a flow from registry:

nipyapi ci deploy_flow \
    --registry_client_id "$REGISTRY_ID" \
    --bucket "connectors" \
    --flow "postgresql"

Parse JSON output with jq:

# Get registry client ID by name
REGISTRY_ID=$(nipyapi versioning get_registry_client "MyClient" | jq -r '.id')

# List process group names
nipyapi canvas list_all_process_groups | jq -r '.[].component.name'

Error Handling

The CLI returns structured error responses and uses non-zero exit codes for failures.

Exception errors (Python exceptions during execution):

{
  "success": false,
  "error": "Process group not found: invalid-id",
  "error_type": "ValueError",
  "command": "get_process_group",
  "logs": ["nipyapi.canvas: Fetching process group..."]
}

Operational errors (command completed but operation failed):

CI functions include an error or errors field when an operation fails. The CLI detects these fields and exits with code 1.

{
  "verified": "false",
  "failed_count": 2,
  "error": "Verification failed for: DBCPConnectionPool, ExecuteSQL"
}

Exit codes:

0: Success (no error/errors key in result)
1: Error (exception raised, or result contains error/errors key)

Error Field Convention

When writing custom CI functions or extending nipyapi, follow this convention:

Include an error key (string) when an operation fails
Use errors key (string) for multiple error messages (pipe-separated)
Do NOT include error/errors keys on success

This ensures the CLI exits with the correct code for scripting:

# Script can rely on exit code
if nipyapi ci verify_config --process_group_id "$PG_ID"; then
    nipyapi ci start_flow --process_group_id "$PG_ID"
else
    echo "Verification failed, not starting flow"
    exit 1
fi

Cross-References

For CI/CD operations: See CI Operations

For profile configuration: See Environment Profiles with NiPyAPI

For security setup: See Security with NiPyAPI

For API reference: See API Reference