Installation

This guide covers all methods to install Probitas CLI.

The CLI is a single probitas binary. It embeds its runtime and Probitas itself, so nothing else (Node.js, Bun, or Deno) needs to be installed to run scenarios.

Supported platforms:

• macOS (arm64, x64)
• Linux with glibc (x64, arm64)
• Windows (x64)

musl-based Linux distributions such as Alpine are not supported yet.

Upgrading from Probitas 1.x? See the Migration Guide.

Shell Installer

Install the CLI on macOS or Linux using the shell installer:

curl -fsSL https://raw.githubusercontent.com/probitas-test/probitas/main/install.sh | sh

The script downloads the binary for your platform from the GitHub Releases, verifies its checksum, and installs it to ~/.local/bin. Make sure that directory is on your PATH.

Options

Configure installation via environment variables:

# Install specific version
curl -fsSL https://raw.githubusercontent.com/probitas-test/probitas/main/install.sh | PROBITAS_VERSION=2.0.0 sh

# Install under a custom root (the binary goes to <root>/bin)
curl -fsSL https://raw.githubusercontent.com/probitas-test/probitas/main/install.sh | PROBITAS_INSTALL_DIR=/usr/local sh

Windows

Download probitas-windows-x64.zip from the GitHub Releases, extract it, and put probitas.exe in a directory on your PATH.

Homebrew (macOS/Linux)

Install via the official Homebrew tap:

# Add the tap and install
brew tap probitas-test/tap
brew install probitas

# Or install directly
brew install probitas-test/tap/probitas

Nix

The Probitas repository provides a Nix flake that builds probitas from source.

Run Without Installing

Execute probitas directly without installing:

nix run github:probitas-test/probitas

Install to Profile

Install into your Nix profile for persistent access:

nix profile install github:probitas-test/probitas

Add to Project's flake.nix

Add Probitas to your project's development environment using the overlay:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
    probitas-flake.url = "github:probitas-test/probitas";
    flake-utils.url = "github:numtide/flake-utils";
  };

  outputs = { nixpkgs, probitas-flake, flake-utils, ... }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        pkgs = import nixpkgs {
          inherit system;
          overlays = [ probitas-flake.overlays.default ];
        };
      in {
        devShells.default = pkgs.mkShell {
          packages = with pkgs; [ probitas ];
        };
      });
}

Enter the development environment:

nix develop

Why Use Overlays?

The overlay pattern integrates probitas directly into your pkgs, enabling cleaner configuration:

overlays = [ probitas-flake.overlays.default ];
# ...
packages = with pkgs; [ probitas ];  # probitas is now part of pkgs

Benefits:

• Unified namespace: Access probitas like any nixpkgs package
• Composable: Combine with other overlays seamlessly

Why Use inputs.follows?

The inputs.follows directive ensures Probitas uses your project's nixpkgs version instead of its own pinned version:

probitas-flake.inputs.nixpkgs.follows = "nixpkgs";
probitas-flake.inputs.flake-utils.follows = "flake-utils";

Benefits:

• Single nixpkgs version: All dependencies share one nixpkgs, reducing closure size
• Faster evaluation: Fewer inputs to fetch and evaluate

Pin a Specific Version

The flake builds the CLI from the revision you lock, so nix flake update follows the main branch, and the binary reports its version as 0.0.0-unstable.<date>.<rev>. To stay on a release, pin the flake to its tag:

probitas-flake.url = "github:probitas-test/probitas/v2.0.2";

Pin v2.0.2 or later: the v2.0.0 and v2.0.1 tags predate the source build and do not install their own version through Nix. Pin v1.0.0 to keep using Probitas 1.x, which runs on Deno.

Flake Outputs Reference

The Probitas flake provides:

GitHub Actions

Using setup-probitas Action

The recommended way to use Probitas in GitHub Actions:

- uses: probitas-test/setup-probitas@v2
  with:
    probitas-version: latest # or a specific version like '2.0.0'

- name: Run scenarios
  run: probitas run

Use probitas-test/setup-probitas@v1 to keep using Probitas 1.x. See probitas-test/setup-probitas for full documentation.

Using Nix in GitHub Actions

For projects using Nix flakes with nixbuild/nix-quick-install-action:

- uses: nixbuild/nix-quick-install-action@v34

- name: Run scenarios
  run: nix run github:probitas-test/probitas -- run

Or within a Nix development shell:

- uses: nixbuild/nix-quick-install-action@v34

- name: Run scenarios
  run: nix develop -c probitas run

Pre-fetching DuckDB

The DuckDB native binding is not embedded in the binary; it is downloaded the first time a scenario creates a DuckDB client. Pre-fetch it when building CI images or before going offline:

probitas cache duckdb

See Native Dependencies for details.

Verify Installation

After installation, verify the CLI is working:

probitas --version

Next Steps

• Quick Start - Initialize your first project
• Scenario Guide - Learn to write scenarios
• Migration Guide - Upgrade scenarios from Probitas 1.x