Installation

Reqloom ships a CLI (reqloom) and a desktop app in the same archive. Download a build below, or build from source if you want to contribute.

Alpha software

Reqloom is pre-1.0. The schema format is stable enough to build on — it is versioned, and the loader accepts versions 1–3 — but expect rough edges in the desktop UI, and expect flags to gain options rather than lose them.

Download

Grab the latest build from the releases page.

Each release carries a macOS .dmg, a Linux .AppImage and .tar.gz, and a Windows -setup.exe.

Each platform gets two files. Take the first one unless you have a reason not to:

| Platform | Recommended | Alternative | | --- | --- | --- | | macOS | .dmg — drag to Applications | .zip — unpack anywhere | | Linux | .AppImage — single self-contained file | .tar.gz — unpack anywhere | | Windows | -setup.exe — installer | .zip — portable, no install |

First launch

The builds are not signed with a paid certificate and not notarized, so every OS will warn you the first time. This is expected for an alpha, and the steps below are the standard way through it. If you’d rather not bypass the warnings, build from source instead.

macOS

The app is ad-hoc signed, which prevents the misleading “Reqloom is damaged and can’t be opened” error — but macOS still blocks an unidentified developer on first launch.

1. Open the .dmg and drag Reqloom to Applications.

2. Right-click (or Control-click) Reqloom in Applications and choose Open. Using right-click → Open is what registers your consent; double-clicking will keep getting refused.

3. Confirm Open in the dialog. macOS remembers the decision, so later launches are normal.

If macOS still refuses, clear the download quarantine flag explicitly:

xattr -dr com.apple.quarantine /Applications/Reqloom.app

To put the CLI on your PATH:

sudo ln -sf /Applications/Reqloom.app/Contents/MacOS/reqloom \
            /usr/local/bin/reqloom

Linux

The AppImage needs the executable bit set, and nothing else:

chmod +x Reqloom-*-linux-x86_64.AppImage
./Reqloom-*-linux-x86_64.AppImage --help

On a minimal system (containers, slim server images) an AppImage may need FUSE:

sudo apt-get install -y libfuse2      # Debian / Ubuntu

Or skip FUSE entirely by extracting it:

./Reqloom-*.AppImage --appimage-extract
./squashfs-root/AppRun --help

To put the CLI on your PATH:

sudo install -m 755 Reqloom-*-linux-x86_64.AppImage /usr/local/bin/reqloom

Windows

The installer is unsigned, so SmartScreen shows “Windows protected your PC”.

1. Click More info.

2. Click Run anyway.

The installer adds the CLI to your PATH. Open a new terminal afterwards — an already-open one keeps the stale PATH.

Prefer no installer? Take the .zip, unpack it, and run reqloom.exe from the extracted folder.

Verify the download

Every asset is published with a SHA-256 digest, shown truncated next to each file above and in full on the release page. To check a download:

macOS

shasum -a 256 Reqloom-*-macos.dmg

Linux

sha256sum Reqloom-*-linux-x86_64.AppImage

Windows

Get-FileHash .\Reqloom-*-windows-x64-setup.exe -Algorithm SHA256

Check that it works

reqloom --help

You should see the three subcommands and their flags:

Reqloom CLI
  reqloom run <operation> [opts]   Execute a chain ending at <operation>
    --project <path>                Project directory (default: cwd)
    --env <name>                    Environment to run against
    --var KEY=VALUE                 Override an env variable (repeatable)
    --format text|json|junit        Output format (default: text)
    --output <file>                 Write rendered output to <file>
    --quiet                         Suppress live progress on stdout
  reqloom lint                     Validate the schema in current project
    --project <path>                Project directory (default: cwd)
  reqloom import <file>            Import an external API spec
    --out <dir>                     Directory to write the project (default: cwd)
    --project-root <dir>            Containment root the spec must resolve under
    --force                         Overwrite an existing reqloom.yaml
  reqloom --help                   Show this message

Then validate the bundled sample project, which exercises the parser and the dependency resolver without sending a single request:

git clone https://github.com/Mirzabaig313/Reqloom
reqloom lint --project Reqloom/samples/marketplace

LINT OK — 3 actors, 5 resources, 27 operations. No errors.

If you see that line, you’re set. The 5-minute tour runs the sample end to end next.

What you get

Every download contains both front ends:

• Reqloom (desktop) — the workbench. Project explorer, request editor, response inspection, dependency graph, step timeline, run history, and keychain secret storage. Start here if you’re building a schema. See Desktop app.
• reqloom (CLI) — for CI and scripting, with JSON and JUnit output. See CLI overview.

They share one engine and one schema format, so a project behaves identically in both. Most people build in the app and run in the CLI — which to use when.

To launch the desktop app, open it like any other application. The CLI needs to be on your PATH — see First launch for your platform.

Build from source

Needed if you’re contributing, or if you’re on a platform without a published build (Apple Intel is covered by the universal .dmg; ARM Linux is not).

Prerequisites

