Skip to content

Command Flags Reference ​

This page provides comprehensive documentation for all Konfigo command-line flags and options.

Command-Line Interface ​

Global Options ​

FlagDescriptionDefault
-hShow help message-
-vEnable informational (INFO) loggingfalse
-dEnable debug (DEBUG + INFO) logging, overrides -vfalse
-cUse case-sensitive key matchingfalse (case-insensitive)
-mMerge arrays by union with deduplicationfalse (arrays replaced)
-rRecursively search subdirectoriesfalse

Source Input Options ​

FlagDescriptionNotes
-sComma-separated list of source files/directoriesRequired. Use - for stdin
-sjForce input parsing as JSONRequired for stdin
-syForce input parsing as YAMLRequired for stdin
-stForce input parsing as TOMLRequired for stdin
-seForce input parsing as ENVRequired for stdin

Schema Processing Options ​

FlagLong FormDescriptionNotes
-S--schemaPath to schema fileJSON, YAML, or TOML only
-V--vars-filePath to variables fileHigh-priority variable definitions

Output Format Options ​

FlagDescriptionNotes
-ojOutput in JSON format-
-oyOutput in YAML formatDefault when no format specified
-otOutput in TOML format-
-oeOutput in ENV format-
-ofWrite output to fileExtension determines format

Environment Variables ​

Runtime Configuration Overrides ​

Variable PatternDescriptionExample
KONFIGO_KEY_*Override any configuration key (highest precedence, but subject to immutable paths)KONFIGO_KEY_app.port=8080
KONFIGO_VAR_*Define schema variables (highest variable precedence)KONFIGO_VAR_DATABASE_HOST=prod-db.com

Exit Codes ​

CodeMeaningDescription
0SuccessOperation completed successfully
1ErrorAny error (parsing, validation, file I/O, schema processing, etc.)

File Format Support ​

Input Formats ​

FormatExtensionsNotes
JSON.jsonStandard JSON (no comments)
YAML.yaml, .ymlSingle-document YAML
TOML.tomlFull TOML v1.0.0 support
ENV.envKEY=value pairs, # comments, dot notation for nesting
INI.iniSections become nested maps, input only

Output Formats ​

FormatNotes
JSONPretty-printed with 2-space indentation
YAML2-space indentation
TOMLStandard TOML with sections
ENVFlattened to UPPERCASE_UNDERSCORE=value, sorted keys, auto-quoting

INI is input-only; it cannot be used as an output format.

Error Handling ​

Common Error Patterns ​

  • File not found: Check file paths and permissions
  • Parse errors: Validate syntax with format-specific tools
  • Schema errors: Verify schema structure and required fields
  • Validation failures: Check data types and constraints

Debug Information ​

Use -v or -d flags to get detailed information about:

  • File discovery and loading
  • Merge order and precedence
  • Schema processing steps
  • Variable substitution
  • Validation results

Performance Considerations ​

File Size Limits ​

  • Configuration files are limited to 50 MiB each; larger files are rejected with an error
  • Schema files are limited to 10 MiB
  • Consider splitting large configurations into multiple files and merging

Memory Usage ​

  • Konfigo loads all source files into memory
  • Schema processing requires additional memory for transformations
  • Array union merging (-m) with very large arrays (>1,000 elements per side) automatically skips deduplication to avoid O(n*m) performance degradation

Integration Patterns ​

CI/CD Integration ​

bash
# Typical pipeline usage
konfigo -s base.yaml,env/${ENVIRONMENT}.yaml -S schema.yaml -of config.json

Container Integration ​

dockerfile
# Multi-stage build pattern
FROM golang:1.22 AS config-builder
COPY . /src
WORKDIR /src
RUN go build -o /usr/local/bin/konfigo ./cmd/konfigo
COPY configs/ /configs/
RUN konfigo -s /configs/base.yaml,/configs/prod.yaml -of /tmp/final.json

FROM alpine:latest
COPY --from=config-builder /tmp/final.json /app/config.json

Library Integration ​

Konfigo is designed as a CLI tool but can be integrated into build processes, deployment scripts, and configuration management workflows.

Schema Version ​

The apiVersion field in schema files is informational only. Konfigo does not enforce or validate this field. Common values used in the community:

  • konfigo/v1alpha1