Skip to content
The docs are now organized by product area. Old links still work. Report a broken link

Install Qualflare CLI

Install the Qualflare CLI (qf) on macOS, Linux or Windows with Homebrew, npm, Docker or a release archive, and check the download against its signed checksums.

Last updated

The Qualflare CLI, qf, installs with Homebrew, npm, Docker or a release archive, and runs on macOS, Linux and Windows on amd64 and arm64.

brew install qualflare/tap/qf
npm install -g @qualflare/cli
docker run --rm ghcr.io/qualflare/qf:0.7.0 version
# Download a binary for your platform from the qf 0.7.0 release page:
# https://github.com/Qualflare/qualflare-cli/releases/tag/v0.7.0

Download a binary from the qf 0.7.0 release page.

AI Command

Paste this prompt into your AI coding agent to install qf automatically:

Install the Qualflare CLI (`qf`) on my machine.

1. Detect my operating system (macOS, Linux, or Windows) and CPU architecture
   (amd64 or arm64).
2. If Homebrew is available (macOS/Linux), run: brew install qualflare/tap/qf
3. Otherwise, open https://github.com/qualflare/qualflare-cli/releases/latest,
   download the asset matching my OS and architecture
   (qf_<version>_<os>_<arch>.tar.gz, or .zip on Windows), extract it, and move
   the `qf` binary into a directory on my PATH.
4. Run `qf version` to confirm the install succeeded.

Homebrew (macOS/Linux)

The qf cask of the qualflare/tap tap installs on macOS, and on Linux with Homebrew 4.5.0 or later, which added casks on Linux:

brew install qualflare/tap/qf

The binaries aren't notarized by Apple, so the cask removes the quarantine attribute from qf on macOS as it installs. It installs no shell completion: see Shell completion. To upgrade or remove qf, see Upgrading and Uninstalling.

Reporter casks

The same tap has the casks of two Qualflare reporters, which write the reports qf uploads. Neither cask installs qf.

brew install qualflare/tap/qualflare-go       # the go test reporter
brew install qualflare/tap/qualflare-maestro  # the Maestro reporter

To set them up, see the Go reporter and the Maestro reporter.

npm

The npm package @qualflare/cli needs Node.js 16 or later and runs no install script. npm installs the qf binary for your machine from one of the package's optional dependencies, which cover macOS, Linux and Windows on x64 and arm64:

npm install -g @qualflare/cli

In CI, npx runs a pinned qf with no global install. The login and upload pair is under npx:

npx --yes @qualflare/cli@0.7.0 version

