### Setup and installation targets

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/contributing.md

Commands for managing development environments and cleaning build artifacts.

```shell
make dev-install      # Install with dev dependencies (uses uv if available, pip otherwise)
make docs-install     # Install documentation dependencies
make clean            # Remove build, pyc, and temp artifacts
make clean-all        # Nuclear clean: removes ALL including generated code
```

--------------------------------

### Install and Start NiFi via Docker

Source: https://github.com/chaffelson/nipyapi/blob/main/README.rst

Commands to clone the repository, install development dependencies, and launch a NiFi environment using the provided Makefile.

```bash
git clone https://github.com/Chaffelson/nipyapi.git
cd nipyapi

# Install NiPyAPI in development mode
pip install -e ".[dev]"

# Start complete NiFi environment (this may take a few minutes)
make certs && make up NIPYAPI_PROFILE=single-user && make wait-ready NIPYAPI_PROFILE=single-user
```

--------------------------------

### Install and Run NiFi with Docker

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/readme.md

Installs NiPyAPI in development mode and starts a complete NiFi environment using Docker. This is recommended for new users to test the connection.

```bash
# Clone the repository (includes Docker profiles and Makefile)
git clone https://github.com/Chaffelson/nipyapi.git
cd nipyapi

# Install NiPyAPI in development mode
pip install -e ".[dev]"

# Start complete NiFi environment (this may take a few minutes)
make certs && make up NIPYAPI_PROFILE=single-user && make wait-ready NIPYAPI_PROFILE=single-user

# Test the connection
python3 -c "
import nipyapi
nipyapi.profiles.switch('single-user')
version = nipyapi.system.get_nifi_version_info()
print(f'✓ Connected to NiFi {version}')
"
```

--------------------------------

### OIDC Authentication Setup Command

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/migration.md

Command to start the sandbox environment with OIDC profile to discover the application UUID. This is the first step for OIDC authentication setup.

```shell
# 1. Use sandbox to discover your OIDC application UUID
make sandbox NIPYAPI_PROFILE=secure-oidc
```

--------------------------------

### Docker Environment Setup and Workflow

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/migration.md

Commands for setting up the Docker environment, starting NiFi, and waiting for it to be ready using a specific profile. This workflow integrates with Python code using the same profile.

```shell
# One-command environment setup
make certs && make up NIPYAPI_PROFILE=secure-ldap && make wait-ready NIPYAPI_PROFILE=secure-ldap

# Python code matches the environment
nipyapi.profiles.switch('secure-ldap')

# Testing with the same profile
make test NIPYAPI_PROFILE=secure-ldap
```

--------------------------------

### Verify Installation

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/devnotes.md

Command to test the package installation in a clean environment.

```shell
# Test installation in clean environment
pip install nipyapi=={version}
python -c "import nipyapi; print(nipyapi.__version__)"
```

--------------------------------

### Start NiFi Infrastructure with a Profile

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/profiles.md

Use make commands to generate certificates, start the Docker environment, and wait for it to be ready with a specified profile.

```console
make certs
make up NIPYAPI_PROFILE=single-user
make wait-ready NIPYAPI_PROFILE=single-user
```

--------------------------------

### Install NiPyAPI with CLI support using uv

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/cli.md

Faster installation using the uv package manager. Requires uv to be installed.

```console
uv pip install "nipyapi[cli]"
```

--------------------------------

### List Versioning Functions

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/cli.md

Lists all available functions for flow versioning and registry operations. Examples include listing registry clients and getting version information.

```console
nipyapi versioning --help
```

```console
nipyapi versioning list_registry_clients
```

```console
nipyapi versioning get_version_info PROCESS_GROUP
```

--------------------------------

### Install NiPyAPI

Source: https://github.com/chaffelson/nipyapi/blob/main/AGENTS.md

Install the NiPyAPI library with optional CLI support. Recommended for most users.

```bash
uv pip install "nipyapi[cli]"
```

```bash
pip install nipyapi
```

--------------------------------

### Start Flow

Source: https://context7.com/chaffelson/nipyapi/llms.txt

Starts a deployed process group by enabling controllers and starting processors.

