NiFi Basic Commands With Practical Examples

This guide covers the essential NiFi commands you need for day-to-day operations, with practical, copy-ready examples you can run safely. You will learn how to start and stop NiFi, check health, gather diagnostics, set credentials in single-user mode, and verify results with the REST API and logs. The examples emphasize low-risk steps that you can validate locally before applying to shared environments. Along the way, you will see expected outputs, common failure modes, and how to roll back quickly if needed.

A small set of clear, correct NiFi commands shortens time-to-fix for incidents, gives you faster feedback when changing flows, and establishes a repeatable baseline you can teach to teammates. A focused, narrow pilot is the fastest way to prove value and reduce rework.

Version and Environment Inventory

Before running any command, capture an inventory. This makes troubleshooting faster and reduces guesswork across the team.

Record the following:

• NiFi version: for example 1.x.y (find via UI About dialog or REST API below).
• Java runtime: java -version output.
• OS and kernel: uname -a (Linux/Unix) or systeminfo (Windows Server).
• Topology: standalone vs cluster, number of nodes, load balancer if any.
• Install location: NIFI_HOME, e.g., /opt/nifi or C:\nifi.
• Data directories: content, flowfile, provenance repositories, and logs path.
• Network: inbound UI/API port, hostnames, and any reverse proxy.
• Authentication mode: single-user, LDAP/SAML/OIDC, or none (dev only).

Keep this in a shared, versioned document for your team. When you see odd behavior, differences here often explain it quickly.

Safe Configuration Path

Adopt a narrow, low-risk path for your first pass, then expand as confidence grows.

Recommended pilot approach:

• Environment: a single-node, non-production NiFi with no critical data. Use test datasets.
• Access: if possible, use single-user authentication during the pilot so basic commands are easy to verify.
• Scope: validate start/stop/status, logs, diagnostics, and read-only API checks first. Only after that, test write actions (e.g., changing credentials) in a controlled window.
• Backups: before any changes, copy conf/flow.xml.gz and conf/bootstrap.conf to a dated backup folder.
• Rollback plan: define exact steps (stop NiFi, restore backup files, start NiFi) so you can revert fast.

This path lets you inspect changes locally and measure results without risking production. Once you have predictable outcomes, you can repeat these steps in staging and, later, production windows.

NiFi Basic Commands Cheat Sheet

These commands assume a typical installation with NIFI_HOME set to the NiFi root directory. Run them from NIFI_HOME or prefix with the full path, for example /opt/nifi/bin/nifi.sh.

Command Walkthrough With Practical Examples

The following scenarios demonstrate safe commands with expected results and verification steps. Adjust paths and ports for your environment.

Prerequisites:

• You have filesystem access to NIFI_HOME (example: /opt/nifi).
• Your PATH includes Java, and JAVA_HOME is set.
• If secured, you can authenticate to the NiFi UI/API.

Note on prompts and outputs: replace example host 127.0.0.1 and port 8443 / 8080 with your values.

1) Start NiFi and confirm status

Commands:

cd /opt/nifi
bin/nifi.sh start
sleep 5
bin/nifi.sh status

Expected results:

• start prints a short message like "NiFi has started." and returns quickly.
• status prints something like "NiFi is running with PID 12345." If not, it prints "NiFi is not running."

Verification steps:

• Tail the log for startup messages:

  tail -n 200 -f logs/nifi-app.log

• In the log, look for lines indicating the web server has started and which port it is listening on.
• Visit the UI in a browser, for example https://127.0.0.1:8443/ or http://127.0.0.1:8080/ depending on your config.

Common variations:

• To run in foreground with console logs for quick debugging:

  bin/nifi.sh run

Use Ctrl+C to stop. Do not use this mode as a daemon in production.

2) Stop NiFi safely

Commands:

cd /opt/nifi
bin/nifi.sh stop
sleep 5
bin/nifi.sh status

Expected results:

• stop returns promptly.
• After a short time, status reports NiFi is not running.

Verification steps:

• Check logs/nifi-app.log for graceful shutdown messages.
• Ensure the PID is gone. On Unix-like systems:

  ps -ef | grep nifi | grep -v grep

