Getting Started

Welcome to the Zarf documentation! This section will list the various ways to install Zarf onto your machine. It will also demonstrate how to verify the installation. Choose the installation type that best suits your needs in accordance with your operating system. Let's get started!

Installing Zarf

There are multiple ways to get the Zarf CLI onto your machine:

• Install from Homebrew.
• Download a prebuilt binary.
• Build the CLI from scratch.

Installing with Homebrew

Homebrew is an open-source software package manager that simplifies the installation of software on macOS and Linux.

macOS

With Homebrew on macOS, installing Zarf is as simple as:

brew tap defenseunicorns/tap && brew install zarf

Linux

With Homebrew on Linux, installing Zarf is as simple as:

brew tap defenseunicorns/tap && brew install zarf

note

The above command detects your OS and system architecture and installs the correct Zarf CLI binary for your machine. Once the above command is entered, the CLI should be installed on your $PATH and is ready for immediate use.

Downloading from GitHub Releases

All Zarf releases on GitHub include prebuilt binaries that you can download and use. We offer range of combinations of OS and architecture for you to choose from.

Linux

To download Zarf on Linux you can run the following (replacing <zarf-version> with a version of Zarf):

ZARF_VERSION=<zarf-version>
ZARF_ARCH=$([ $(uname -m) == "x86_64" ] && echo "amd64" || echo "arm64";)

curl -sL https://github.com/defenseunicorns/zarf/releases/download/${ZARF_VERSION}/zarf_${ZARF_VERSION}_Linux_${ZARF_ARCH} -o zarf
chmod +x zarf

On most Linux distributions, you can also install the binary onto your $PATH by simply moving the downloaded binary to the /usr/local/bin directory:

sudo mv zarf /usr/local/bin/zarf

macOS

To download Zarf on macOS you can run the following (replacing <zarf-version> with a version of Zarf):

ZARF_VERSION=<zarf-version>
ZARF_ARCH=$([ $(uname -m) == "x86_64" ] && echo "amd64" || echo "arm64";)

curl -sL https://github.com/defenseunicorns/zarf/releases/download/${ZARF_VERSION}/zarf_${ZARF_VERSION}_Darwin_${ZARF_ARCH} -o zarf
chmod +x zarf

You can also install the binary onto your $PATH by simply moving the downloaded binary to the /usr/local/bin directory:

sudo mv zarf /usr/local/bin/zarf

Windows

To download Zarf on Windows you can run the following (replacing <zarf-version> with a version of Zarf and <zarf-arch> with either amd64 or arm64 depending on your system):

$ZarfVersion="<zarf-version>"
$ZarfArch="<zarf-arch>"

Start-BitsTransfer -Source "https://github.com/defenseunicorns/zarf/releases/download/$($ZarfVersion)/zarf_$($ZarfVersion)_Windows_$($ZarfArch).exe" -Destination zarf.exe

You can also install the binary onto your $PATH by moving the downloaded binary to the desired directory and modifying the $PATH environment variable to include that directory.

Building the CLI from Scratch

If you want to build the CLI from scratch, you can do that too. Our local builds depend on Go 1.19.x and Node 18.x and are built using make.

note

The make build-cli command builds a binary for each combination of OS and architecture. If you want to shorten the build time, you can use an alternative command to only build the binary you need:

• make build-cli-mac-intel
• make build-cli-mac-apple
• make build-cli-linux-amd
• make build-cli-linux-arm
• make build-cli-windows-amd
• make build-cli-windows-arm

For additional information, see the Building Your Own Zarf CLI page.

Verifying the Zarf Install

Now that you have installed Zarf, let's verify that it is working. First, we'll check the version of Zarf that has been installed:

$ zarf version

vX.X.X  # X.X.X is replaced with the version number of your specific installation

If you are not seeing this then Zarf was not installed onto your $PATH correctly. This $PATH guide should help with that.

Downloading the 'Init' Package

The 'init' package is a special Zarf package that initializes a cluster with services that are used to store resources while in the air gap and is required for most (but not all) Zarf deployments.

You can get it for your version of Zarf by visiting the Zarf releases page and downloading it into your working directory or into ~/.zarf-cache/zarf-init-<amd64|arm64>-vX.X.X.tar.zst)

If you are online on the machine with cluster access you can also run zarf init without the --confirm flag to be given the option to download the version of the init package for your Zarf version or you can use the zarf tools download-init command.

note

You can build your own custom 'init' package too if you'd like. For this you should check out the Creating a Custom 'init' Package Tutorial.

Where to Next?

Depending on how familiar you are with Kubernetes, DevOps, and Zarf, let's find what set of information would be most useful to you.

• If you want to become more familiar with Zarf and it's features, see the Tutorials page.

• More information about the Zarf CLI is available on the Zarf CLI page, or by browsing through the help descriptions of all the commands available through zarf --help.

• More information about the packages that Zarf creates and deploys is available in the Understanding Zarf Packages page.

• If you want to take a step back and better understand the problem Zarf is trying to solve, you can find more context on the Understand the Basics and Core Concepts pages.