```APIDOC
## POST /nifi/api/ci/start_flow

### Description
Starts a deployed process group by enabling controller services and starting processors. It can optionally skip enabling controller services if they are already enabled.

### Method
POST

### Endpoint
/nifi/api/ci/start_flow

### Parameters
#### Query Parameters
- **process_group_id** (string) - Required if not using environment variables - The ID of the process group to start.
- **enable_controllers** (boolean) - Optional - Whether to enable controller services before starting processors. Defaults to `true`.

### Request Example
```json
{
  "process_group_id": "pg-uuid-here",
  "enable_controllers": true
}
```

### Response
#### Success Response (200)
- **process_group_name** (string) - The name of the process group that was started.

#### Response Example
```json
{
  "process_group_name": "data-pipeline"
}
```
```

--------------------------------

### Install and Configure NiPyAPI CLI

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/readme.md

Installs the CLI extras and demonstrates environment variable configuration and command execution.

```bash
pip install "nipyapi[cli]"

# Set connection via environment variables
export NIFI_API_ENDPOINT=https://your-nifi-host.com/nifi-api
export NIFI_USERNAME=your_username
export NIFI_PASSWORD=your_password

# Or use a profile
nipyapi --profile single-user system get_nifi_version_info

# CI/CD operations
nipyapi ci deploy_flow --bucket flows --flow my-flow
nipyapi ci start_flow --process_group_id <id>
nipyapi ci get_status --process_group_id <id>
```

--------------------------------

### Install NiPyAPI from Source Archive

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/installation.md

Manual installation steps using a downloaded source tarball.

```console
# Download the latest source
$ curl -OL https://github.com/Chaffelson/nipyapi/tarball/main
$ tar -xzf main
$ cd Chaffelson-nipyapi-*

# Install using pip (recommended)
$ pip install .

# Or build and install manually
$ python -m build
$ pip install dist/*.whl
```

--------------------------------

### Install NiPyAPI via PyPI

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/installation.md

Standard installation method for the most recent stable release.

```console
$ pip install nipyapi
```

--------------------------------

### NiPyAPI CLI Examples

Source: https://github.com/chaffelson/nipyapi/blob/main/AGENTS.md

Examples of using the NiPyAPI command-line interface for common NiFi operations.

```bash
nipyapi ci ensure_registry --name my-registry --uri https://github.com/org/repo
```

```bash
nipyapi ci deploy_flow --registry_client my-registry --bucket flows --flow my-flow
```

```bash
nipyapi ci start_flow --pg_id <process-group-id>
```

```bash
nipyapi canvas list_all_process_groups
```

--------------------------------

### Install NiPyAPI for Development

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/installation.md

Methods for installing from the repository or source for development purposes.

```console
# Clone the repository
$ git clone https://github.com/Chaffelson/nipyapi.git
$ cd nipyapi

# Install in development mode with all dependencies
$ pip install -e ".[dev,docs]"
```

```console
$ pip install git+https://github.com/Chaffelson/nipyapi.git@main
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/chaffelson/nipyapi/blob/main/AGENTS.md

Installs the project in editable mode with development dependencies. Use this instead of bare `pip install -e .[dev]` to ensure proper Zsh bracket quoting.

```bash
make dev-install
```

--------------------------------

### Run FDLC example scripts

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/profiles.md

Commands to execute the Flow Development Life Cycle example in interactive or automated modes.

```console
# Interactive mode (recommended)
python -i examples/fdlc.py
>>> step_1_setup_environments()
>>> step_2_create_dev_flow()
>>> # ... continue with remaining steps

# Auto run (complete demo)
python examples/fdlc.py --auto
```

--------------------------------

### Install NiPyAPI with Development and Docs Dependencies

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/installation.md

Use this command to install NiPyAPI in a development environment, including optional dependencies for development and documentation.

```console
pip install -e ".[dev,docs]"
```

--------------------------------

### Start Flow

Source: https://context7.com/chaffelson/nipyapi/llms.txt

Starts a process group, optionally enabling controller services first.

```python
import nipyapi.ci

# Start flow with controller services
result = nipyapi.ci.start_flow(
    process_group_id='pg-uuid-here',
    enable_controllers=True  # Enable controller services first (default)
)
print(f"Started: {result['process_group_name']}")

# Start without enabling controllers (if already enabled)
result = nipyapi.ci.start_flow(
    process_group_id='pg-uuid-here',
    enable_controllers=False
)

