nu_plugin_kcl\n\nA powerful Nushell plugin for KCL (Kubernetes Configuration Language) workflows, providing seamless integration between Nushell's data processing capabilities and KCL's configuration management system.\n\n## Overview\n\nThis plugin wraps the KCL CLI to provide native Nushell commands for running, formatting, and validating KCL configurations. Perfect for Infrastructure as Code (IaC), Kubernetes manifests, and configuration management workflows where you need to combine structured data processing with declarative configuration.\n\n## Installing\n\n> [!CAUTION]\n> Require to have KCL CLI wrapper\n> use KCL installation documentation\n\nClone this repository\n\n> [!WARNING]\n> nu_plugin_kcl has dependencies to nushell source via local path in Cargo.toml\n> Nushell and plugins require to be sync with same version\n\nClone Nushell alongside this plugin or change dependencies in Cargo.toml\n\nThis plugin is also included as submodule in nushell-plugins\nas part of plugins collection for Provisioning project\n\nBuild from source\n\nnushell\n> cd nu_plugin_kcl\n> cargo install --path .\n\n\n### Nushell\n\nIn a Nushell\n\nnushell\n> plugin add ~/.cargo/bin/nu_plugin_kcl\n\n\n## Commands\n\n### kcl-run\n\nExecute KCL files and return their output with support for variables, output formats, and settings.\n\nnushell\n> kcl-run <file> [--format] [--output] [--define] [--setting]\n\n\nParameters:\n\n- file <path>: KCL file to execute\n\nFlags:\n\n- --format -f <string>: Output format (yaml/json)\n- --output -o <path>: Output file path\n- --define -D <string>: Variables to define (key=value)\n- --setting -Y <string>: Setting files to include\n\nExample:\n\nnushell\n> kcl-run myfile.k -D foo=bar -f json\n{\n "foo": "bar"\n}\n\n\n### kcl-format\n\nFormat KCL files according to standard KCL formatting rules.\n\nnushell\n> kcl-format <file>\n\n\nParameters:\n\n- file <path>: KCL file to format\n\nExample:\n\nnushell\n> kcl-format myfile.k\n✅ File formatted: myfile.k\n\n\n### kcl-validate\n\nValidate all KCL files in a directory for syntax and semantic correctness.\n\nnushell\n> kcl-validate [directory]\n\n\nParameters:\n\n- directory <path>: Directory to validate (defaults to current directory)\n\nExample:\n\nnushell\n> kcl-validate ./project_dir\n✅ All 3 files are valid\n\n✅ ./project_dir/main.k\n✅ ./project_dir/vars.k\n✅ ./project_dir/other.k\n\n\n## KCL Configuration Language\n\nKCL is a constraint-based record and functional programming language hosted by CNCF. It provides powerful features for configuration management:\n\n### Basic Syntax\n\nkcl\n# Simple configuration\nname = "my-app"\nversion = "1.0.0"\n\n# Schema definition\nschema Config:\n name: str\n version: str\n replicas: int = 3\n\n# Configuration instance\nconfig: Config = {\n name = name\n version = version\n replicas = 5\n}\n\n\n### Advanced Features\n\nkcl\n# Constraints and validation\nschema Service:\n name: str\n port: int\n\n check:\n 1 <= port <= 65535, "port must be between 1 and 65535"\n len(name) > 0, "name cannot be empty"\n\n# Conditional logic\nconfig = {\n env = "production"\n database = {\n host = "prod-db.example.com" if env == "production" else "localhost"\n port = 5432\n ssl = True if env == "production" else False\n }\n}\n\n# List comprehensions and filters\nservices = [\n {name = "web-${i}", port = 8000 + i} for i in range(3)\n] + [\n {name = "worker-${i}", port = 9000 + i} for i in range(2)\n]\n\n# Filtering\nweb_services = [s for s in services if "web" in s.name]\n\n\n## Usage Examples\n\n### Basic Configuration Management\n\napp-config.k\n\nkcl\n# Application configuration schema\nschema AppConfig:\n name: str\n version: str\n environment: str\n database: DatabaseConfig\n server: ServerConfig\n\nschema DatabaseConfig:\n host: str\n port: int = 5432\n name: str\n ssl: bool = True\n\nschema ServerConfig:\n host: str = "0.0.0.0"\n port: int = 8080\n workers: int = 4\n\n# Configuration instance\nconfig: AppConfig = {\n name = "my-microservice"\n version = "1.2.3"\n environment = "production"\n database = {\n host = "db.example.com"\n name = "myapp_prod"\n ssl = True\n }\n server = {\n port = 8080\n workers = 8\n }\n}\n\n\nUsage:\n\nnushell\n> kcl-run app-config.k -f yaml\nname: my-microservice\nversion: 1.2.3\nenvironment: production\ndatabase:\n host: db.example.com\n port: 5432\n name: myapp_prod\n ssl: true\nserver:\n host: 0.0.0.0\n port: 8080\n workers: 8\n\n\n### Dynamic Configuration with Variables\n\nkubernetes-deployment.k\n\nkcl\n# Kubernetes deployment template\nschema Deployment:\n apiVersion: str = "apps/v1"\n kind: str = "Deployment"\n metadata: {\n name: str\n namespace?: str\n }\n spec: {\n replicas: int\n selector: {\n matchLabels: {str:}\n }\n template: {\n metadata: {\n labels: {str:}\n }\n spec: {\n containers: [Container]\n }\n }\n }\n\nschema Container:\n name: str\n image: str\n ports?: [{\n containerPort: int\n protocol?: str = "TCP"\n }]\n env?: [{\n name: str\n value: str\n }]\n\n# Variables with defaults\napp_name = option("app_name") or "my-app"\napp_version = option("app_version") or "latest"\nreplicas = option("replicas") or 3\nnamespace = option("namespace") or "default"\n\n# Generate deployment\ndeployment: Deployment = {\n metadata = {\n name = app_name\n namespace = namespace\n }\n spec = {\n replicas = replicas\n selector.matchLabels = {"app": app_name}\n template = {\n metadata.labels = {"app": app_name}\n spec.containers = [{\n name = app_name\n image = "${app_name}:${app_version}"\n ports = [{containerPort = 8080}]\n env = [\n {name = "APP_NAME", value = app_name}\n {name = "APP_VERSION", value = app_version}\n ]\n }]\n }\n }\n}\n\n\nUsage:\n\nnushell\n# Basic deployment\n> kcl-run kubernetes-deployment.k -D app_name=web-service -D app_version=v1.2.3 -f yaml\n\n# Multiple environment deployment\n> ["dev", "staging", "prod"] | each { |env|\n kcl-run kubernetes-deployment.k -D app_name=web-service -D app_version=v1.2.3 -D namespace=$env -f yaml\n | save $"manifests/($env)/deployment.yaml"\n}\n\n\n### Multi-Environment Configuration\n\nbase-config.k\n\nkcl\n# Base configuration shared across environments\nschema BaseConfig:\n app: {\n name: str\n version: str\n }\n features: {\n auth: bool = True\n metrics: bool = True\n logging: bool = True\n }\n\nbase: BaseConfig = {\n app = {\n name = "my-service"\n version = "1.0.0"\n }\n features = {\n auth = True\n metrics = True\n logging = True\n }\n}\n\n\nenvironments/dev.k\n\nkcl\nimport base\n\n# Development environment overrides\nconfig = base.base | {\n environment = "development"\n database = {\n host = "localhost"\n port = 5432\n name = "myapp_dev"\n ssl = False\n }\n server = {\n host = "localhost"\n port = 3000\n debug = True\n }\n features = base.base.features | {\n auth = False # Disable auth in dev\n }\n}\n\n\nenvironments/prod.k\n\nkcl\nimport base\n\n# Production environment configuration\nconfig = base.base | {\n environment = "production"\n database = {\n host = "prod-db.example.com"\n port = 5432\n name = "myapp_prod"\n ssl = True\n pool_size = 20\n }\n server = {\n host = "0.0.0.0"\n port = 8080\n workers = 16\n debug = False\n }\n security = {\n rate_limit = 1000\n cors_origins = ["https://myapp.com"]\n }\n}\n\n\nUsage:\n\nnushell\n# Generate configurations for all environments\n> ["dev", "staging", "prod"] | each { |env|\n let config = (kcl-run $"environments/($env).k" -f json | from json)\n $config | to yaml | save $"configs/($env).yaml"\n print $"Generated config for ($env)"\n}\n\n\n## Workflow Examples\n\n### Infrastructure as Code Pipeline\n\nnushell\n# Complete IaC workflow with KCL\ndef deploy-infrastructure [environment: string] {\n print $"🚀 Deploying infrastructure for ($environment)"\n\n # 1. Validate all KCL files\n print "📋 Validating KCL configurations..."\n let validation = (kcl-validate ./infrastructure)\n print $validation\n\n # 2. Generate environment-specific configs\n print $"⚙️ Generating ($environment) configuration..."\n let config = (kcl-run $"infrastructure/($environment).k" -f yaml)\n $config | save $"output/($environment)/config.yaml"\n\n # 3. Generate Kubernetes manifests\n print "🎯 Generating Kubernetes manifests..."\n ls infrastructure/kubernetes/*.k\n | each { |manifest|\n let name = ($manifest.name | path basename | str replace '.k' '')\n kcl-run $manifest.name -D environment=$environment -f yaml\n | save $"output/($environment)/k8s/($name).yaml"\n }\n\n # 4. Validate generated YAML\n print "✅ Validating generated manifests..."\n ls $"output/($environment)/k8s/*.yaml"\n | each { |file|\n # You could add kubectl validation here\n print $"Validated: ($file.name)"\n }\n\n print $"✨ Infrastructure deployment for ($environment) complete!"\n}\n\n# Usage\n> deploy-infrastructure "staging"\n\n\n### Configuration Validation and Testing\n\nnushell\n# Comprehensive validation workflow\ndef validate-all-configs [] {\n print "🔍 Starting comprehensive validation..."\n\n # 1. Validate KCL syntax\n print "📝 Validating KCL syntax..."\n let kcl_validation = (kcl-validate .)\n print $kcl_validation\n\n # 2. Test all environment configurations\n print "🌍 Testing environment configurations..."\n let environments = ["dev", "staging", "prod"]\n let results = ($environments | each { |env|\n try {\n let config = (kcl-run $"environments/($env).k" -f json | from json)\n {\n environment: $env\n status: "✅ valid"\n config_keys: ($config | columns | length)\n }\n } catch { |err|\n {\n environment: $env\n status: "❌ invalid"\n error: $err.msg\n }\n }\n })\n\n $results | table\n\n # 3. Check for required configuration keys\n print "🔑 Checking required configuration keys..."\n let required_keys = ["app", "database", "server"]\n $environments | each { |env|\n let config = (kcl-run $"environments/($env).k" -f json | from json)\n let missing = ($required_keys | where $it not-in ($config | columns))\n if ($missing | length) > 0 {\n print $"⚠️ ($env): Missing keys: ($missing | str join ', ')"\n } else {\n print $"✅ ($env): All required keys present"\n }\n }\n}\n\n# Schema validation helper\ndef validate-schema [config_file: string, schema_file: string] {\n try {\n kcl-run $config_file -Y $schema_file -f json | from json\n print $"✅ ($config_file) validates against schema"\n } catch { |err|\n print $"❌ ($config_file) schema validation failed: ($err.msg)"\n }\n}\n\n\n### Continuous Integration Integration\n\nnushell\n# CI/CD pipeline integration\ndef ci-kcl-pipeline [] {\n print "🏗️ Starting KCL CI pipeline..."\n\n # 1. Format check\n print "📐 Checking code formatting..."\n let unformatted = (ls **/*.k | each { |file|\n let original = (open $file.name)\n kcl-format $file.name\n let formatted = (open $file.name)\n if $original != $formatted {\n $file.name\n }\n } | compact)\n\n if ($unformatted | length) > 0 {\n print $"❌ Unformatted files found: ($unformatted | str join ', ')"\n exit 1\n }\n print "✅ All files properly formatted"\n\n # 2. Validation\n print "🔍 Validating configurations..."\n let validation = (kcl-validate .)\n if "❌" in $validation {\n print "❌ Validation failed"\n print $validation\n exit 1\n }\n print "✅ All configurations valid"\n\n # 3. Generate and test configurations\n print "⚙️ Testing configuration generation..."\n ["dev", "staging", "prod"] | each { |env|\n try {\n kcl-run $"environments/($env).k" -f json | from json | ignore\n print $"✅ ($env) configuration generates successfully"\n } catch { |err|\n print $"❌ ($env) configuration failed: ($err.msg)"\n exit 1\n }\n }\n\n print "🎉 KCL CI pipeline completed successfully!"\n}\n\n\n### Configuration Management and Templating\n\nnushell\n# Generate application configurations from templates\ndef generate-app-config [app_name: string, version: string, environment: string] {\n let template = "templates/app-template.k"\n let settings = $"settings/($environment).yaml"\n\n kcl-run $template -D app_name=$app_name -D version=$version -Y $settings -f yaml\n | save $"configs/($app_name)-($environment).yaml"\n\n print $"Generated config for ($app_name) v($version) in ($environment)"\n}\n\n# Bulk configuration generation\ndef generate-all-configs [] {\n let apps = [\n {name: "web-service", version: "1.2.3"}\n {name: "api-service", version: "2.1.0"}\n {name: "worker-service", version: "1.5.2"}\n ]\n\n let environments = ["dev", "staging", "prod"]\n\n $apps | each { |app|\n $environments | each { |env|\n generate-app-config $app.name $app.version $env\n }\n }\n}\n\n# Configuration diff and comparison\ndef compare-configs [env1: string, env2: string] {\n print $"Comparing ($env1) vs ($env2) configurations..."\n\n let config1 = (kcl-run $"environments/($env1).k" -f json | from json)\n let config2 = (kcl-run $"environments/($env2).k" -f json | from json)\n\n # Find differences in configuration keys\n let keys1 = ($config1 | columns)\n let keys2 = ($config2 | columns)\n\n let only_in_env1 = ($keys1 | where $it not-in $keys2)\n let only_in_env2 = ($keys2 | where $it not-in $keys1)\n\n if ($only_in_env1 | length) > 0 {\n print $"Keys only in ($env1): ($only_in_env1 | str join ', ')"\n }\n\n if ($only_in_env2 | length) > 0 {\n print $"Keys only in ($env2): ($only_in_env2 | str join ', ')"\n }\n\n print "Configuration comparison complete"\n}\n\n\n### Advanced KCL Patterns\n\nnushell\n# Modular configuration management\ndef build-modular-config [base_config: string, modules: list<string>, output: string] {\n # Combine base configuration with modules\n let module_imports = ($modules | each { |m| $"-Y ($m)" } | str join " ")\n\n kcl-run $base_config $module_imports -f yaml | save $output\n print $"Built modular configuration: ($output)"\n}\n\n# Configuration validation with custom rules\ndef validate-with-rules [config_file: string, rules_file: string] {\n try {\n kcl-run $config_file -Y $rules_file\n print $"✅ ($config_file) passes all validation rules"\n true\n } catch { |err|\n print $"❌ ($config_file) validation failed: ($err.msg)"\n false\n }\n}\n\n# Generate documentation from KCL schemas\ndef generate-config-docs [schema_dir: string] {\n ls $"($schema_dir)/*.k"\n | each { |schema|\n let schema_name = ($schema.name | path basename | str replace '.k' '')\n print $"## ($schema_name | str title-case)"\n print ""\n\n # Extract schema documentation (would need KCL introspection)\n # This is a simplified example\n open $schema.name | lines | each { |line|\n if ($line | str starts-with "# ") {\n $line | str replace "# " ""\n }\n } | str join "\n"\n\n print ""\n }\n}\n\n\n## Integration with Nushell Data Processing\n\nLeverage Nushell's powerful data manipulation with KCL configuration management:\n\nnushell\n# Process and generate configurations from CSV data\n> open services.csv\n | each { |service|\n kcl-run service-template.k -D name=$service.name -D port=$service.port -f yaml\n | save $"configs/($service.name).yaml"\n }\n\n# Combine multiple data sources for configuration\n> let infrastructure = (sys)\n> let settings = (open settings.json)\n> {\n infrastructure: $infrastructure,\n settings: $settings,\n timestamp: (date now | format date "%Y-%m-%d %H:%M:%S")\n } | to json | save runtime-config.json\n> kcl-run dynamic-config.k -Y runtime-config.json\n\n# Batch process and validate configurations\n> ls configs/*.k\n | par-each { |config|\n let result = (kcl-validate $config.name)\n {\n file: $config.name,\n valid: ("✅" in $result),\n result: $result\n }\n }\n | where valid == false\n\n\n## Error Handling\n\nThe plugin provides detailed error messages for common issues:\n\nnushell\n# Syntax errors in KCL files\n> kcl-run broken-config.k\nError: Error executing KCL\n ╭─[calling kcl-run]\n │ KCL syntax error: unexpected token at line 5\n\n# Missing files\n> kcl-run nonexistent.k\nError: Error executing KCL\n ╭─[calling kcl-run]\n │ File not found: nonexistent.k\n\n# Validation errors\n> kcl-validate invalid-project/\n❌ Validation failed in invalid-project/\n - main.k: schema validation error\n - config.k: undefined variable 'missing_var'\n\n\n## Features\n\n- ✅ KCL Execution - Run KCL files with variable substitution and output formatting\n- ✅ Code Formatting - Automatic KCL code formatting according to standards\n- ✅ Project Validation - Comprehensive validation of KCL projects and files\n- ✅ Variable Support - Dynamic configuration through command-line variables\n- ✅ Multiple Formats - Support for YAML and JSON output formats\n- ✅ Settings Integration - Include external setting files in KCL execution\n- ✅ Error Reporting - Detailed error messages with context\n- ✅ Nushell Integration - Seamless data flow between Nushell and KCL\n\n## Use Cases\n\n- Infrastructure as Code: Manage Kubernetes, Terraform, and cloud configurations\n- Configuration Management: Environment-specific application configurations\n- Policy as Code: Define and enforce organizational policies\n- CI/CD Pipelines: Validate and generate configurations in automated workflows\n- Multi-Environment Deployments: Consistent configurations across environments\n- Schema Validation: Ensure configuration correctness with KCL schemas\n- Template Generation: Dynamic configuration templates with variable substitution\n- Compliance Management: Configuration compliance checking and reporting\n\n## Best Practices\n\n### 1. Organize KCL Projects\n\nplaintext\nproject/\n├── schemas/ # Reusable schemas\n│ ├── app.k\n│ ├── database.k\n│ └── server.k\n├── environments/ # Environment-specific configs\n│ ├── dev.k\n│ ├── staging.k\n│ └── prod.k\n├── templates/ # Configuration templates\n│ └── service.k\n├── settings/ # External settings\n│ └── common.yaml\n└── output/ # Generated configurations\n ├── dev/\n ├── staging/\n └── prod/\n\n\n### 2. Use Schema-Driven Development\n\nkcl\n# Define schemas first\nschema AppConfig:\n name: str\n version: str\n replicas: int\n\n check:\n 1 <= replicas <= 100, "replicas must be between 1 and 100"\n len(name) > 0, "name cannot be empty"\n\n# Then implement configurations\nconfig: AppConfig = {\n name = "my-app"\n version = "1.0.0"\n replicas = 3\n}\n\n\n### 3. Create Reusable Functions\n\nnushell\n# KCL helper functions\ndef kcl-dev [config: string] {\n kcl-run $config -D environment=dev -f yaml\n}\n\ndef kcl-prod [config: string] {\n kcl-run $config -D environment=prod -Y settings/prod.yaml -f yaml\n}\n\n# Validation helpers\ndef validate-project [dir: string = "."] {\n kcl-validate $dir\n}\n\ndef format-all-kcl [] {\n ls **/*.k | each { |file| kcl-format $file.name }\n}\n\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues, feature requests, or pull requests.\n\n## License\n\nThis project is licensed under the MIT License.\n\n## Related Projects\n\n- KCL - Kubernetes Configuration Language\n- Nushell - A new type of shell\n- nu_plugin_tera - Tera templating plugin for Nushell\n- nu_plugin_fluent - Fluent localization plugin for Nushell