CLI Reference

Complete command-line interface reference for all KafkaGuard commands, flags, and options.

Command Overview
Global Flags
scan Command
validate-policy Command
list-controls Command
version Command
Exit Codes
Command Examples by Use Case

Command Overview

KafkaGuard provides four primary commands:

Command	Purpose	Common Use
`scan`	Scan Kafka cluster against policy	Daily operations, CI/CD pipelines
`validate-policy`	Validate policy file syntax	Before deploying custom policies
list-controls	List available controls from policy	Documentation, policy review
`version`	Display version information	Troubleshooting, CI/CD version checks

Command Syntax Conventions

kafkaguard <command> [flags]

<command> - Required command name
[flags] - Optional flags (can be combined)
Arguments in <> are required
Arguments in [] are optional

Global Flags

Flags available for all commands:

Flag	Short	Type	Default	Description
`--help`	`-h`	bool	false	Display help for command
`--log-level`	`-l`	string	`info`	Log level: `debug`, `info`, `warn`, `error`
`--no-color`		bool	false	Disable colored output (useful for CI/CD)
`--config`	`-c`	string	`.kafkaguard.yaml`	Path to configuration file

Global Flag Examples

# Display help for scan command
kafkaguard scan --help

# Run with debug logging
kafkaguard scan --log-level debug --bootstrap kafka:9092

# Disable colored output for CI/CD
kafkaguard scan --no-color --bootstrap kafka:9092

# Use custom config file
kafkaguard scan --config /etc/kafkaguard/config.yaml

scan Command

The primary command for scanning Kafka clusters and generating compliance reports.

Syntax

kafkaguard scan [flags]

Required Flags

Flag	Short	Type	Description
`--bootstrap`	`-b`	string	Kafka bootstrap servers (comma-separated: `broker1:9092,broker2:9092`)

Optional Flags

General Flags

Flag	Short	Type	Default	Description
`--policy`	`-p`	string	`policies/baseline-dev.yaml`	Path to policy YAML file
`--out`	`-o`	string	`./reports`	Output directory for reports
`--format`	`-f`	string	`json`	Report formats (comma-separated: `json,html,pdf,csv`)
`--fail-on`		string	`high`	Fail threshold: `high`, `medium`, `low`, `none`
`--timeout`		int	300	Scan timeout in seconds

Security Flags

Flag	Type	Default	Description
`--security-protocol`	string	auto-detect	Security protocol: `PLAINTEXT`, `SSL`, `SASL_PLAINTEXT`, `SASL_SSL`
`--sasl-mechanism`	string	-	SASL mechanism: `PLAIN`, `SCRAM-SHA-256`, `SCRAM-SHA-512`
`--sasl-username`	string	-	SASL username (prefer `KAFKAGUARD_SASL_USERNAME` env var)
`--sasl-password`	string	-	SASL password (prefer `KAFKAGUARD_SASL_PASSWORD` env var)
`--tls-ca-cert`	string	-	Path to CA certificate file (for server verification)
`--tls-client-cert`	string	-	Path to client certificate file (for mutual TLS)
`--tls-client-key`	string	-	Path to client private key file (for mutual TLS)
`--tls-insecure-skip-verify`	bool	false	Skip TLS certificate verification (testing only, NOT for production)

Performance Flags

Flag	Type	Default	Description
`--parallel`	bool	true	Enable parallel data collection
`--max-collectors`	int	6	Maximum concurrent collectors

scan Examples

Basic Development Cluster Scan

# Minimal scan with PLAINTEXT protocol
kafkaguard scan --bootstrap localhost:9092

# Scan with custom policy
kafkaguard scan \
  --bootstrap localhost:9092 \
  --policy policies/baseline-dev.yaml \
  --format html,json \
  --out ./reports

Production Cluster Scan (SASL_SSL)

# Production scan with SCRAM-SHA-512
kafkaguard scan \
  --bootstrap kafka.prod.example.com:9095 \
  --security-protocol SASL_SSL \
  --sasl-mechanism SCRAM-SHA-512 \
  --sasl-username admin \
  --sasl-password secret \
  --tls-ca-cert /path/to/ca-cert.pem \
  --policy policies/enterprise-default.yaml \
  --format json,html,pdf \
  --out /var/reports

# Better: Use environment variables for credentials
export KAFKAGUARD_SASL_USERNAME=admin
export KAFKAGUARD_SASL_PASSWORD=secret

kafkaguard scan \
  --bootstrap kafka.prod.example.com:9095 \
  --security-protocol SASL_SSL \
  --sasl-mechanism SCRAM-SHA-512 \
  --tls-ca-cert /path/to/ca-cert.pem \
  --policy policies/enterprise-default.yaml \
  --format json,html,pdf \
  --out /var/reports