# Environment variable usage
# Set: NIFI_PROCESS_GROUP_ID
result = nipyapi.ci.start_flow()
```

--------------------------------

### Start Docker Services

Source: https://github.com/chaffelson/nipyapi/blob/main/AGENTS.md

Starts the Docker services required for the nipyapi environment. Specify the profile to use.

```bash
make up NIPYAPI_PROFILE=single-user
```

--------------------------------

### Install NiPyAPI from source with CLI support

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/cli.md

Install the CLI from a specific Git branch for development or testing. Requires Git and pip.

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

--------------------------------

### Install Development and Documentation Dependencies

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/dependencies.md

Use this command to set up a complete development environment including all optional dependencies.

```console
$ pip install -e ".[dev,docs]"
```

--------------------------------

### Contribute to NiPyAPI: Development Setup

Source: https://github.com/chaffelson/nipyapi/blob/main/AGENTS.md

Clone the NiPyAPI repository and set up the development environment using make commands.

```bash
git clone https://github.com/Chaffelson/nipyapi.git && cd nipyapi
make dev-install    # Uses uv if available, pip otherwise
make help           # See all available targets
```

```bash
# Important:
# Always activate venv first: source .venv/bin/activate before running Python/make commands
# Prefer make commands: Check `make help` for available targets before using generic tooling (pip, pytest, sphinx, etc.)
```

--------------------------------

### GET /canvas/process-groups

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/core_modules/canvas.md

Retrieves a flattened list of all Process Groups on the canvas starting from a specified root.

```APIDOC
## GET /canvas/process-groups

### Description
Returns a flattened list of all Process Groups on the canvas. This command traverses the entire canvas, unlike standard API calls that only return the first layer.

### Parameters
#### Query Parameters
- **pg_id** (str) - Optional - The UUID of the Process Group to start from, defaults to the Canvas root.

### Response
#### Success Response (200)
- **list[ProcessGroupEntity]** - A list of all process groups found.
```

--------------------------------

### Quick start CI deployment

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/ci.md

Basic workflow for configuring a NiFi connection, setting up a registry client, and deploying a flow using environment variables.

```console
# 1. Configure NiFi connection
export NIFI_API_ENDPOINT="https://nifi.example.com/nifi-api"
export NIFI_BEARER_TOKEN="your-jwt-token"

# 2. Set up registry client
export GH_REGISTRY_TOKEN="ghp_xxxx"
nipyapi ci ensure_registry --repo owner/repo

# 3. Deploy a flow
nipyapi ci deploy_flow --bucket connectors --flow postgresql

# 4. Start the flow
nipyapi ci start_flow --process_group_id $PROCESS_GROUP_ID
```

--------------------------------

### Get NAR Details

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/extensions.md

Retrieve detailed information about an installed NAR, including its component types.

```python
import nipyapi

# Get NAR with full details
details = nipyapi.extensions.get_nar_details(nar_id)

print("Processor types:")
for proc_type in details.processor_types:
    print(f"  - {proc_type.type}")

print("Controller service types:")
for cs_type in details.controller_service_types:
    print(f"  - {cs_type.type}")
```

--------------------------------

### Set up local development environment

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/contributing.md

Commands to create a virtual environment and install development dependencies using either venv or uv.

```shell
# using venv
$ python -m venv .venv && source .venv/bin/activate
$ cd nipyapi/
$ make dev-install  # uses uv if available, falls back to pip

# or using uv (faster)
$ uv venv .venv && source .venv/bin/activate
$ make dev-install
```

--------------------------------

### Get Processor Initialization Status

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/core_modules/extensions.md

Retrieves the initialization status of a processor, particularly useful for custom NARs that require post-creation setup.

```APIDOC
## GET /api/extensions/processor/{processor}/init-status

### Description
Get the initialization status of a processor from a custom NAR.
Python processors and other extension processors may require initialization time after being created (e.g., setting up a virtual environment).

### Method
GET

### Endpoint
/api/extensions/processor/{processor}/init-status

### Parameters
#### Path Parameters
- **processor** (ProcessorEntity or str) - Required - ProcessorEntity or processor ID string