An empty result means the process exited.

Notes:

• If NiFi is slow to stop, allow extra time. NiFi flushes in-flight work to maintain data integrity.

3) Gather diagnostics for an incident

The dump command collects a bundle of diagnostic artifacts that can speed up root-cause analysis.

Command:

cd /opt/nifi
bin/nifi.sh dump

Expected results:

• Output indicates the path to a generated zip under logs/ (for example logs/diagnostics-YYYYMMDD-HHMMSS.zip).

Verification steps:

• List the file and inspect its timestamp:

  ls -lh logs | grep diagnostics

• Store the bundle per your team process.

4) Print environment for troubleshooting

When JVM or environment issues arise, confirming the runtime arguments helps narrow causes.

Command:

cd /opt/nifi
bin/nifi.sh env

Expected results:

• The command prints JAVA_HOME, JVM options, memory settings, and useful environment variables.

Verification steps:

• Confirm memory flags (-Xms, -Xmx) match your sizing plan.
• Check for unexpected overrides from the shell environment.

5) Set single-user credentials (for a dev pilot)

If using single-user authentication (common in local testing), set or rotate credentials safely. Perform this only in non-production or in a planned window.

Command (constructed example):

cd /opt/nifi
bin/nifi.sh set-single-user-credentials devadmin S3cur3P@ssw0rd!

Expected results:

• The script updates the appropriate configuration files for single-user access.
• A restart is typically required for the change to take effect.

Safe restart:

bin/nifi.sh restart

Verification steps:

• Log in to the UI with the new credentials.
• Test a read-only API call (see the API section below) to confirm authenticated access if your instance is secured.

Rollback plan:

• Stop NiFi.
• Restore prior credentials if you have a backup of the configuration (for example, conf/users.xml when applicable) or re-run the command with the previous values.
• Start NiFi and verify.

6) Log-based health checks during operations

Logs are the quickest window into NiFi behavior during command execution.

Examples:

• Tail application log during restart:

  tail -f logs/nifi-app.log

• Inspect bootstrap log for JVM launch details:

  tail -n 200 logs/nifi-bootstrap.log

• Check provenance and repository warnings quickly:

  grep -E "ERROR|WARN" logs/nifi-app.log | tail -n 50

Expected results:

• During startup, the web server binds to the configured port and reports readiness.
• During shutdown, the logs indicate processors stopped and repositories closed cleanly.

Verification and Diagnostics

Use a combination of UI checks, logs, and REST API calls. The following API calls are read-only and safe.

Replace the scheme/host/port with your environment. For secured instances, include an auth header or use a cookie/session from a prior login and add a minimal header like:

-H "X-Requested-By: nifi"

Example: confirm version and node state

curl -s http://127.0.0.1:8080/nifi-api/flow/about | jq .

Expected: JSON that includes the NiFi version string. If jq is not installed, remove the pipe to jq and view raw JSON.

Example: gather last 10 bulletins to quickly spot errors

curl -s http://127.0.0.1:8080/nifi-api/flow/bulletin-board?limit=10 | jq '.bulletinBoard.bulletins[] | {level: .bulletin.level, msg: .bulletin.message}'

Expected: A short list of recent messages. ERROR or WARN entries should be investigated.

Example: check cluster summary (works for standalone too)

curl -s http://127.0.0.1:8080/nifi-api/flow/cluster/summary | jq .clusterSummary

Expected: Node counts and statuses. For a single node, counts should be 1 online and 0 disconnected.

Note: In secured environments (HTTPS), add -k for self-signed certs in test and use https://host:8443/ as applicable. Ensure you follow your organization security policy.

Failure Modes and Recovery

The following issues are common during basic NiFi operations. Each includes a safe recovery path.

1. NiFi will not start

