Skip to main content

Install Chromia CLI

This topic contains instructions to install and update the Chromia CLI.

Prerequisite​

Install​

Before installing the Chromia CLI, ensure you have installed the Java Development Kit (open JDK) and have at least Java 21. For more information, see JDK installation guide.

You can download and install the latest Chromia CLI from here or via a package manager:

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

Some versions are backed up, so you can return to a previous version of the CLI. To install a prior version, use this command to install and switch versions:

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

To see which versions are available, search for them using brew search: brew search chr.

Update​

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:

brew update
brew upgrade chr

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. Please refer to the Docker documentation on how to install Docker on Windows, Mac, and Linux.

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
note

When configuring your chromia.yml file to ensure the Chromia CLI can access the PostgreSQL instance, use the following instructions based on your operating system:

  • Mac: Specify host.docker.internal in the database:host field in chromia.yml.
  • Windows: Set database:host to 172.17.0.1 in chromia.yml.
  • Linux: Instead of modifying chromia.yml, when running Docker on Linux, include the --network=host argument in your Docker CLI commands.

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

See the Docker command line reference for information about updating or uninstalling the Docker image.

#!/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 "$@"