If qf stops with [qualflare] The package "@qualflare/cli-<os>-<arch>" could not be found, and is needed by @qualflare/cli., npm left the binary out:

  • With --omit=optional or --no-optional: install again without the flag.
  • Otherwise, in a project that lists @qualflare/cli, its lockfile can lack the platform package (npm bug npm/cli#4828): in the project's folder, run rm -rf node_modules package-lock.json && npm install. It deletes the lockfile and resolves every dependency again, so commit first and review the new lockfile's diff.

If node_modules was installed on another platform, through a Docker bind mount, a WSL share or Rosetta, the message names the package that is there instead: install again on the machine that runs qf. To run a qf binary you already have, set QF_BINARY to its absolute path, such as QF_BINARY=/opt/qualflare/qf qf version, and the package runs that binary without looking for its own.

Docker

Multi-arch images (amd64 and arm64) are published to GitHub Container Registry as ghcr.io/qualflare/qf and to Docker Hub as qualflare/qf. Each release is tagged with its version number, such as 0.7.0, and latest points to the newest stable release:

docker run --rm ghcr.io/qualflare/qf:0.7.0 version

The image is Alpine Linux with qf and no git, and it runs as the user qf (uid 10001), which must be able to read the files you mount. Each docker run --rm starts with no saved login, so log in and collect in the same container, and pass in the branch and commit, which qf can't read from git there:

docker run --rm \
  -e QF_TOKEN -e QF_BRANCH -e QF_COMMIT -e QF_ENVIRONMENT \
  -v "$(pwd)":/data -w /data --entrypoint sh \
  ghcr.io/qualflare/qf:0.7.0 -c 'qf login ci --force && qf ci collect results.xml'

-e NAME with no value passes the job's own value into the container, and no other variable crosses, so set QF_BRANCH and QF_COMMIT in the job first. More: Docker image.

Binary Download

Each release has one archive per platform on the GitHub releases page. It holds the qf binary (qf.exe on Windows), LICENSE and README.md:

OSCPUArchive
macOSApple siliconqf_0.7.0_darwin_arm64.tar.gz
macOSIntelqf_0.7.0_darwin_amd64.tar.gz
Linuxx86-64qf_0.7.0_linux_amd64.tar.gz
LinuxARM64qf_0.7.0_linux_arm64.tar.gz
Windowsx86-64qf_0.7.0_windows_amd64.zip
WindowsARM64qf_0.7.0_windows_arm64.zip

The commands below install qf 0.7.0 and keep the archive's name, so you can verify the download. To install the newest release instead, replace their VERSION= line with these two lines, which read the version from GitHub's latest-release link:

VERSION=$(curl -Ls -o /dev/null -w '%{url_effective}' https://github.com/qualflare/qualflare-cli/releases/latest)
VERSION=${VERSION##*/v}

macOS

VERSION=0.7.0
ARCH=arm64  # amd64 on an Intel Mac
curl -LO "https://github.com/qualflare/qualflare-cli/releases/download/v${VERSION}/qf_${VERSION}_darwin_${ARCH}.tar.gz"
tar -xzf "qf_${VERSION}_darwin_${ARCH}.tar.gz" qf
sudo mv qf /usr/local/bin/

The binaries aren't notarized by Apple. If macOS won't open qf from an archive you downloaded in a browser, remove the quarantine attribute:

xattr -d com.apple.quarantine /usr/local/bin/qf

Linux

VERSION=0.7.0
ARCH=amd64  # arm64 on an ARM64 machine
curl -LO "https://github.com/qualflare/qualflare-cli/releases/download/v${VERSION}/qf_${VERSION}_linux_${ARCH}.tar.gz"
tar -xzf "qf_${VERSION}_linux_${ARCH}.tar.gz" qf
sudo mv qf /usr/local/bin/

Windows

Download qf_0.7.0_windows_amd64.zip (x86-64) or qf_0.7.0_windows_arm64.zip (ARM64) from the GitHub releases page. Extract it and move qf.exe to a folder on your PATH.

Verify a download

Each release's checksums.txt lists the SHA-256 checksum of every archive and SBOM in the release. Download it into the folder that holds your archive, then check:

VERSION=0.7.0
curl -LO "https://github.com/qualflare/qualflare-cli/releases/download/v${VERSION}/checksums.txt"
sha256sum --check --ignore-missing checksums.txt       # Linux
shasum -a 256 --check --ignore-missing checksums.txt   # macOS

Each file you have prints OK, such as qf_0.7.0_linux_amd64.tar.gz: OK, and --ignore-missing skips the rest. On Windows, Get-FileHash in PowerShell prints a file's SHA-256: compare it with the ZIP's line in checksums.txt.

The release workflow signs checksums.txt with Sigstore's keyless signing. The signature is checksums.txt.sig and the signing certificate checksums.txt.pem, on the same release page. To check them with cosign, in the same shell:

curl -LO "https://github.com/qualflare/qualflare-cli/releases/download/v${VERSION}/checksums.txt.sig"
curl -LO "https://github.com/qualflare/qualflare-cli/releases/download/v${VERSION}/checksums.txt.pem"
cosign verify-blob checksums.txt \
  --signature checksums.txt.sig \
  --certificate checksums.txt.pem \
  --certificate-identity "https://github.com/Qualflare/qualflare-cli/.github/workflows/release.yml@refs/tags/v${VERSION}" \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

It prints Verified OK when the release workflow of that tag signed checksums.txt. Each archive also has a software bill of materials (SBOM) in SPDX 2.3 JSON on the release page, named after the archive with .sbom.json added, such as qf_0.7.0_linux_amd64.tar.gz.sbom.json.

Verify Installation

Confirm that qf is installed correctly:

qf version

You should see output like this, with your own build details and platform:

qf 0.7.0 (commit: <commit>, built: <build date>, <os>/<arch>, <go version>)

Shell completion

qf completion prints a completion script for bash, zsh, fish or PowerShell. To load it in your current shell, run the line for your shell:

  • bash, with the bash-completion package installed: source <(qf completion bash)
  • zsh, with compinit loaded: source <(qf completion zsh)
  • fish: qf completion fish | source
  • PowerShell: qf completion powershell | Out-String | Invoke-Expression

To load it in every new shell, follow qf completion <shell> --help. Completion offers your saved identifiers too, because each one is a qf command.

Upgrading

  • Homebrew: Run brew upgrade qualflare/tap/qf
  • npm: Run npm install -g @qualflare/cli@latest
  • Docker: Pull the new release's version tag, or latest, which points to the newest stable release on both registries
  • Binary: Download the latest release, verify it, and replace the existing binary

Uninstalling

  • Homebrew: brew uninstall qualflare/tap/qf
  • npm: npm uninstall -g @qualflare/cli
  • Docker: Remove each image tag you pulled, such as docker rmi ghcr.io/qualflare/qf:0.7.0
  • Binary: Delete the qf binary from wherever you moved it (e.g. sudo rm /usr/local/bin/qf)

Your saved login credentials aren't removed by any of the above. Delete the credentials file too if you want a clean slate: ~/.config/qualflare/config.toml on Linux ($XDG_CONFIG_HOME/qualflare/config.toml when that variable is set), ~/Library/Application Support/qualflare/config.toml on macOS, or %AppData%\qualflare\config.toml on Windows.

Troubleshooting

Next Steps

After installing qf: