Skip to content

Installing riddlc

This guide covers the various ways to install riddlc on your system.

Download a Release

The easiest way to get started is to download a pre-built release:

  1. Go to GitHub Releases
  2. Download the .zip asset for your platform (under "Assets")
  3. Unpack the archive: 
    unzip riddlc-*.zip
  4. Add the bin directory to your PATH: 
    export PATH="$PATH:$(pwd)/riddlc-*/bin"
  5. Verify installation: 
    riddlc version

Note

Not all releases include pre-built assets. If no asset is available for your desired version, you'll need to build from source.

Build from Source

Building from source requires JDK 25 and sbt.

Prerequisites

Install JDK 25:

brew install --cask temurin

Follow Adoptium installation instructions

Download from Adoptium and run the installer

Install sbt:

brew install sbt

Follow sbt setup instructions

Build Steps

# Clone the repository
git clone https://github.com/ossuminc/riddl.git
cd riddl

# Compile and stage the executable
sbt "riddlc/stage"

# The executable is now at:
# riddlc/jvm/target/universal/stage/bin/riddlc

Add to PATH

Add the staged executable to your PATH:

export PATH="$PATH:$(pwd)/riddlc/jvm/target/universal/stage/bin"

For permanent installation, add this to your shell profile (.bashrc, .zshrc, etc.).

Create Universal Package

To create a portable package you can distribute:

sbt "project riddlc" "universal:packageBin"

This creates a .zip file in riddlc/target/universal/ that can be unpacked on any system with a compatible JVM.

Verify Installation

After installation, verify that riddlc is working:

riddlc info

You should see output like:

[info] About riddlc:
[info]            name: riddlc
[info]         version: 1.1.2
[info]   documentation: https://riddl.tech
[info]       copyright: © 2019-2026 Ossum Inc.
[info]        licenses: Apache License, Version 2.0
[info]    organization: Ossum Inc.
[info]   scala version: 3.3.7

Next Steps