### Response
#### Success Response (200)
- **status object** (dict) - Contains:
  - status (str): One of ‘initializing’, ‘downloading_dependencies’, ‘dependency_failed’, ‘ready’, ‘missing_nar’, or ‘error’
  - is_ready (bool): True if processor is fully initialized
  - has_properties (bool): True if properties are loaded
  - validation_status (str): The processor’s validation_status field
  - validation_errors (list[str]): List of validation error strings
  - init_message (str): Human-readable description of current state
```

--------------------------------

### Legacy 0.x Manual Configuration

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/migration.md

Deprecated manual setup method from 0.x; do not use in 1.x.

```python
# 0.x: Complex manual setup (DO NOT USE in 1.x)
import nipyapi
nipyapi.config.nifi_config.ssl_ca_cert = nipyapi.config.default_ssl_context["ca_file"]
nipyapi.utils.set_endpoint("https://localhost:8443/nifi-api", ssl=True, login=True,
                          username="nobel", password="supersecret1!")
```

--------------------------------

### Development Environment Setup (Self-signed certs)

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/migration.md

Quick setup for development and testing using self-signed certificates. SSL warnings are suppressed for convenience.

```shell
# Quick setup for learning and testing
make certs
make up NIPYAPI_PROFILE=single-user
nipyapi.profiles.switch('single-user')

# SSL warnings are safely suppressed in development
nipyapi.config.disable_insecure_request_warnings = True
```

--------------------------------

### Get NAR Summaries

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/nifi_apis/controller_api.md

Retrieves summary information for installed NARs. This method makes a synchronous HTTP request and returns the response data directly.

```APIDOC
## GET /nars/summaries

### Description
Retrieves summary information for installed NARs.

### Method
GET

### Endpoint
/nars/summaries

### Response
#### Success Response (200)
- **response** (NarSummariesEntity) - The response data.
```

--------------------------------

### Get NAR Details

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/nifi_apis/controller_api.md

Retrieves the component types available from the installed NARs. This method makes a synchronous HTTP request and returns detailed response information.

```APIDOC
## GET /nars/{id}/details

### Description
Retrieves the component types available from the installed NARs.

### Method
GET

### Endpoint
/nars/{id}/details

### Parameters
#### Path Parameters
- **id** (str) - Required - The id of the NAR.

### Response
#### Success Response (200)
- **response** (NarDetailsEntity) - Response data with HTTP details.
- **status_code** (int) - HTTP status code.
- **headers** (dict) - HTTP headers.
```

--------------------------------

### Make Commands for 1.x Approach

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/migration.md

Commands to set up and test the 1.x environment using make targets with a specified profile.

```bash
make up NIPYAPI_PROFILE=secure-ldap
make wait-ready NIPYAPI_PROFILE=secure-ldap
make test NIPYAPI_PROFILE=secure-ldap
```

--------------------------------

### Development and Test Commands

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/migration.md

Commands for setting up certificates, starting the environment, and running tests.

```bash
make certs && make up NIPYAPI_PROFILE=single-user
```

```bash
make test NIPYAPI_PROFILE=single-user
```

--------------------------------

### Use NiPyAPI CLI with a Profile

Source: https://github.com/chaffelson/nipyapi/blob/main/README.rst

Execute NiPyAPI commands via the CLI using a specified profile. This example shows how to get NiFi version information.

```bash
nipyapi --profile single-user system get_nifi_version_info
```

--------------------------------

### Create sandbox environment

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/profiles.md

Use make to initialize a development environment with a specific profile.

```console
$ make sandbox NIPYAPI_PROFILE=single-user
```

--------------------------------

### Get NAR Summary with HTTP Info

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/nifi_apis/controller_api.md

Retrieves summary information for installed NARs and returns detailed response information including status code, headers, and other metadata.

```APIDOC
## GET /nars/summaries/http-info

### Description
Retrieves summary information for installed NARs and returns detailed response information.

### Method
GET

### Endpoint
/nars/summaries/http-info

### Response
#### Success Response (200)
- **response** (NarSummariesEntity) - Response data with HTTP details.
- **status_code** (int) - HTTP status code.
- **headers** (dict) - HTTP headers.
```

--------------------------------

### Delete NAR extensions via CLI

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/core_modules/ci.md

Examples of removing installed NAR extensions using either a unique identifier or Maven coordinates, with an option to force deletion.

```default
# Delete by identifier
nipyapi ci delete_nar --identifier abc-123-def

