Installing

This guide explains how to install the current 1.15.0 release of ecctl on supported operating systems. Release artifacts are available from the release page. If you need changes that are not yet included in the latest release, you can build ecctl from source.

You can install ecctl using one of these methods:

• macOS: Homebrew (recommended) or archive (.tar.gz)
• Linux: deb, rpm, or archive (.tar.gz)
• Windows: Install with go install
• Any OS: Build from source

For shell completions, refer to Enable shell completions. If you download release artifacts (.tar.gz, .deb, or .rpm), refer to Verify downloaded artifacts to optionally verify their SHA-256 checksums before installation.

The simplest installation for macOS users is to install ecctl with Homebrew:

brew tap elastic/tap
brew install elastic/tap/ecctl

1. Download the .tar.gz archive for your architecture from the release page:

   # Apple Silicon
   curl -L -O https://download.elastic.co/downloads/ecctl/1.15.0/ecctl_1.15.0_darwin_arm64.tar.gz
   
   # Intel (x86_64)
   curl -L -O https://download.elastic.co/downloads/ecctl/1.15.0/ecctl_1.15.0_darwin_amd64.tar.gz
   

2. Extract the archive and move the ecctl binary to a directory in your PATH, for example /usr/local/bin.

3. Verify the installation:

ecctl version

Linux packages are published with every release and are available from the release page.

• Debian/Ubuntu: ecctl_<VERSION>_linux_64-bit.deb, ecctl_<VERSION>_linux_32-bit.deb, or ecctl_<VERSION>_linux_arm64.deb
• RHEL/CentOS/Fedora: ecctl_<VERSION>_linux_64-bit.rpm, ecctl_<VERSION>_linux_32-bit.rpm, or ecctl_<VERSION>_linux_arm64.rpm

Download the package that matches your system and architecture, then install it with your package manager. For example:

• On Debian/Ubuntu systems:

  curl -L -O https://download.elastic.co/downloads/ecctl/1.15.0/ecctl_1.15.0_linux_64-bit.deb
  sudo dpkg -i ecctl_1.15.0_linux_64-bit.deb
  

• On RHEL/CentOS/Fedora systems:

  curl -L -O https://download.elastic.co/downloads/ecctl/1.15.0/ecctl_1.15.0_linux_64-bit.rpm
  sudo rpm -i ecctl_1.15.0_linux_64-bit.rpm
  

1. Download the Linux .tar.gz archive for your architecture from the release page:

   # x86_64 (AMD64)
   curl -L -O https://download.elastic.co/downloads/ecctl/1.15.0/ecctl_1.15.0_linux_amd64.tar.gz
   
   # ARM64
   curl -L -O https://download.elastic.co/downloads/ecctl/1.15.0/ecctl_1.15.0_linux_arm64.tar.gz
   
   # x86 (386)
   curl -L -O https://download.elastic.co/downloads/ecctl/1.15.0/ecctl_1.15.0_linux_386.tar.gz
   

2. Extract the archive and move the ecctl binary to a directory in your PATH, for example /usr/local/bin:

   tar -xzf ecctl_1.15.0_linux_amd64.tar.gz
   sudo cp ecctl /usr/local/bin
   

3. Verify the installation:

   ecctl version
   

Official Windows binaries are not currently published. Install ecctl with go install:

1. Install Go.

2. Open Command Prompt or PowerShell.

3. Confirm Go is available:

   go version
   

4. Install ecctl:

   go install github.com/elastic/ecctl@latest
   

   To install a different version, replace @latest with a specific tag, for example:

   go install github.com/elastic/ecctl@v1.15.0
   

5. Add Go's binary directory to your PATH if needed (%USERPROFILE%\go\bin by default).

6. Verify the installation:

   ecctl version
   

Use this method if you need changes that are not yet included in an official release or want to build from a specific branch or commit.

• Go
• git

Clone the repository and build locally:

git clone https://github.com/elastic/ecctl.git
cd ecctl
go build .

This command produces an ecctl binary (ecctl.exe on Windows) in the current directory.

You can also install directly with Go:

go install .

This installs the binary into GOBIN (or GOPATH/bin if GOBIN is not set). Make sure that location is in your PATH.

For contributor-focused setup details, see Setting up a dev environment.

If you download release artifacts (.tar.gz, .deb, or .rpm), you can optionally verify their SHA-256 checksums before installing them.

1. Download the checksum file:

   curl -L -O https://download.elastic.co/downloads/ecctl/1.15.0/ecctl_1.15.0_checksums.txt
   

2. Compute the SHA-256 checksum of the downloaded artifact. For example:

   # macOS
   shasum -a 256 ecctl_1.15.0_darwin_arm64.tar.gz
   
   # Linux
   sha256sum ecctl_1.15.0_linux_amd64.tar.gz
   

3. Display the expected checksum from the checksums file. For example:

   grep "ecctl_1.15.0_linux_amd64.tar.gz" ecctl_1.15.0_checksums.txt
   

   Verify that the checksum matches the value returned by the checksum command.

You can enable shell completions after installation. These instructions apply to Bash and Zsh on macOS and Linux.

Load completions for the current shell session:

source <(ecctl generate completions)

Persist completions across sessions:

• Bash: echo "source <(ecctl generate completions)" >> ~/.bash_profile
• Zsh: echo "source <(ecctl generate completions)" >> ~/.zshrc

• ecctl: command not found: Add the binary location to your PATH.
• permission denied when copying to system paths: Use elevated privileges (sudo on Linux/macOS).
• go: command not found on Windows: Ensure Go is installed correctly and restart the terminal after installation.

Use the same installation method you used to install ecctl:

• Homebrew (macOS):

  brew upgrade ecctl
  

• Linux package (deb/rpm): Install a newer package from the release page
• Archive (.tar.gz) (macOS/Linux): Download the latest archive from the release page and replace the existing binary.
• Windows (go install):

  go install github.com/elastic/ecctl@latest
  

After installing ecctl, continue with:

• Configure ecctl
• Initialize your first configuration
• Authentication methods
• Usage examples
• Command reference

If you use serverless projects, refer to Manage serverless projects