Installation

Installing Riot starts with the public install path from riot.ml:

curl -sSL https://get.riot.ml | sh

That only counts as a successful installation if the full workspace loop can start after that.

Quick StartTake a fresh workspace from scaffold to build, run, test, and docs.Editor SetupConnect VS Code or Neovim to the same toolchain assumptions the CLI uses.riot initStart from an empty Riot workspace when you want to understand the default shape directly.riot runBootstrap starter apps and run package targets through the normal Riot model.

By the end of this page you should be able to do four things:

1. invoke the CLI
2. materialize the declared compiler toolchain
3. create or bootstrap a real workspace
4. build and run at least one package successfully

Step 1: install the Riot CLI

Run the installer:

curl -sSL https://get.riot.ml | sh

The installer puts the Riot binary on your machine. The next step is to make sure your shell can actually see it.

Step 2: verify the CLI is there

The first verification should be boring and deterministic:

riot --help

If that does not work, the rest of the toolchain discussion is premature.

You can also use:

riot --version

but riot --help is a better first smoke test because it proves the command surface is available instead of only checking that a binary exists somewhere on PATH.

Step 3: materialize the compiler toolchain

Once the Riot binary is visible, make sure it can also install the compiler toolchains the workspace expects:

riot toolchain install

This matters because Riot is not just a front-end to whatever random compiler happens to be lying around on the machine. It wants a declared toolchain story.

Step 4: choose the first project path

There are two good first-project paths.

Path A: bootstrap a starter app

If you want the fastest path to a working Riot application, use the starter app entrypoint that the public Riot site points new users toward:

riot run leostera/create-riot-app

That path is good when you want to see Riot with batteries included instead of starting from a bare workspace.

Path B: start from an empty workspace

If you want to learn the raw Riot project shape, initialize a workspace directly:

riot init hello
cd hello

This path is better when you want to understand what Riot expects a package and workspace to look like.

Step 5: prove the workflow with a real package

The fastest real verification is:

riot build
riot run hello
riot test
riot doc

If you used the starter app path instead of riot init, run the same loop inside the generated workspace, replacing hello with the package or app target that the scaffold created.

That sequence is better than a shallow version check because it proves:

• scaffolding or bootstrapping works
• the compiler path works
• the build planner works
• binaries run
• the test runner is wired
• docs can be generated from public interfaces

What usually goes wrong

Installation issues tend to cluster into a few categories:

• the Riot binary is not actually on PATH
• the workspace cannot fetch or materialize toolchains
• the shell environment is different between interactive use and scripted use
• the editor is pointed at the wrong root even though the CLI works

The right response is to verify the system in layers:

1. binary
2. toolchain
3. workspace
4. editor

After installation

The normal next pages are:

• Quick Start
• Editor Setup
• riot init
• riot run
• ocaml-toolchain.toml and riot toolchain

Those pages turn the installation from a one-time setup step into a repeatable daily workflow.