# Delete by coordinate
nipyapi ci delete_nar --group com.example --artifact my-nar --version 1.0.0

# Force delete
nipyapi ci delete_nar --identifier abc-123-def --force
```

--------------------------------

### Select CLI profiles

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/profiles.md

Examples of using the --profile option with various CLI commands.

```console
# Explicit profile selection (recommended for multi-profile setups)
nipyapi --profile my_runtime ci get_status PG_ID
nipyapi --profile prod_runtime system get_nifi_version_info
nipyapi --profile dchaffelson_az1_runtime canvas list_all_process_groups

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

--------------------------------

### Build and documentation targets

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/contributing.md

Commands for packaging the project and generating documentation.

```shell
make dist             # Build wheel and source distribution
make check-dist       # Validate distribution files
make test-dist        # Test that distribution can be imported
make docs             # Generate Sphinx documentation
```

--------------------------------

### Verify and start flow in CI pipeline

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/ci.md

Example of using nipyapi ci commands in a shell script to conditionally execute flow operations based on verification results.

```bash
# Exit code will be 1 if verification fails
if nipyapi ci verify_config --process_group_id "$PG_ID"; then
    nipyapi ci start_flow --process_group_id "$PG_ID"
else
    echo "Verification failed"
    exit 1
fi
```

--------------------------------

### Get Flow Components and Connections

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/core_modules/canvas.md

Finds all components and connections within a connected flow subgraph starting from a given component. Useful for moving or analyzing an entire flow as a unit. The function performs a breadth-first traversal.

```python
# Get the complete flow subgraph
flow = nipyapi.canvas.get_flow_components(proc1)

# Access components
for c in flow.components:
    print(c.component.name)

# Access connections (useful for transpose_flow)
nipyapi.layout.transpose_flow(
    flow.components, offset=(400, 0), connections=flow.connections
)
```

--------------------------------

### Shell Script: NiFi Workflow Setup

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/ci.md

This bash script demonstrates setting up environment variables for NiFi API connection and GitHub registry token, then ensuring a registry client exists.

```bash
#!/bin/bash
set -e

# Configuration
export NIFI_API_ENDPOINT="https://nifi.example.com/nifi-api"
export NIFI_BEARER_TOKEN="$NIFI_TOKEN"
export GH_REGISTRY_TOKEN="$GITHUB_TOKEN"

# 1. Ensure registry client exists
RESULT=$(nipyapi ci ensure_registry --repo myorg/nifi-flows)
REGISTRY_ID=$(echo "$RESULT" | jq -r '.registry_client_id')
echo "Registry client: $REGISTRY_ID"
```

--------------------------------

### Start Flow

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/core_modules/ci.md

Starts a process group by enabling its controller services and starting its processors. This is a crucial step for resuming or activating a NiFi flow.

```APIDOC
## POST /ci/start_flow

### Description
Start a process group (enable controllers, start processors).

### Method
POST

### Endpoint
/ci/start_flow

### Parameters
#### Query Parameters
- **process_group_id** (str) - Required - ID of the process group. Env: NIFI_PROCESS_GROUP_ID
- **enable_controllers** (bool) - Optional - Enable controller services first. Default: True

### Response
#### Success Response (200)
- **results** (dict) - Dictionary containing started status and process group name.

#### Response Example
```json
{
  "started": true,
  "process_group_name": "MyFlow"
}
```
```

--------------------------------

### GET /actions/{id}

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/nifi_apis/flow_api.md

Gets an action by its ID.

```APIDOC
## GET /actions/{id}

### Description
Gets an action. Note: This endpoint is subject to change as NiFi and it’s REST API evolve.

### Parameters
#### Path Parameters
- **id** (IntegerParameter) - Required - The action id.

### Response
#### Success Response (200)
- **action_entity** (ActionEntity) - The response data containing the action details.
```

--------------------------------

### Old Docker Commands (0.x)

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/migration.md

Illustrates the older method of starting the Docker environment using `docker-compose` within a profile directory.

```shell
# 0.x approach
cd resources/docker/some_profile
docker-compose up -d
```

--------------------------------

### Manage Custom Profiles

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/migration.md

Commands for setting up custom profile files.

```bash
# Copy the example as a starting point
cp examples/profiles.yml ~/.nipyapi/profiles.yml

# Edit for your environments
vim ~/.nipyapi/profiles.yml
```

