Getting Started with Qilletni

Welcome to Qilletni, a Domain-Specific Language (DSL) designed for advanced playlist management, music curation, and seamless integration with Spotify and Java libraries.

Introduction

Qilletni simplifies the creation and manipulation of playlists and music data, allowing you to automate tasks, integrate with external libraries, and leverage a rich standard library. If you’d like a broader overview of Qilletni, see the Home page for more details.

Installation

Start Database

Qilletni leverages a database for caching music data for efficient lookups and conversions. The easiest way to start a caching database is via docker, using a command such as:

docker run -d \
  --name qilletni-db \
  -p 5435:5432 \
  -e POSTGRES_USER=qilletni \
  -e POSTGRES_PASSWORD=pass \
  -e POSTGRES_DB=qilletni \
  -v ~/.qilletni/cache:/var/lib/postgresql/data \
  postgres

Install Qilletni

There are two ways to use Qilletni. You may install it on your system, or use the Docker image. A normal system install is recommended (everything is put under ~/.qilletni), but a Docker install is great for trying things out.

Install on System

A system install requires Java 22 or newer. The installer checks for it, preferring $JAVA_HOME and falling back to whatever java is on your PATH.

curl -L https://install.qilletni.dev/ | bash

This installs the commands qilletni and qpm, which are the primary toolchain and the Qilletni Package Manager (QPM) respectively. This also installs qilletni-up, which manages the install itself. Everything goes under ~/.qilletni, and each download is verified against the SHA-256 recorded in the release's platform manifest.

Then open a new shell, or run:

source ~/.qilletni/env

The installer adds that line to your shell profile automatically, for bash and zsh. On other shells, add ~/.qilletni/bin to your PATH yourself.

From there, you can run qilletni --help or qpm --help for a list of commands.

Updating

qilletni-up update

This installs the newest published version and switches to it in one step. Your installed packages and credentials are untouched. To pin a specific version instead, pass it to install:

qilletni-up install 1.0.0

Run qilletni-up status to see what you currently have.

Uninstalling

qilletni-up uninstall

This removes the toolchain, QPM and the lines added to your shell profile. It then asks whether to also delete your ~/.qilletni user data — your qpm credentials and installed packages — and keeps that data if you decline or if it is running non-interactively. Use qilletni-up uninstall --purge to remove everything without being asked.

Use with Docker

The image bundles its own Java runtime, so nothing needs to be installed first. To use it, run the following:

docker run --rm \
  --network host \
  -v "/$(pwd)":/workspace \
  -v qilletni-packages:/root/.qilletni/packages \
  ghcr.io/qilletni/qilletni:latest \
  qilletni --help

Which is equivalent to running qilletni --help. QPM is also accessible through this image.

To run a file, it's recommended to cd into the parent directory of the file and run it from there. For example, to run /e/qilletni/demo.ql you would do, from the /e/qilletni directory,

docker run --rm \
  --network host \
  -v "/$(pwd)":/workspace \
  -v qilletni-packages:/root/.qilletni/packages \
  ghcr.io/qilletni/qilletni:latest \
  run demo.ql

Hello World (Your First Program)

Let’s create a simple "Hello, World!" program:

Initialize a project Create a project directory, and then run the command

qilletni init --name qilletni_demo

It will ask you for a project name, and the author's name. In this case, we'll give it the name qilletni_demo. It will also ask for an optional native binding class name, which may be left blank for now.

This will create a file tree of the following structure:

qilletni_demo/
└── qilletni-src/
    ├── qilletni_demo.ql
    ├── qilletni.lock
    └── qilletni_info.yml

The file created, qilletni_demo.ql, is the start of your source code. Right now, it only contains:

qilletni_demo.ql

print("Hello, World!")

A more in-depth explanation of the project structure, and other project types, can be found in the Project Structure guide.

Run the program via command line:

qilletni run qilletni-src/qilletni_demo.ql

If everything is set up correctly, you should see:

Hello, World!

Next Steps

Now that you have a Qilletni program running, it's time to link a music service. Check out the Spotify or Last.fm pages for more info. If you've done that, feel tree to check out the Language Introduction or some of the official packages.

For making and using packages in Qilletni, navigate to Package Management.