YINI CLI

The official CLI for validating, inspecting, and converting YINI configuration files to JSON or JavaScript, maintained by the YINI-lang project.

YINI is an INI-inspired, human-readable configuration format with explicit structure, nested sections, comments, and predictable parsing.

YINI is intended to emphasize clarity, readability, explicit structure, predictability, and deterministic parsing, while remaining simple, but not simplistic.

Quick Start

Requirements

YINI CLI requires Node.js v20 or later.

Installation

1. Install globally from npm — (requires Node.js)
   Open your terminal and run:

   npm install -g yini-cli

2. Verify installation
   Run this in your terminal:

   yini --version

   This should print the installed version.

   Then try:

   yini --help

   This should show the CLI help.

3. Test functionality
   Create a simple test file, for example: config.yini:

   ^ App
   name = "My App Title"
   version = "1.2.3"
   pageSize = 25
   darkTheme = off

   Then run:

   yini parse config.yini

   Expected output:

   {
       "App": {
           "name": "My App Title",
           "version": "1.2.3",
           "pageSize": 25,
           "darkTheme": false
       }
   }    

Typical use cases

• Validating configuration files during development or CI.
• Inspecting and debugging structured configuration.
• Converting YINI files to JSON for tooling and automation.

What YINI looks like

A basic YINI configuration example, showing a section, nested section, comments:
Source: basic.yini

A larger example

A real-world YINI configuration example, showing sections, nesting, comments, and multiple data types:
Source: config.yini

YINI characteristics

• Indentation-independent structure: YINI is indentation-independent — whitespace never alters structural meaning.
• Explicit nesting: Section markers such as ^, ^^, and ^^^ define hierarchy explicitly.
• Multiple data types: Supports booleans (true / false, yes / no, etc.), numbers, lists, and inline objects, with explicit string syntax.
• Comment support: YINI supports multiple comment styles (#, //, /* ... */, and ;) for documenting configuration directly in the file.
• Predictable parsing: Well-defined rules with optional strict and lenient modes for different use cases.

Usage

Quick Examples

yini parse config.yini

→ Parse and print formatted JSON (default).

yini parse config.yini --compact

→ Output compact JSON (no whitespace).

yini parse config.yini --js

→ Output as JavaScript-style object.

yini parse config.yini -o out.json

→ Write formatted JSON to a file.

yini validate --strict config.yini

→ Validate using strict mode.

For help with a specific command:

yini parse --help

Why YINI?

YINI is intended for configuration files where human readability, explicit structure, and predictable parsing are more important than minimal syntax or maximum flexibility.

Compared with common configuration formats:

• INI: YINI supports clearer nested sections and typed values.
• JSON: YINI supports comments and is easier to edit by hand.
• YAML: YINI does not use indentation to define structure.
• TOML: YINI uses explicit section markers for hierarchy instead of dotted table names.

The same small configuration can be written in several formats:

YINI

^ Application
name = 'demo'
environment = 'dev'

^^ Server
host = 'localhost'
ports = [8080, 8081]

^^^ TLS
enabled = true
mode = 'optional'

• Application contains the top-level application settings.
• Server is nested under Application.
• TLS is nested under Server.
• The section markers ^ make the nesting explicit. Indentation is optional and not required for structure.
• Strings can use either ' or ".

JSON

{
  "Application": {
    "name": "demo",
    "environment": "dev",
    "Server": {
      "host": "localhost",
      "ports": [8080, 8081],
      "TLS": {
        "enabled": true,
        "mode": "optional"
      }
    }
  }
}

YAML

Application:
  name: demo
  environment: dev
  Server:
    host: localhost
    ports:
      - 8080
      - 8081
    TLS:
      enabled: true
      mode: optional

TOML

[Application]
name = "demo"
environment = "dev"

[Application.Server]
host = "localhost"
ports = [8080, 8081]

[Application.Server.TLS]
enabled = true
mode = "optional"

YINI may not be the right choice when you need mature ecosystem support, existing schema tooling, or maximum compatibility with infrastructure that already expects JSON, YAML, or TOML. The format and parser are still alpha-stage and best suited for testing, experiments, and early integration feedback.

Feedback and bug reports

If you find a problem, please open an issue on GitHub:

• Report a bug or issue

When reporting parser behavior, it is helpful to include:

• The YINI input that caused the issue.
• The command and options used.
• The expected result.
• The actual result or error message.
• The installed yini-cli version.
• The Node.js version used.
• The operating system and version used.

A closer look at YINI

Here's a small example showing YINI structure and comments:

    // This is a comment in YINI

    ^ App                      // Defines section (group) "App" 
      name     = 'My Title'    // Keys and values are written as key = value
      items    = 25
      darkMode = true          // "ON" and "YES" works too

        // Sub-section of the "App" section
        ^^ Special
           primaryColor = #336699   // Hex number format
           isCaching    = false     // "OFF" and "NO" works too
    
    # This is a comment too.

The above YINI as a JavaScript object:

{
    App: {
        name: 'My Title',
        items: 25,
        darkMode: true,
        Special: { 
            primaryColor: 3368601,
            isCaching: false
        }
    }
}

In JSON:

{
   "App":{
      "name":"My Title",
      "items":25,
      "darkMode":true,
      "Special":{
         "primaryColor":3368601,
         "isCaching":false
      }
   }
}

• YINI Homepage.
• YINI Demo Apps with usage examples.

📤 Output Modes for yini parse

The parse command supports multiple output formats:

| Command Example | Output Format | Description | |------------------------------------------|----------------------|------------| | yini parse config.yini | Pretty JSON (default) | Formatted JSON with indentation (4 spaces). | | yini parse config.yini --json | Pretty JSON | Explicit pretty JSON output. | | yini parse config.yini --compact | Compact JSON | Minified JSON (no whitespace). | | yini parse config.yini --js | JavaScript object | JavaScript-style object (unquoted keys, single quotes). | | yini parse config.yini -o out.json | File output | Writes formatted JSON to file (default format). |

--js and --compact are mutually exclusive.
--output can be combined with a style flag to control both formatting and destination.

Output File Handling

When using -o, --output <file>, YINI CLI applies safe write rules:

| Scenario | Result | |----------|--------| | File does not exist | File is written | | File exists and is older than the input YINI file | File is overwritten | | File exists and is newer than the input YINI file | Skipped by default | | File exists and output content is unchanged | Skipped | | --overwrite is used | File is always overwritten | | --no-overwrite is used | Command fails if file exists |

This helps avoid overwriting newer generated files and avoids rewriting unchanged output unnecessarily.

Use --overwrite to force replacement.

Links

• ➡️ YINI Homepage
  Tutorials, guides, and examples.

• ➡️ Read the YINI Specification
  Full syntax and format reference.

• ➡️ YINI Parser on npm
  The TypeScript/Node.js parser used by this CLI.

• ➡️ Demo Apps
  Complete basic usage examples.

• ➡️ YINI-lang Project
  Repositories and related ecosystem projects.

Contributing

Bug reports, feedback, and contributions are welcome.

GitHub Issues and Discussions are available for feedback and project discussion.

License

This project is licensed under the Apache License 2.0 — see the LICENSE file for details.

^YINI ≡

YINI is a human-readable configuration format designed for clarity, readability, explicit structure, predictability, and deterministic parsing.

See the specification for syntax and format details.

yini-lang.org · YINI-lang on GitHub