--------------------------------

### GET /flows/{flow_id}

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/registry_apis/flows_api.md

Gets a flow by its unique identifier.

```APIDOC
## GET /flows/{flow_id}

### Description
Gets a flow by id.

### Method
GET

### Endpoint
/flows/{flow_id}

### Parameters
#### Path Parameters
- **flow_id** (str) - Required - The flow identifier

### Response
#### Success Response (200)
- **VersionedFlow** (object) - The flow details.
```

--------------------------------

### Complex 0.x SSL Configuration vs. Simple 1.x Profile Switch

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/migration.md

Illustrates the significant reduction in configuration complexity when migrating from 0.x manual setup to 1.x profile-based configuration.

```python
# 0.x: Complex multi-step configuration (10+ lines)
import os
import nipyapi

# Step 1: Set global SSL settings
nipyapi.config.global_ssl_verify = True
nipyapi.config.global_ssl_host_check = False  # But this affects BOTH services!
nipyapi.config.disable_insecure_request_warnings = True

# Step 2: Direct configuration (NIFI_CA_CERT no longer supported)
nipyapi.config.nifi_config.ssl_ca_cert = '/path/to/ca.pem'

# Step 4: Manually configure each service endpoint
nipyapi.utils.set_endpoint("https://localhost:8443/nifi-api", ssl=True, login=True)
# Registry SSL settings? More complex configuration needed...

# vs.

# 1.x: Simple declarative configuration (1 line)
nipyapi.profiles.switch('single-user')  # Everything configured automatically
```

--------------------------------

### GET /registry-clients

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/nifi_apis/flow_api.md

Gets the listing of available flow registry clients.

```APIDOC
## GET /registry-clients

### Description
Gets the listing of available flow registry clients.

### Method
GET

### Response
#### Success Response (200)
- **FlowRegistryClientsEntity** (object) - Response data containing flow registry clients.
```

--------------------------------

### GET /processor/{id}/status

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/nifi_apis/flow_api.md

Gets the status for a specific processor.

```APIDOC
## GET /processor/{id}/status

### Description
Gets status for a processor. Supports optional node-wise breakdown.

### Parameters
#### Path Parameters
- **id** (str) - Required - The processor id

#### Query Parameters
- **nodewise** (bool) - Optional - Whether or not to include the breakdown per node (defaults to false)
- **cluster_node_id** (str) - Optional - The id of the node where to get the status

### Response
#### Success Response (200)
- **ProcessorStatusEntity** (object) - The processor status entity.
```

--------------------------------

### GET /canvas/controller-services/{controller}/state

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/core_modules/canvas.md

Get the state for a controller service.

```APIDOC
## GET /canvas/controller-services/{controller}/state

### Description
Retrieves the current state for a given controller service.

### Method
GET

### Endpoint
/canvas/controller-services/{controller}/state

### Parameters
#### Path Parameters
- **controller** (string) - Required - The identifier (ID, name, or ControllerServiceEntity) of the controller service.
#### Query Parameters
- **greedy** (boolean) - Optional - For name lookup, true for partial match, false for exact. Defaults to true.
- **identifier_type** (string) - Optional - How to interpret string identifier: "auto" (default), "id", or "name".

### Response
#### Success Response (200)
- **componentState** (object) - An object containing the state of the controller service, including local and cluster states.

#### Response Example
{
  "componentState": {
    "componentId": "controller-service-uuid",
    "stateDescription": "Controller service is active.",
    "localState": {
      "scope": "NODE",
      "totalEntryCount": 1,
      "state": [
        {
          "key": "last_processed_id",
          "value": "12345"
        }
      ]
    },
    "clusterState": {}
  }
}
```

--------------------------------

### Configure SSL using Profiles (1.x Recommended)

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/migration.md

The recommended approach in 1.x is to use profiles, which automatically configure all SSL settings, simplifying complexity.

```python
# Use profiles with smart defaults - handles all SSL complexity
nipyapi.profiles.switch('production')  # All SSL settings configured automatically
```

--------------------------------

### GET /canvas/connections/{connectionId}

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/core_modules/canvas.md

Get a connection by ID or refresh a ConnectionEntity.