• Symptoms: status says "not running"; UI is unreachable; logs show bind failures or repository errors.
• Checks:
• Is the port already in use? netstat or ss can confirm.
• Does logs/nifi-app.log show repository corruption or permission issues?
• Is JAVA_HOME valid and compatible with your NiFi version?
• Recovery:
• Free the port or change the configured port, then retry start.
• Fix file permissions so the NiFi user can read/write repos and logs.
• If repository corruption is indicated for a non-critical dev instance, stop NiFi and clear only the affected test repository directories; for production, escalate and preserve data for analysis.
• Capture a diagnostics bundle with bin/nifi.sh dump before making major changes.

1. NiFi is slow to stop

• Symptoms: stop returns, but process persists for minutes.
• Checks:
• Tail logs to see which processors are waiting to finish work.
• Confirm external systems (e.g., Kafka, HDFS) are reachable; blocked IO can delay shutdown.
• Recovery:
• Allow extra time for graceful stop to avoid data loss.
• If required, a controlled service window can include a forceful termination, but prefer graceful shutdown to maintain flowfile integrity.

1. Authentication changes did not take effect

• Symptoms: updated single-user credentials but cannot log in.
• Checks:
• Did you restart NiFi after running set-single-user-credentials?
• Are you pointing to the correct host/port and protocol (http vs https)?
• Recovery:
• Stop NiFi, re-run the credentials command, verify config files updated, start NiFi.
• If you have backups, restore the previous configuration and start NiFi.

1. High CPU or memory after restart

• Symptoms: UI is responsive but system resources spike.
• Checks:
• Review bulletins and system diagnostics via the API for back pressure or errors.
• Check JVM flags with bin/nifi.sh env and validate heap sizing.
• Recovery:
• Right-size -Xms and -Xmx in the NiFi bootstrap or environment configuration per your capacity plan.
• Pause heavy processors or data sources, then resume gradually while watching diagnostics.

1. Configuration drift causes unexpected behavior

• Symptoms: a node behaves differently from others.
• Checks:
• Compare conf/flow.xml.gz timestamps and hashes across nodes.
• Confirm Java and OS versions match your baseline.
• Recovery:
• Stop the affected node, restore the last known-good conf/flow.xml.gz from backup, start the node, and verify.

General rollback guidance:

• Always stop NiFi before restoring configuration files.
• Keep dated backups of conf/flow.xml.gz and conf/bootstrap.conf at minimum.
• After rollback, verify with status, logs, UI availability, and API read-only checks.

Operations Checklist

Use this checklist for daily and weekly operations. Adjust interval based on workload and SLAs.

Daily

• Confirm NiFi is running: bin/nifi.sh status
• Check last 50 WARN/ERROR lines: grep -E "WARN|ERROR" logs/nifi-app.log | tail -n 50
• Review bulletins via API and UI for new warnings
• Verify available disk space for content, flowfile, provenance, and logs
• If in a cluster, confirm all nodes are connected via cluster summary

Weekly

• Capture a diagnostics bundle: bin/nifi.sh dump and archive it securely
• Review Java and NiFi memory settings with bin/nifi.sh env against observed usage
• Rotate or archive logs if not handled automatically
• Back up conf/flow.xml.gz and conf/bootstrap.conf with date-stamped copies

Change window (planned)

• Announce timing and impact
• Pre-change: bin/nifi.sh status; take backups of critical conf files
• Apply change: use start/stop/restart as necessary
• Post-change: verify UI, logs, and API checks; document outcomes
• If issues: execute rollback plan and re-verify

Incident response

• Stabilize first: stop or pause heavy sources if relevant
• Gather facts: logs, bulletins, API diagnostics
• Capture bin/nifi.sh dump for later analysis
• Apply targeted fixes; verify after each step

Conclusion

With a handful of NiFi basic commands and clear verification steps, you can operate NiFi confidently and recover quickly from common issues. Start with a narrow, safe pilot: learn start/stop/status, watch logs, collect diagnostics, and make small, reversible changes. Use the API checks to confirm health without guesswork. Then, standardize your daily and weekly routines with the checklist so every operator can achieve consistent results. Capture your environment inventory and baseline the commands in a dev instance. Practice the failure and recovery scenarios using test data. Integrate the checks into your team runbooks so they are easy to execute during routine operations and incidents alike.