# Install Qualflare CLI

Source: https://docs.qualflare.com/docs/cli/installation · Last updated: 2026-11-09

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.

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

**Homebrew:**

```bash
brew install qualflare/tap/qf
```

**npm:**

```bash
npm install -g @qualflare/cli
```

**Docker:**

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

**Binary:**

```bash
# 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](https://github.com/Qualflare/qualflare-cli/releases/tag/v0.7.0).

## 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:

```bash
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](https://docs.qualflare.com/docs/cli/installation#shell-completion). To upgrade or remove `qf`, see [Upgrading](https://docs.qualflare.com/docs/cli/installation#upgrading) and [Uninstalling](https://docs.qualflare.com/docs/cli/installation#uninstalling).

### Reporter casks

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

```bash
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](https://docs.qualflare.com/docs/reporters/go#install) and the [Maestro reporter](https://docs.qualflare.com/docs/reporters/maestro#install).

## 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:

```bash
npm install -g @qualflare/cli
```

In CI, npx runs a pinned `qf` with no global install. The login and upload pair is under [npx](https://docs.qualflare.com/docs/cli/ci-cd/other-ci#npx):

```bash
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](https://github.com/npm/cli/issues/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:

```bash
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:

```bash
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](https://docs.qualflare.com/docs/cli/ci-cd/other-ci#docker).

## Binary Download

Each release has one archive per platform on the [GitHub releases page](https://github.com/qualflare/qualflare-cli/releases/latest). It holds the `qf` binary (`qf.exe` on Windows), `LICENSE` and `README.md`:

| OS      | CPU           | Archive                        |
| ------- | ------------- | ------------------------------ |
| macOS   | Apple silicon | `qf_0.7.0_darwin_arm64.tar.gz` |
| macOS   | Intel         | `qf_0.7.0_darwin_amd64.tar.gz` |
| Linux   | x86-64        | `qf_0.7.0_linux_amd64.tar.gz`  |
| Linux   | ARM64         | `qf_0.7.0_linux_arm64.tar.gz`  |
| Windows | x86-64        | `qf_0.7.0_windows_amd64.zip`   |
| Windows | ARM64         | `qf_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](https://docs.qualflare.com/docs/cli/installation#verify-a-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:

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

### macOS

```bash
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:

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

### Linux

```bash
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](https://github.com/qualflare/qualflare-cli/releases/latest). 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:

```bash
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](https://github.com/sigstore/cosign), in the same shell:

```bash
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:

```bash
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](https://docs.qualflare.com/docs/cli/installation#verify-a-download), 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

* `command not found: qf` after you install a release binary: its directory likely isn't on your `PATH`. See [`command not found: qf` after you install it](https://docs.qualflare.com/docs/cli/troubleshooting#installation-fails).
* npm can't find the platform package: see [npm](https://docs.qualflare.com/docs/cli/installation#npm).
* macOS won't open a downloaded `qf`: see [macOS](https://docs.qualflare.com/docs/cli/installation#macos).

## Next Steps

After installing `qf`:

* Log in with a project access token: [Authenticate with qf login](https://docs.qualflare.com/docs/cli/authentication)
* Learn about the [collect command](https://docs.qualflare.com/docs/cli/collect)
* Explore [other commands](https://docs.qualflare.com/docs/cli/commands)
* Set up [CI/CD integration](https://docs.qualflare.com/docs/cli/ci-cd)
* Changelog: [Install qf with npm or Docker, or use the GitHub Action](https://changelog.qualflare.com/install-qf-npm-docker-github-action) · [What's new in Qualflare: July 2026](https://changelog.qualflare.com/july-2026)
