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.

Homebrew (macOS)

On macOS, the easiest installation method is via Homebrew:

brew install ossuminc/tap/riddlc

This installs the latest release and manages updates automatically. To upgrade later:

brew upgrade riddlc

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 RIDDL:
[info]            name: utils
[info]         version: 1.2.1
[info]   documentation: https://github.com/ossuminc/riddl
[info]       copyright: © 2019-2026 Ossum, Inc.
[info]        built at: 2026-02-01 23:24:51.835-0500
[info]        licenses: Apache-2.0
[info]    organization: Ossum, Inc.
[info]   scala version: 3.7.4
[info]     sbt version: 1.12.0
[info]        jvm name: OpenJDK 64-Bit Server VM
[info]     jvm version: 21.0.10
[info]   operating sys: Mac OS X

Next Steps