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 just a few minutes. Learn how to install and use YINI from the terminal or command line (CLI).

YINI is a human-friendly data format — like INI, but with nested sections, comments, lists (arrays), and objects. It is suitable for configuration files, application settings, and general data-storage use cases.

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.
• 📦 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

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

💡 You can use either npx yini (no install), or just yini if yini-cli is 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:

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 Downloads.

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: Intro to 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, type the following:

npx yini-cli parse config2.yini

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

yini parse config2.yini

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) Other output styles

4.1) Results in JSON

If you want the output in pure JSON, use the --json flag.

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

npx yini-cli parse --json config2.yini

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

yini parse --json config2.yini

JSON Output:

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

4.2) Results in pretty JSON

If you want the output in pretty JSON so it’s easier to read, use the --pretty flag.

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

npx yini-cli parse --pretty config2.yini

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

yini parse --pretty config2.yini

Pretty JSON Output:

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

💡 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.

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

• ▶️ Quick Tutorial — 5-minute guided walkthrough of YINI.
• ➡️ YINI Examples
  Shows YINI configuration examples.