| Tool | Version | Notes | | --- | --- | --- | | CMake | 4.0+ | Most package managers still ship 3.x — see troubleshooting | | C++ compiler | Apple Clang 16+, Clang 18+, GCC 14+, MSVC 19.40+ | C++23 is required | | Qt | 6.8 LTS | Installed by tools/setup-qt.sh, not by your package manager | | vcpkg | manifest mode | Every dependency except Qt | | Ninja | any recent | Generator used by all presets |

Qt comes from aqtinstall, not vcpkg

tools/setup-qt.sh fetches pre-built Qt 6.8.3 from the official Qt mirror via aqtinstall. Building Qt from source through vcpkg added 45–90 minutes to a cold CI run, so the project doesn’t do it — and neither should you locally.

macOS

# 1. Toolchain
brew install cmake ninja autoconf autoconf-archive automake libtool pkg-config

# 2. vcpkg (one-time)
git clone https://github.com/microsoft/vcpkg.git ~/vcpkg
~/vcpkg/bootstrap-vcpkg.sh
echo 'export VCPKG_ROOT="$HOME/vcpkg"' >> ~/.zshrc && exec zsh

# 3. Reqloom + Qt
git clone https://github.com/Mirzabaig313/Reqloom
cd Reqloom
./tools/setup-qt.sh
export CMAKE_PREFIX_PATH="$HOME/Qt/6.8.3/macos"

# 4. Build
cmake --preset macos-debug
cmake --build --preset macos-debug

# 5. Run
./build/macos-debug/cli/reqloom --help

Linux

# 1. Toolchain (Ubuntu 24.04)
sudo apt-get install -y ninja-build autoconf autoconf-archive \
    automake libtool pkg-config libgl1-mesa-dev python3-pip

# 2. vcpkg (one-time)
git clone https://github.com/microsoft/vcpkg.git ~/vcpkg
~/vcpkg/bootstrap-vcpkg.sh
export VCPKG_ROOT="$HOME/vcpkg"

# 3. Reqloom + Qt
git clone https://github.com/Mirzabaig313/Reqloom
cd Reqloom
./tools/setup-qt.sh
export CMAKE_PREFIX_PATH="$HOME/Qt/6.8.3/gcc_64"

# 4. Build
cmake --preset linux-debug
cmake --build --preset linux-debug

# 5. Run
./build/linux-debug/cli/reqloom --help

GCC 14 is required. On Ubuntu 24.04 install it with sudo apt-get install -y gcc-14 g++-14 and select it via CC=gcc-14 CXX=g++-14 before configuring.

Windows

# 1. Prerequisites: Visual Studio 2022 (Desktop C++ workload),
#    Git for Windows, Python 3, CMake 4.0+

# 2. vcpkg (one-time)
git clone https://github.com/microsoft/vcpkg.git $HOME\vcpkg
& $HOME\vcpkg\bootstrap-vcpkg.bat
$env:VCPKG_ROOT = "$HOME\vcpkg"

# 3. Reqloom + Qt
git clone https://github.com/Mirzabaig313/Reqloom
cd Reqloom
.\tools\setup-qt.cmd
$env:CMAKE_PREFIX_PATH = "C:\Qt\6.8.3\msvc2022_64"

# 4. Build
cmake --preset windows-debug
cmake --build --preset windows-debug

# 5. Run
.\build\windows-debug\cli\reqloom.exe --help

Release presets (macos-release, linux-release, windows-release) build optimised binaries without sanitizers. The debug presets enable ASan and UBSan, which makes them slower but far better for development.

Run the test suite to confirm a healthy build:

ctest --test-dir build/macos-debug --output-on-failure

Troubleshooting

cmake: command not found

Reqloom needs CMake 4.0 or newer. Homebrew and most Linux repositories still ship 3.x, which fails at configure time with a policy error. Install a current build from cmake.org or with pip install "cmake>=4.0".

CMake can’t find Qt

The presets don’t guess at Qt’s location. Set CMAKE_PREFIX_PATH to the directory tools/setup-qt.sh printed:

export CMAKE_PREFIX_PATH="$HOME/Qt/6.8.3/macos"      # or .../gcc_64 on Linux

If you skipped setup-qt.sh and installed Qt some other way, it must be 6.8 or newer — 6.7 and earlier are missing APIs the desktop app relies on.

The build fails inside vcpkg

Delete the build directory and reconfigure, which is enough for most stale-cache failures:

rm -rf build/macos-debug && cmake --preset macos-debug

vcpkg writes a per-package log; the configure output names the exact file to read. Include that log if you open an issue.

The binary builds but won’t start

Usually a missing shared library. Inspect what it wants:

otool -L build/macos-debug/cli/reqloom      # macOS
ldd    build/linux-debug/cli/reqloom        # Linux

reqloom: command not found after installing

The CLI lives inside the app bundle or archive and isn’t on your PATH until you link it — see the First launch tab for your platform. On Windows, open a new terminal so it picks up the updated PATH.

Updating

Downloaded a build? Grab the newer one from the releases page and replace it. Your projects are plain files on disk and are untouched by an upgrade.

Built from source?

cd Reqloom
git pull
cmake --build --preset macos-debug

vcpkg picks up dependency changes from vcpkg.json automatically. If git pull brought in a Qt version bump, re-run ./tools/setup-qt.sh first.