Multi-Format Report Generation

# Generate all 4 report formats
kafkaguard scan \
  --bootstrap kafka:9092 \
  --policy policies/enterprise-default.yaml \
  --format json,html,pdf,csv \
  --out ./reports

# Reports generated:
# - reports/scan-20251115120530-abc123.json
# - reports/scan-20251115120530-abc123.html
# - reports/scan-20251115120530-abc123.pdf
# - reports/scan-20251115120530-abc123.csv

CI/CD Integration with Fail Threshold

# Fail pipeline if HIGH severity findings detected
kafkaguard scan \
  --bootstrap kafka.prod.example.com:9095 \
  --policy policies/enterprise-default.yaml \
  --format json \
  --fail-on high \
  --no-color \
  --out ./reports

# Check exit code
EXIT_CODE=$?
if [ $EXIT_CODE -eq 1 ]; then
  echo "HIGH severity findings detected!"
  exit 1
fi

Mutual TLS (mTLS) Authentication

# Scan with client certificate authentication
kafkaguard scan \
  --bootstrap kafka:9093 \
  --security-protocol SSL \
  --tls-ca-cert /path/to/ca-cert.pem \
  --tls-client-cert /path/to/client-cert.pem \
  --tls-client-key /path/to/client-key.pem \
  --policy policies/enterprise-default.yaml \
  --out ./reports

Custom Timeout for Large Clusters

# Increase timeout for large clusters (1000+ topics)
kafkaguard scan \
  --bootstrap kafka:9092 \
  --policy policies/enterprise-default.yaml \
  --timeout 600 \
  --out ./reports

validate-policy Command

Validates policy files for syntax and structural correctness before use.

Syntax

kafkaguard validate-policy --policy <file> [flags]

Required Flags

Flag	Short	Type	Description
`--policy`	`-p`	string	Path to policy YAML file to validate

Validation Checks Performed

The validate-policy command performs the following checks:

✅ YAML Syntax - Valid YAML structure and parseable
✅ Required Fields - version, name, controls fields present
✅ Control ID Format - IDs match KG-XXX pattern (3 digits: KG-001, KG-042, etc.)
✅ Control Fields - Each control has id, title, description, severity, category, expr
✅ Severity Values - Valid values: HIGH, MEDIUM, LOW
✅ Category Values - Valid values: security, reliability, operational, compliance
✅ CEL Expression Syntax - CEL expressions have valid syntax (syntax check, not evaluated)
✅ Unique Control IDs - No duplicate control IDs in policy
✅ Compliance Mapping - Valid compliance framework references (if present)

validate-policy Examples

Validate Policy File

# Validate a policy file
kafkaguard validate-policy --policy policies/custom-policy.yaml

# Validate with debug logging
kafkaguard validate-policy \
  --policy policies/custom-policy.yaml \
  --log-level debug

Successful Validation Output

$ kafkaguard validate-policy --policy policies/enterprise-default.yaml

✅ Policy validation successful

Policy Details:
  Name:        Enterprise Default Policy
  Version:     1.0
  Description: Production-ready policy with 40 security, reliability, and operational controls
  Controls:    40

Severity Distribution:
  HIGH:        18
  MEDIUM:      12
  LOW:         10

Category Distribution:
  security:    15
  reliability: 12
  operational: 13

Validation Error Output

$ kafkaguard validate-policy --policy policies/bad-policy.yaml

❌ Error: invalid control ID format 'KG-1' at control index 3

💡 Suggestion: Control IDs must match pattern KG-XXX where XXX is 3 digits
   Examples: KG-001, KG-042, KG-123

Details:
  File:         policies/bad-policy.yaml
  Control:      3 (KG-1)
  Expected:     KG-001 format (3-digit padding)

Common Validation Errors

Error	Cause	Fix
`missing required field 'version'`	No version field in policy	Add `version: "1.0"` to policy file
`missing required field 'name'`	No name field in policy	Add `name: "My Policy"` to policy file
`invalid control ID format 'KG-1'`	Control ID not 3 digits	Change to `KG-001` format
`invalid severity 'CRITICAL'`	Invalid severity value	Use `HIGH`, `MEDIUM`, or `LOW`
`invalid category 'performance'`	Invalid category value	Use `security`, `reliability`, `operational`, or `compliance`
`CEL syntax error at line X`	Invalid CEL expression	Check CEL syntax using CEL spec
`duplicate control ID 'KG-001'`	Same control ID used twice	Ensure all control IDs are unique

list-controls Command

