Skip to main content

Install Chromia CLI

This guide provides detailed instructions for installing and updating the Chromia CLI.

Prerequisites​

Before installing Chromia CLI, ensure the following requirements are met:

  • PostgreSQL Database: Refer to the Set up PostgreSQL database.
  • Java Runtime (RELL_JAVA): Chromia CLI requires Java Runtime Environment (version 21 or later). Package managers handle this automatically. To control the Java runtime explicitly, set the RELL_JAVA environment variable to a valid Java installation path.

Using Docker is the recommended way to install Chromia CLI as it provides an isolated environment with Chromia CLI pre-installed. Make sure you have Docker installed and configured on your machine.

Install Docker​

Docker can run a standalone Linux container with the Chromia CLI pre-installed. Make sure that you have set up the PostgreSQL database.

To use the published Docker images, you must first have Docker installed and configured on your host machine. Follow the Docker installation guide to install Docker on your system.

Start the Docker container with Chromia CLI pre-installed​

To run the latest version of the Chromia CLI, use the docker run command and specify the CLI Docker image name and chr.

docker run --rm -v "$(pwd):/usr/app" registry.gitlab.com/chromaway/core-tools/chromia-cli/chr:<latest version> chr
info

This prefix is required for all chr commands, not just during setup. This ensures that the chr commands run inside the Docker container correctly and can access your project files.

Example:

docker run --rm -v "$(pwd):/usr/app" registry.gitlab.com/chromaway/core-tools/chromia-cli/chr:0.22.2 chr test
note

Make sure to configure your chromia.yml file correctly:

  • macOS: Set database:host to host.docker.internal in your configuration file.
  • Windows: Set database:host to 172.17.0.1.
  • Linux: Use --network=host in the Docker run command to ensure proper connectivity to your PostgreSQL database.

These configurations are crucial to ensure connectivity between Chromia CLI and the PostgreSQL instance.

Advanced Docker configuration​

You can customize the Docker command further using this script:

#!/bin/bash

# Allocate a pseudo-TTY one when run in interactive mode
if [ -t 0 ] && [ -t 1 ] ; then TTY="--tty"; else TTY=""; fi

docker run \
  # Sets the network to host to not need to change the database hostname (linux only)
  --network=host \
  # Set timezone based on system settings (linux only)
  -e TZ=$(cat /etc/timezone) \
  # Sets process ownership to current user
  --user $(id -u):$(id -g) \
  --mount type=bind,source="/etc/passwd",target=/etc/passwd,readonly \
  --mount type=bind,source="/etc/group",target=/etc/group,readonly \
  # Configures ssh-agent (only needed if chr install is called on non-public repositores)
  -e SSH_AUTH_SOCK=$SSH_AUTH_SOCK \
  --volume "$SSH_AUTH_SOCK:$SSH_AUTH_SOCK" \
  --mount type=bind,source="${HOME}/.ssh",target=${HOME}/.ssh,readonly \
  --mount type=bind,source="${HOME}/.config/jgit",target=${HOME}/.config/jgit \
  # Mounts current folder into the container (Use `Get-Location` on PowerShell)
  --mount type=bind,source="$(pwd)",target=/usr/app \
  --interactive ${TTY} \
  --rm \
  registry.gitlab.com/chromaway/core-tools/chromia-cli/chr:${CHR_VERSION:-latest} chr "$@"

This script mounts the current directory into the container and ensures that Chromia CLI runs with the correct user and environment settings.

For additional details, refer to the Docker documentation.

Installation via package managers (optional)​

If you prefer not to use Docker, Chromia CLI can also be installed using package managers. Choose the appropriate platform below:

macOS​

To install Chromia CLI (chr) on macOS, follow these steps:

  1. Install Homebrew (if not already installed):

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. Add the Chromia repository to Homebrew:

    brew tap chromia/core https://gitlab.com/chromaway/core-tools/homebrew-chromia.git

  3. Install Chromia CLI:

    brew install chromia/core/chr
    info

    To install a specific version of Chromia CLI, use the following commands:

    brew install chromia/core/chr@<version>
    brew unlink chr
    brew link chr@<version>

    You can list available versions using: brew search chr.

  4. Verify the installation:

    chr --version

Linux/WSL​

To install Chromia CLI (chr) on Linux or WSL (Windows Subsystem for Linux), follow these steps:

  1. Download and add Chromia's apt-repo public key to your system’s trusted keyrings:

    curl -fsSL https://apt.chromia.com/chromia.gpg | sudo tee /usr/share/keyrings/chromia.gpg >/dev/null

  2. Add the Chromia repository to your list of package sources:

    echo "deb [arch=amd64 signed-by=/usr/share/keyrings/chromia.gpg] https://apt.chromia.com stable main" | sudo tee /etc/apt/sources.list.d/chromia.list

  3. Run the following command to update your package sources:

    sudo apt-get update
    info

    If you added apt.chromia.com before Chromia CLI version 0.16.0, run the following command to allow the repository update:

    sudo apt-get --allow-releaseinfo-change update

  4. Once the repository is updated, install Chromia CLI by running:

    sudo apt-get install chr

  5. To verify that Chromia CLI is installed successfully, check the version:

    chr --version

Windows​

To install Chromia CLI (chr) on Windows, you must first install Scoop by using the Windows PowerShell version >= 5.1.

  1. Open Windows PowerShell as an administrator and run the following command to allow PowerShell to run downloaded scripts:

    Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

  2. Install Scoop by running the following command in PowerShell:

    Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression

  3. Add Chromia and Java buckets to Scoop:

    scoop bucket add chromia https://gitlab.com/chromaway/core-tools/scoop-chromia.git
    scoop bucket add java

    This will enable scoop to download the openjdk21 which chromia-cli depends on when installing

  4. Install Chromia CLI:

    scoop install chr

  5. Verify the installation:

    chr --version

Updating Chromia CLI​

You can download and install the latest Chromia CLI from here, or if you have installed the Chromia CLI via a package manager, you can update it with the following:

macOS​

brew update
brew upgrade chr

Linux/WSL​

sudo apt-get update
sudo apt-get install chr

Windows​

scoop update
scoop update chr