```APIDOC
## GET /canvas/connections/{connectionId}

### Description
Retrieves a specific connection by its ID or refreshes an existing ConnectionEntity.

### Method
GET

### Endpoint
/canvas/connections/{connectionId}

### Parameters
#### Path Parameters
- **connectionId** (string) - Required - The UUID of the connection to retrieve.

### Response
#### Success Response (200)
- **connection** (object) - The ConnectionEntity object representing the requested connection.

#### Response Example
{
  "connection": {
    "id": "connection-uuid-1",
    "name": "Connection 1",
    "sourceId": "processor-uuid",
    "destinationId": "queue-uuid"
  }
}
```

--------------------------------

### Check NAR Installation Status

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/extensions.md

Retrieve the installation status of a NAR file using its identifier. This helps diagnose issues where a NAR upload times out or remains in an 'Installing' state.

```python
import nipyapi

nar = nipyapi.extensions.get_nar(identifier)
print(f"State: {nar.state}")
print(f"Complete: {nar.install_complete}")
print(f"Failure: {nar.failure_message}")
```

--------------------------------

### New Docker Commands (1.x)

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/migration.md

Demonstrates the updated commands for starting and preparing the Docker environment in NiPyAPI 1.x using the `make` utility with profile support.

```shell
# 1.x approach
make up NIPYAPI_PROFILE=secure-ldap
make wait-ready NIPYAPI_PROFILE=secure-ldap
```

--------------------------------

### Python Function Docstring Example

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/contributing.md

Illustrates the Sphinx documentation format for Python functions, including an 'Example::' section for code demonstrations. Ensure a blank line after 'Example::' for correct rendering.

```python
def my_function():
    """Do something useful.

    Example::

        result = my_function()
        print(result)
    """
```

--------------------------------

### Initialize NiPyAPI and Perform Basic Operations

Source: https://github.com/chaffelson/nipyapi/blob/main/README.rst

Import the library, switch to a profile, and perform basic operations like getting the root process group ID and NiFi version. Ensure you have set up your environment or profiles before running.

```python
import nipyapi

# If using profiles (Paths A or B)
nipyapi.profiles.switch('single-user')  # or your custom profile name

# Basic operations
root_pg_id = nipyapi.canvas.get_root_pg_id()
version = nipyapi.system.get_nifi_version_info()
process_groups = nipyapi.canvas.list_all_process_groups()

print(f"Connected to NiFi {version}")
print(f"Root Process Group: {root_pg_id}")
print(f"Found {len(process_groups)} process groups")
```

--------------------------------

### Start Flow

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/index.md

Use this function to start a flow. Requires the flow ID.

```python
nipyapi.ci.start_flow(flow_id='12345')
```

--------------------------------

### Replace Manual Configuration

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/migration.md

Transition from manual configuration to profile switching.

```python
# Before (0.x) - Complex setup
import nipyapi
nipyapi.config.nifi_config.ssl_ca_cert = "/path/to/ca.pem"
nipyapi.utils.set_endpoint("https://nifi.com/nifi-api", ssl=True, login=True,
                          username="user", password="pass")
# ... 10+ more configuration lines ...

# After (1.x) - Simple profile switch
import nipyapi
nipyapi.profiles.switch('production')

# Your existing business logic stays the same
flows = nipyapi.canvas.list_all_process_groups()
about = nipyapi.system.get_nifi_version_info()
```

--------------------------------

### GET /remote-process-groups/{id}/status

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/nifi_apis/flow_api.md

Gets status for a remote process group.

```APIDOC
## GET /remote-process-groups/{id}/status

### Description
Gets status for a remote process group.

### Method
GET

### Parameters
#### Path Parameters
- **id** (str) - Required - The remote process group id.

#### Query Parameters
- **nodewise** (bool) - Optional - Whether or not to include the breakdown per node. Defaults to false.
- **cluster_node_id** (str) - Optional - The id of the node where to get the status.

### Response
#### Success Response (200)
- **RemoteProcessGroupStatusEntity** (object) - Response data containing remote process group status.
```

--------------------------------

### Set Up Sandbox Environment for Certificate Authentication

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/examples.md

Configure and run the sandbox environment with certificate-based authentication (mTLS). This is an advanced setup for secure environments.

```bash
$ make sandbox NIPYAPI_PROFILE=secure-mtls
```