Displays all controls from a policy file with optional filtering.

Syntax

kafkaguard list-controls [flags]

Optional Flags

Flag	Short	Type	Default	Description
`--policy`	`-p`	string	`policies/baseline-dev.yaml`	Path to policy file
`--format`	`-f`	string	`text`	Output format: `text` or `json`
`--severity`		string	-	Filter by severity: `HIGH`, `MEDIUM`, `LOW`
`--category`		string	-	Filter by category: `security`, `reliability`, `operational`, `compliance`

list-controls Examples

List All Controls

# List all controls from default policy
kafkaguard list-controls

# List controls from specific policy
kafkaguard list-controls --policy policies/enterprise-default.yaml

Filter by Severity

# List only HIGH severity controls
kafkaguard list-controls \
  --policy policies/enterprise-default.yaml \
  --severity HIGH

# List MEDIUM and below (combine with grep)
kafkaguard list-controls --policy policies/enterprise-default.yaml | grep -E "MEDIUM|LOW"

Filter by Category

# List only security controls
kafkaguard list-controls \
  --policy policies/enterprise-default.yaml \
  --category security

# List reliability controls
kafkaguard list-controls \
  --policy policies/enterprise-default.yaml \
  --category reliability

Combine Filters

# List HIGH severity security controls
kafkaguard list-controls \
  --policy policies/enterprise-default.yaml \
  --severity HIGH \
  --category security

JSON Output for Automation

# Output as JSON for scripting
kafkaguard list-controls \
  --policy policies/enterprise-default.yaml \
  --format json > controls.json

# Parse with jq
cat controls.json | jq '.controls[] | select(.severity == "HIGH") | .id'

# Count controls by severity
cat controls.json | jq '.controls | group_by(.severity) | map({severity: .[0].severity, count: length})'

Text Output Format

$ kafkaguard list-controls --policy policies/baseline-dev.yaml

KafkaGuard Policy: Baseline Development Policy
Version: 1.0
Tier: development
Total Controls: 20

Severity Distribution:
  MEDIUM: 12
  LOW:     8

Category Distribution:
  reliability: 8
  operational: 12

## Reliability Controls (8)

ID       Title                                    Severity  Category
---      ---                                      ---       ---
KG-016   Minimum replication factor ≥3            MEDIUM    reliability
KG-017   In-Sync Replicas (ISR) ≥2                MEDIUM    reliability
KG-018   Unclean leader election disabled         MEDIUM    reliability
KG-019   ZooKeeper quorum odd (3+)                MEDIUM    reliability
KG-020   Consistent broker versions               MEDIUM    reliability
KG-021   Balanced partitions across brokers       LOW       reliability
KG-022   Under-replicated partitions = 0          MEDIUM    reliability
KG-023   Offline partitions = 0                   MEDIUM    reliability

## Operational Controls (12)

ID       Title                                    Severity  Category
---      ---                                      ---       ---
KG-028   Auto-create topics disabled              MEDIUM    operational
KG-029   Log directories on separate disks        LOW       operational
[... more controls ...]

version Command

Displays KafkaGuard version and build information.

Syntax

kafkaguard version [flags]

Optional Flags

Flag	Short	Type	Default	Description
`--format`	`-f`	string	`text`	Output format: `text` or `json`

version Examples

Text Format (Default)

$ kafkaguard version

KafkaGuard v1.0.0
Commit: a1b2c3d4e5f6
Built: 2025-11-15T12:00:00Z
Go: go1.22.0 darwin/arm64

JSON Format

$ kafkaguard version --format json

{
  "version": "1.0.0",
  "commit": "a1b2c3d4e5f6",
  "date": "2025-11-15T12:00:00Z",
  "go_version": "go1.22.0",
  "platform": "darwin/arm64"
}

Extract Version in Scripts

# Extract version number
VERSION=$(kafkaguard version --format json | jq -r '.version')
echo "Running KafkaGuard $VERSION"

# Check if version meets requirement
REQUIRED="1.0.0"
CURRENT=$(kafkaguard version --format json | jq -r '.version')
if [ "$CURRENT" != "$REQUIRED" ]; then
  echo "Version mismatch: expected $REQUIRED, got $CURRENT"
  exit 1
fi

Exit Codes

KafkaGuard uses standard exit codes for scripting and CI/CD integration.

Exit Code Reference

Exit Code	Meaning	Description	Use Case
0	Success	Scan completed successfully, no findings above `--fail-on` threshold	Continue pipeline, deploy changes
1	Findings	Scan completed, findings exceed `--fail-on` threshold	Block deployment, review findings
2	Error	Scan failed due to errors (connection failure, invalid config, policy error)	Fix configuration, check connectivity

