Confµgami User Manual

Confµgami makes a configuration file something your editor understands. A product’s author provides a model of it: which properties exist, what values they accept, in which unit, and what each one means.

This manual covers IDE setup, CLI usage, and configuration file authoring. The rest of this page walks you through your first configuration file: you find the definition it belongs to, write the file, and get validation feedback.

What a Configuration Developer Works With

Confµgami has two main file types:

  • A definition file (.def.json5) describes the configuration schema model (definition): which elements could exist, their types, value ranges, and documentation. You receive definitions from the author of the software component you configure.

  • A configuration file (.cfg.json5) holds the actual configuration data. This is the file you write.

Everything your editor offers you, completion, hover documentation, value range checks, comes from the definition. When in doubt about what a property means or which values are allowed, the definition is the authoritative answer.

How the Pieces Fit Together

One definition, any number of configuration files, one merged result:

  TurnIndicator.def.json5        schema model (definition)
          |   bound by name: $definition: "TurnIndicator@1.0"
          |
          v
  platform.cfg.json5  +  project.cfg.json5  +  generated.cfg.json5
          |
          |   merged per CfgSpace, by entity identity and file priority
          v
  the merged configuration

Four consequences follow:

  • Files find each other through the workspace, a directory tree Confµgami scans for .def.json5 and .cfg.json5 files.

  • Whether you can split your configuration across several files is the definition’s decision. A definition declares, if the configuration can be split

  • Errors are reported for the individual file, but required values and counts are checked on the merged result.

  • Everything the IDE shows you, and everything cfu checks, comes from the same engine, so the CLI and the editor never disagree.

Single-file configurations need none of the merging machinery. Start with How Configuration Files Work and Writing Values, and come back to the merging chapters when a second file appears.

What Confµgami Gives You

Capability What it means

Plain files

JSON5 text with comments and trailing commas, in your version control, readable and diffable without the tool.

Typed configuration model

Every property has a type, declared once in the definition.

Enforced conventions

Every definition author is held to the same naming rules, so a definition from another team or vendor reads like the last one you configured.

Origin Tracing

Confµgami records for every value which file and line it came from.

Editor support

IDE support from the definition, and accepting a key inserts the whole required structure with defaults filled in.

Configuration split across teams

Platform, project and generated files contribute to the same entities, and a priority ladder decides which one wins.

Reuse and validated wiring

A mixin applies one block of data to the elements a selector picks out, and a reference is a checked configuration link.

Documentation and annotations

Descriptions, comments and definition-declared annotation types travel with the configured elements through merging and export.

Deprecation with migration

A deprecated element warns in the configuration using it and carries its replacement.

Multiple Projects side by side

CfgSpaces hold several projects in one workspace without their names, references or merges leaking into each other.

Generated code

Generated Rust and Python bindings and JSON Schemas.

One engine everywhere

The IDE, cfu, the CI job and the MCP server report the same diagnostics from the same model.

See Compared with Other Configuration Formats for a details comparison of Confµgami with other plain text formats and the configuration systems.

Prerequisites

  • The cfu executable on your PATH, it is part of your delivery.

  • Any editor. For the full experience use an IDE with the Confµgami integration, see Setting Up the IDE.

Step 1: Find the Definition

Configuration files bind to a definition by name, not by file path. List the definitions available in your workspace:

cfu workspace list

The output shows the workspace roots, CfgSpaces, and the tree of discovered definition and configuration files. cfu tui shows the same information, plus the configurations and the diagnostics, in an interactive terminal UI, see the CLI reference. For this chapter we use the TurnIndicator definition, which models the turn indicator function of a body ECU:

{
    $definitionSpecVersion: "1.0",
    definitionName: "TurnIndicator",
    definitionVersion: "1.0",
    configurationFileMode: "SingleFile",
    title: "Turn indicator",
    description: "Turn indicator function configuration of a body ECU.",
    definition: {
        indicator: {
            title: "Turn indicator function",
            description: "Settings of the direction indicator flasher.",
            multiplicity: "1..1",
            entity: {
                flashFrequency: {
                    title: "Flash frequency",
                    description: "How often the indicator lamps flash per second.",
                    multiplicity: "1..1",
                    u8: {
                        min: 1,
                        max: 3,
                        unit: "Hz"
                    }
                },
                dimmingLevel: {
                    description: "PWM duty cycle for the indicator lamps in percent.",
                    u8: {
                        min: 0,
                        max: 100,
                        default: 100,
                        unit: "%"
                    }
                },
                comfortMode: {
                    description: "Behavior when the driver tips the indicator stalk.",
                    enum: {
                        literals: [
                            "OFF",
                            "THREE_FLASHES",
                            "FIVE_FLASHES"
                        ],
                        default: "THREE_FLASHES"
                    }
                }
            }
        }
    }
}

Reading a definition takes a moment of practice, but the essentials for a configuration author are:

  • The property names (indicator, flashFrequency, …​) are the keys you write in your configuration.

  • multiplicity: "1..1" means required exactly once. Omitted multiplicity means optional ("0..1").

  • The type block (u8, enum) states the allowed values: flashFrequency is an integer from 1 to 3, comfortMode one of three literals.

  • A default applies when you leave the property out.

Step 2: Write the Configuration

Create a file named TurnIndicator.cfg.json5. The base name is your choice; the .cfg.json5 suffix is what makes it Confµgami configuration file. The suffix is required.

{
    $definition: "TurnIndicator@1.0",
    indicator: {
        name: "FrontLeft",
        flashFrequency: 2,
        comfortMode: "THREE_FLASHES",
        // dimmingLevel is omitted: the default 100 from the definition applies
    }
}

  • $definition binds the file to the definition by name, with the definition version appended after an @. Without it the file cannot be validated, and the version is required: a mismatch after a definition update is reported as an error.

  • name gives the entity its identity. It is used in references and, when a definition allows merging, to match the same entity across files.

  • flashFrequency is required; dimmingLevel is omitted and gets its default of 100.

.cfg.json5 configuration files are JSON5: comments, trailing commas, and unquoted keys are all allowed.

Step 3: Validate

cfu cfg validate

cfu discovers all configuration files under the current directory, validates each against its definition, and reports errors and warnings in the file. Try setting flashFrequency to 9: you get an error pointing at the value, because the definition allows at most 3.

For continuous feedback add -t, which re-validates whenever a file changes:

cfu cfg validate -t

In an IDE with the Confµgami extension you get the same diagnostics inline as you type, plus completion for property names, enum literals, and reference paths.

Step 4: Confirm the File Was Discovered

A validation run only checks the files it found. If your file is outside the workspace, or hidden by discovery settings, cfu cfg validate happily reports success without ever reading it. After creating a new file, run cfu workspace list once and check that it appears in the discovered file tree. Workspace & Projects explains how discovery works.

Where to Go from Here

  • How Configuration Files Work: file types, binding to a definition, and the validation flow.

  • Workspace & Projects: workspace discovery, .confu files, CfgSpaces, and how to lay out a workspace. Read this when a file is not validated, or not found at all.

  • Writing Values: the syntax for every element type, entities, lists, unions, and references. Read this while writing your first files.

  • Working with Multiple Files: splitting a configuration across files, merging, fragments, and priorities. Read this as soon as a second file configures the same definition.

  • Reusing Content with Mixins: writing a block of settings once and applying it to the elements a selector picks out. Read this when the same settings repeat across elements.

  • Descriptions, Comments, and Annotations: free text and typed metadata that travel with the data.

  • Feature Interactions: covers how features interact with each other.

  • Pitfalls: the mistakes that actually happen, with the diagnostic each one produces.

  • Reference Manual: the glossary plus lookup tables for the $ keys, value syntax, and file types.