Get Started with YINI

💡 This guide focuses on working with YINI via the terminal (CLI). There are other tools available as well.

Welcome! This guide helps you create your first working .yini file in under 2 minutes. Learn how to install and use YINI from the terminal or command line (CLI).

YINI is a human-friendly configuration file format inspired by INI, extended with nested sections, arrays, objects, and comments.

Ways to get started with YINI

You can use YINI in a few different ways:

  • 🧰 Command line (CLI) — the easiest and fastest way to explore YINI.
  • 📦 Node.js library — embed YINI parsing directly into your application.
  • 🌍 Other tools & platforms — see available downloads and integrations.

This guide focuses on the CLI, which is the best starting point for most users.

What can I do with YINI?

Build, convert, and consume structured configuration and data using simple tools.

  • 🛠  Convert YINI → JSON via CLI. (Can export parsed data as YAML, XML, JS too.)
  • 📦 Load YINI into your app as native objects.
  • 🧩 Use YINI for configuration, data files, pipelines, and tooling.

Prerequisite: Node.js

Node.js is required to run the YINI command-line (CLI) tool.

💡 Tip: You can check if Node.js is already installed by running:

node -v

If Node.js is not installed, download it from: https://nodejs.org ↗

It’s recommended to use Node.js 20 or later.

1) Install yini-cli (or just use npx)

Option A — use without installing

npx yini-cli --help

Option B — enable yini CLI globally

npm i -g yini-cli

Option C — add the CLI to your Node.js project

npm i -D yini-cli

💡 By default, yini parse prints formatted JSON to the terminal.

After installing, you can run npx yini-cli or add an npm script like “yini”: “yini”.

You can use npx yini-cli (no installation) or yini if installed globally or locally.

Optional: Use YINI as a Node.js library

If you’re integrating YINI into an application, you can install the official Node.js parser (repo here ↗):

npm i yini-parser

Then import and use it in your project (TypeScript example):

import YINI from 'yini-parser'

const config = YINI.parseFile('./config.yini')
console.log(config.server.port) // 8080

// Or with options
const options = {
    /* see docs for options */
}
const config2 = YINI.parseFile('./config.yini', options)

This lets your app load .yini files directly as JavaScript objects.

💡 You can explore more tools and integrations on the Get YINI Tools page.

2) Create your first .yini file

Save this as config2.yini:

^ App
  name = "Demo"
  version = "1.0.0"
  features = [ "search", "dark-mode" ]  // Comments are allowed

^ Database
  host = "localhost"
  port = 5432
  auth = { user: "admin", pass: "secret" }  // Object literal

Notes:

  • Sections: start with ^. Add more carets for nesting (sub-sections): (^, ^^, ^^^, …).
  • Members: written as key = value pairs.
  • Comments: Use // or # (including a space after the hash) for inline comments.
  • Arrays: [1, 2, 'three']
  • Objects: { key: 'value', n: 1 }
  • Strings: must be quoted 'like this' or "like this".
  • For more details, see: Learn the YINI format.

💡 Coming from INI? YINI keeps the same familiar key-value style but adds nesting, lists, and objects without changing how basic configs look.

3) Parse your .yini file

Once your file is saved, parse it with the CLI:

If you used option A (with npx) in step 1:

npx yini-cli parse config2.yini

Or, if you used option B or C in step 1:

yini parse config2.yini

JSON Output:

By default, parse outputs formatted JSON:

{
    "App": {
        "name": "Demo",
        "version": "1.0.0",
        "features": ["search", "dark-mode"]
    },
    "Database": {
        "host": "localhost",
        "port": 5432,
        "auth": { "user": "admin", "pass": "secret" }
    }
}

4) Output styles

4.1) Compact JSON

To output minified JSON (no whitespace):

If you used option A (with npx) in step 1, type the following:

npx yini-cli parse config2.yini --compact

Or, if you used option B or C in step 1:

yini parse config2.yini --compact

Output:

{"App":{"name":"Demo","version":"1.0.0","features":["search","dark-mode"]},"Database":{"host":"localhost","port":5432,"auth":{"user":"admin","pass":"secret"}}}

4.2) JavaScript-style output

To output a JavaScript-style object instead of JSON, use the --js flag.

If you used option A (with npx) in step 1, type the following:

npx yini-cli parse config2.yini --js

Or, if you used option B or C in step 1:

yini parse config2.yini --js

JS Output:

You should see output like (JavaScript Object):

{
  App: {
    name: 'Demo',
    version: '1.0.0',
    features: [ 'search', 'dark-mode' ]
  },
  Database: {
    host: 'localhost',
    port: 5432,
    auth: { user: 'admin', pass: 'secret' }
  }
}

4.3) Explicit JSON flag

You can also explicitly request formatted JSON:

yini parse config2.yini --json

This is equivalent to the default behavior.

5) Write output to a file

To save the result:

yini parse config2.yini -o output.json

YINI CLI protects you from accidentally overwriting newer files.

By default, output is written only if:

  • It does not already exist, or
  • it is older than the source .yini file.

You can control overwrite behavior:

--overwrite     # Always replace existing file
--no-overwrite  # Never replace existing file

💡 Common tips:

  • Keys and section names are case-sensitive.
  • Strings must always be quoted, either ' or ".

Summary

✅ You have just created and parsed your first YINI configuration file.

You now know how to:

  • Install YINI CLI
  • Create a structured .yini file
  • Parse it to JSON or JavaScript
  • Safely write output to disk

From here, you can:

  • continue using YINI via the CLI,
  • embed it directly in your Node.js applications, or
  • explore additional tools and platforms.

🧭 Next Steps