Exit Code Behavior by Command

Command	Exit Code 0	Exit Code 1	Exit Code 2
`scan`	No findings above threshold	Findings above threshold	Connection/config error
`validate-policy`	Policy valid	Not used	Policy invalid
`list-controls`	Success	Not used	Policy file error
`version`	Success	Not used	Not used

Exit Code Examples

CI/CD Pipeline Integration

#!/bin/bash
set -e

echo "Running KafkaGuard scan..."
kafkaguard scan \
  --bootstrap kafka.prod.example.com:9095 \
  --policy policies/enterprise-default.yaml \
  --format json \
  --fail-on high \
  --out ./reports

EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  echo "✅ Scan passed - no critical findings"
  exit 0
elif [ $EXIT_CODE -eq 1 ]; then
  echo "⚠️  Scan found policy violations exceeding threshold"

  # Parse and display findings
  cat reports/scan-*.json | jq '.findings[] | select(.status == "FAILED" and .severity == "HIGH")'

  # Block deployment
  exit 1
else
  echo "❌ Scan failed with errors"
  exit 2
fi

GitHub Actions Workflow

name: Kafka Compliance Scan

on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Download KafkaGuard
        run: |
          curl -LO https://github.com/aiopsone/kafkaguard-releases/releases/latest/download/kafkaguard_Linux_x86_64.tar.gz && tar -xzf kafkaguard_Linux_x86_64.tar.gz
          chmod +x kafkaguard-linux-amd64
          sudo mv kafkaguard-linux-amd64 /usr/local/bin/kafkaguard

      - name: Run Compliance Scan
        env:
          KAFKAGUARD_SASL_USERNAME: ${{ secrets.KAFKA_USERNAME }}
          KAFKAGUARD_SASL_PASSWORD: ${{ secrets.KAFKA_PASSWORD }}
        run: |
          kafkaguard scan \
            --bootstrap ${{ secrets.KAFKA_BROKER }} \
            --security-protocol SASL_SSL \
            --sasl-mechanism SCRAM-SHA-512 \
            --policy policies/enterprise-default.yaml \
            --format json \
            --fail-on high \
            --no-color

      - name: Upload Report
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: compliance-report
          path: reports/*.json

Jenkins Pipeline

pipeline {
  agent any

  environment {
    KAFKAGUARD_SASL_USERNAME = credentials('kafka-username')
    KAFKAGUARD_SASL_PASSWORD = credentials('kafka-password')
  }

  stages {
    stage('Kafka Compliance Scan') {
      steps {
        script {
          def exitCode = sh(
            script: '''
              kafkaguard scan \
                --bootstrap kafka.prod.example.com:9095 \
                --security-protocol SASL_SSL \
                --sasl-mechanism SCRAM-SHA-512 \
                --policy policies/enterprise-default.yaml \
                --format json \
                --fail-on high \
                --no-color
            ''',
            returnStatus: true
          )

          if (exitCode == 0) {
            echo 'Scan passed - no critical findings'
          } else if (exitCode == 1) {
            currentBuild.result = 'UNSTABLE'
            echo 'Policy violations detected'
          } else {
            currentBuild.result = 'FAILURE'
            error('Scan failed with errors')
          }
        }
      }
    }
  }

  post {
    always {
      archiveArtifacts artifacts: 'reports/*.json', fingerprint: true
    }
  }
}

Command Examples by Use Case

Development Cluster Scan

# Quick scan with minimal configuration
kafkaguard scan \
  --bootstrap localhost:9092 \
  --policy policies/baseline-dev.yaml \
  --format html \
  --out ./reports

Production Compliance Scan

# Full production scan with SASL_SSL
export KAFKAGUARD_SASL_USERNAME=admin
export KAFKAGUARD_SASL_PASSWORD=secret

kafkaguard scan \
  --bootstrap kafka1.prod.example.com:9095,kafka2.prod.example.com:9095 \
  --security-protocol SASL_SSL \
  --sasl-mechanism SCRAM-SHA-512 \
  --tls-ca-cert /etc/kafkaguard/certs/ca.pem \
  --policy policies/enterprise-default.yaml \
  --format json,html,pdf \
  --fail-on high \
  --timeout 600 \
  --out /var/reports/kafkaguard

Audit Report Generation

# Generate PDF report for compliance auditor
kafkaguard scan \
  --bootstrap kafka:9095 \
  --security-protocol SASL_SSL \
  --sasl-mechanism SCRAM-SHA-512 \
  --tls-ca-cert /certs/ca.pem \
  --tls-client-cert /certs/client.pem \
  --tls-client-key /certs/client-key.pem \
  --policy policies/custom-audit-policy.yaml \
  --format pdf,csv \
  --out /audit/reports

Policy Development Workflow

# 1. List controls in policy
kafkaguard list-controls --policy policies/custom-policy.yaml

# 2. Validate policy syntax
kafkaguard validate-policy --policy policies/custom-policy.yaml

# 3. Test against dev cluster
kafkaguard scan \
  --bootstrap localhost:9092 \
  --policy policies/custom-policy.yaml \
  --format json \
  --out ./test-reports

# 4. Review results and iterate

Air-Gapped Environment Scan

# Run scan in air-gapped environment
kafkaguard scan \
  --bootstrap kafka-internal:9092 \
  --policy /opt/kafkaguard/policies/enterprise-default.yaml \
  --format json,html,pdf,csv \
  --out /var/reports/kafkaguard \
  --timeout 600

Multi-Cluster Scanning Script

#!/bin/bash
# Scan multiple Kafka clusters

CLUSTERS=("kafka-dev:9092" "kafka-staging:9095" "kafka-prod:9095")
POLICIES=("baseline-dev.yaml" "enterprise-default.yaml" "enterprise-default.yaml")

for i in "${!CLUSTERS[@]}"; do
  CLUSTER="${CLUSTERS[$i]}"
  POLICY="${POLICIES[$i]}"
  CLUSTER_NAME=$(echo "$CLUSTER" | cut -d: -f1)

  echo "Scanning $CLUSTER_NAME..."

  kafkaguard scan \
    --bootstrap "$CLUSTER" \
    --policy "policies/$POLICY" \
    --format json,html \
    --out "./reports/$CLUSTER_NAME" \
    --log-level info

  echo "Scan complete for $CLUSTER_NAME"
done

echo "All scans complete"

Flag Precedence

When the same configuration is specified in multiple places, KafkaGuard uses this precedence order (highest to lowest):

Command-line flags (highest precedence)
Environment variables (KAFKAGUARD_*)
Configuration file (.kafkaguard.yaml)
Default values (lowest precedence)

Flag Precedence Example

# Config file has: bootstrap: kafka-config:9092
# Env var set: KAFKAGUARD_BOOTSTRAP=kafka-env:9092
# CLI flag: --bootstrap kafka-cli:9092

kafkaguard scan --bootstrap kafka-cli:9092

# Result: Uses kafka-cli:9092 (CLI flag wins)

For more details on configuration, see Configuration Guide.

Getting Help

Command-Specific Help

# Help for scan command
kafkaguard scan --help

# Help for validate-policy command
kafkaguard validate-policy --help

# Help for list-controls command
kafkaguard list-controls --help

General Help

# Show all available commands
kafkaguard --help

# Show version
kafkaguard version

Next Steps

Configuration Guide - Learn about configuration files and environment variables
Security & Authentication - Set up SASL/SSL for production clusters
Usage Patterns - Common workflows and integration examples
Troubleshooting - Resolve common errors and issues

Document Information

Last Updated: 2025-11-15
Applies to Version: KafkaGuard 1.0.0+
Feedback: Open an issue for corrections or improvements

CLI Reference

Table of Contents

Command Overview

Command Syntax Conventions

Global Flags

Global Flag Examples

scan Command

Syntax

Required Flags

Optional Flags

General Flags

Security Flags

Performance Flags

scan Examples

Basic Development Cluster Scan

Production Cluster Scan (SASL_SSL)

Multi-Format Report Generation

CI/CD Integration with Fail Threshold

Mutual TLS (mTLS) Authentication

Custom Timeout for Large Clusters

validate-policy Command

Syntax

Required Flags

Validation Checks Performed

validate-policy Examples

Validate Policy File

Successful Validation Output

Validation Error Output

Common Validation Errors

list-controls Command

Syntax

Optional Flags

list-controls Examples

List All Controls

Filter by Severity

Filter by Category

Combine Filters

JSON Output for Automation

Text Output Format

version Command

Syntax

Optional Flags

version Examples

Text Format (Default)

JSON Format

Extract Version in Scripts

Exit Codes

Exit Code Reference

Exit Code Behavior by Command

Exit Code Examples

CI/CD Pipeline Integration

GitHub Actions Workflow

Jenkins Pipeline

Command Examples by Use Case

Development Cluster Scan

Production Compliance Scan

Audit Report Generation

Policy Development Workflow

Air-Gapped Environment Scan

Multi-Cluster Scanning Script

Flag Precedence

Flag Precedence Example

Getting Help

Command-Specific Help

General Help

Next Steps