--------------------------------

### GET /processor/{id}/status/history

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/nifi_apis/flow_api.md

Gets the status history for a specific processor.

```APIDOC
## GET /processor/{id}/status/history

### Description
Gets status history for a processor.

### Parameters
#### Path Parameters
- **id** (str) - Required - The processor id

### Response
#### Success Response (200)
- **StatusHistoryEntity** (object) - The status history entity.
```

--------------------------------

### JSON Output Example

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/cli.md

Demonstrates the default JSON output format for programmatic parsing.

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

--------------------------------

### GET /canvas/controller-services/docs/{controller}

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/core_modules/canvas.md

Get detailed documentation for a controller service type.

```APIDOC
## GET /canvas/controller-services/docs/{controller}

### Description
Retrieves the full ControllerServiceDefinition from NiFi for a given controller service type, containing comprehensive documentation.

### Method
GET

### Endpoint
/canvas/controller-services/docs/{controller}

### Parameters
#### Path Parameters
- **controller** (string) - Required - The name or type of the controller service (e.g., "JsonTreeReader", "org.apache.nifi.processors.standard.LogAttribute").

### Response
#### Success Response (200)
- **controllerServiceDefinition** (object) - The ControllerServiceDefinition object containing documentation, including property descriptors and tags.

#### Response Example
{
  "controllerServiceDefinition": {
    "type": "org.apache.nifi.services.MyService",
    "tags": ["example", "service"],
    "propertyDescriptors": {
      "property1": {
        "name": "property1",
        "displayName": "Property One",
        "description": "Description for property one."
      }
    }
  }
}
```

--------------------------------

### Switching Environments with Profiles

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/migration.md

Use the profiles system to automatically configure authentication and SSL settings based on a YAML file.

```python
# 1. Profiles file defines your environments
# examples/profiles.yml contains: single-user, secure-ldap, secure-mtls, secure-oidc

# 2. Switch to any environment with one function call
import nipyapi
nipyapi.profiles.switch('single-user')  # Configures everything automatically

# 3. Use NiPyAPI normally - authentication and SSL are handled
about = nipyapi.system.get_nifi_version_info()
```

--------------------------------

### Start Flow

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/ci.md

Starts a process group, optionally enabling controller services first.

```APIDOC
## POST /nifi-api/start_flow

### Description
Starts a process group (enable controllers, start processors).

### Method
POST

### Endpoint
/nifi-api/start_flow

### Parameters
#### Query Parameters
- **process_group_id** (string) - Required - ID of the process group
- **enable_controllers** (boolean) - Optional - Enable controller services first (default: True)

### Request Example
```json
{
  "process_group_id": "PG_ID",
  "enable_controllers": true
}
```

### Response
#### Success Response (200)
- **started** (boolean) - Indicates if the flow was started.
- **process_group_name** (string) - The name of the process group.

#### Response Example
```json
{
  "started": true,
  "process_group_name": "My Process Group"
}
```
```

--------------------------------

### List Installed Extensions

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/extensions.md

Retrieve and display all NARs currently installed in the NiFi instance.

```python
import nipyapi

# List all NARs
nars = nipyapi.extensions.list_nars()
for nar in nars:
    print(f"{nar.coordinate} - {nar.state}")
```

```shell
nipyapi ci list_nars
```

--------------------------------

### 1.x Manual Configuration

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/migration.md

Manual configuration remains supported in 1.x but is more verbose than the profiles system.

```python
# 1.x: Manual configuration still supported but more verbose
import nipyapi
from nipyapi import config, utils
```

--------------------------------

### List Installed NARs

Source: https://github.com/chaffelson/nipyapi/blob/main/docs/nipyapi-docs/core_modules/extensions.md

Retrieves a list of all NARs currently installed in the NiFi instance.

```APIDOC
## GET /extensions/list_nars

### Description
List all installed NARs in NiFi.

### Method
GET

### Endpoint
/extensions/list_nars

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **nar_list** (list[NarSummaryDTO]) - A list of NAR summary objects.

#### Response Example
```json
[
  {
    "coordinate": {
      "group": "org.apache.nifi",
      "artifact": "nifi-standard-nar",
      "version": "1.18.0"
    },
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "type": "NIFI",
    "version": "1.18.0"
  }
]
```
```