Install atscalectl

atscalectl is AtScale's CLI for managing and troubleshooting AtScale deployments on Kubernetes. This page describes how to install atscalectl.

Prerequisites

Before installing atscalectl, verify you meet the following requirements:

• Your AtScale instance is installed on Kubernetes.
• You are on AtScale C2025.12.0 or later.
• You have a valid Kubernetes kubeconfig. atscalectl uses this to connect directly to Kubernetes.
• You have access to the AtScale Kubernetes cluster.

Note

Individual atscalectl commands have additional required permissions. For specifics, see the atscalectl Command Reference.

Install atscalectl

There are two ways to install atscalectl:

1. Download the binary from the AtScale distribution site.
2. Run the Docker image from Docker Hub.

Both methods are described in the following sections.

Option 1: Install the binary

Linux

To install atscalectl on Linux:

1. To install atscalectl, run:

   curl -fsSL https://files.atscale.com/atscalectl/install.sh | sh

   If you want to install a specific version, run:

   curl -fsSL https://files.atscale.com/atscalectl/install.sh | VERSION=0.1.0 sh

   To explicitly install system-wide as a normal user, run:

   curl -fsSL https://files.atscale.com/atscalectl/install.sh | INSTALL_DIR=/usr/local/bin sh

   The installer puts atscalectl in /usr/local/bin, if you have write permissions for that directory; otherwise, it installs to ~/.local/bin. If ~/.local/bin is not on your PATH, add it to your shell profile:

   export PATH="$HOME/.local/bin:$PATH"

2. Verify the installation:

   atscalectl version

   This should output a table similar to the following:

   ┌─────────┬───────────┬──────────────────────┬────────────┐
   │ VERSION │ COMMIT    │ DATE                 │ GO VERSION │
   ├─────────┼───────────┼──────────────────────┼────────────┤
   │ 0.1.0   │ <commit>  │ <date>               │ go1.26.5   │
   └─────────┴───────────┴──────────────────────┴────────────┘

3. Start using atscalectl. For example:

   atscalectl status --context <your-context> --namespace <your-namespace>

macOS

To install atscalectl on macOS:

1. To install atscalectl, run:

   curl -fsSL https://files.atscale.com/atscalectl/install.sh | sh

   If you want to install a specific version, run:

   curl -fsSL https://files.atscale.com/atscalectl/install.sh | VERSION=0.1.0 sh

   The installer puts atscalectl in /usr/local/bin, if you have write permissions for that directory; otherwise, it installs to ~/.local/bin. If ~/.local/bin is not on your PATH, add it to your shell profile:

   export PATH="$HOME/.local/bin:$PATH"

2. Verify the installation:

   atscalectl version

   This should output a table similar to the following:

   ┌─────────┬───────────┬──────────────────────┬────────────┐
   │ VERSION │ COMMIT    │ DATE                 │ GO VERSION │
   ├─────────┼───────────┼──────────────────────┼────────────┤
   │ 0.1.0   │ <commit>  │ <date>               │ go1.26.5   │
   └─────────┴───────────┴──────────────────────┴────────────┘

3. Start using atscalectl. For example:

   atscalectl status --context <your-context> --namespace <your-namespace>

Windows

To install atscalectl on Windows:

1. To install atscalectl, run the following in PowerShell:

   irm https://files.atscale.com/atscalectl/install.ps1 | iex

   To install a specific version, run:

   $env:VERSION="0.1.0"; irm https://files.atscale.com/atscalectl/install.ps1 | iex

2. Open a new PowerShell window. This makes the updated PATH available.

3. Verify the installation:

   atscalectl version

   This should output a table similar to the following:

   ┌─────────┬───────────┬──────────────────────┬────────────┐
   │ VERSION │ COMMIT    │ DATE                 │ GO VERSION │
   ├─────────┼───────────┼──────────────────────┼────────────┤
   │ 0.1.0   │ <commit>  │ <date>               │ go1.26.5   │
   └─────────┴───────────┴──────────────────────┴────────────┘

4. Start using atscalectl. For example:

   atscalectl status --context <your-context> --namespace <your-namespace>

Manual download

For air-gapped or locked-down environments, you can download the archive for your platform and checksums.txt directly using the following links:

• Linux AMD64
• Linux ARM64
• macOS AMD64
• macOS ARM64
• Windows AMD64
• Windows ARM64
• Checksums

Note

On Windows, SmartScreen may display a warning for the manually downloaded binary because it is not currently code-signed.

Verify and extract the archive

Once you have downloaded the archive, you should verify and extract it.

On Linux:

1. Verify the checksum:

   sha256sum -c --ignore-missing checksums.txt

   --ignore-missing is required because checksums.txt also lists a source archive that is not published.

2. Extract the archive:

   tar -xzf atscalectl_0.1.0_linux_amd64.tar.gz

3. Install atscalectl:

   sudo install -m 0755 atscalectl /usr/local/bin/atscalectl

On macOS:

1. Verify the binaries. For example, to verify the ARM64 archive:

   grep atscalectl_0.1.0_darwin_arm64.tar.gz checksums.txt | shasum -a 256 -c -

2. Extract the archive and install atscalectl to a directory on your PATH.

Note

If macOS blocks a manually downloaded binary, remove the quarantine attribute by running:

xattr -d com.apple.quarantine ./atscalectl

Option 2: Run atscalectl with Docker

atscalectl is available as a public Docker image on Docker Hub. The image supports both Linux AMD64 and Linux ARM64.

To run atscalectl with Docker:

1. Pull the image. To pull a specific version, run:

   docker pull atscaleinc/atscalectl:0.1.0

   To pull the latest release, run:

   docker pull atscaleinc/atscalectl:latest

2. Verify the installation:

   docker run --rm atscaleinc/atscalectl:0.1.0 version

3. To run atscalectl against Kubernetes, mount your kubeconfig into the container:

   docker run --rm -v ~/.kube/config:/kube.cfg:ro atscaleinc/atscalectl:0.1.0 status --kubeconfig /kube.cfg --context <your-context> --namespace <your-namespace> --release-name <your-release>

   Where:

   • <your-context> is the Kubernetes context.
   • <your-namespace> is the AtScale namespace.
   • <your-release> is the AtScale Helm release name.
   Note

   For a local Kubernetes cluster such as Minikube or Kind, include --network host if the Kubernetes API server is exposed through localhost.

Note

If you use Cloud Kubernetes, be aware that the Docker image does not include external Kubernetes credential helpers such as aws, gke-gcloud-auth-plugin, or kubelogin. If your kubeconfig uses one of these through exec authentication, use the native atscalectl binary instead, or provide a kubeconfig that does not require an external credential helper.

Troubleshooting

atscalectl: command not found

Make sure the installation directory is in your PATH:

• Linux and macOS: If atscalectl was installed in ~/.local/bin, add it to your shell profile:

  export PATH="$HOME/.local/bin:$PATH"

• Windows: Open a new PowerShell window after installation.

Cannot connect to Kubernetes

Check that:

• Your kubeconfig is valid.
• The Kubernetes context is correct.
• You have the required permissions for the command you are trying to run.

Multiple Helm releases found

Specify the Helm release explicitly with the --release-name global flag.

Cannot auto-detect the release name

If you see an error indicating that access to Secrets is forbidden, specify the Helm release explicitly with the --release-name global flag.

Docker cannot connect to Kubernetes

Make sure your kubeconfig is mounted into the container and pass its location explicitly with the --kubeconfig global flag.

For Minikube or Kind, if the API server is exposed through localhost, include the --network host flag.

Docker reports executable aws not found, gke-gcloud-auth-plugin not found, or kubelogin not found

The Docker image does not include external Kubernetes credential helpers. Use the native atscalectl binary, or provide a kubeconfig that does not require an external credential helper.

Installation quick reference

OS/Platform	Install Command
Linux/macOS	curl -fsSL https://files.atscale.com/atscalectl/install.sh | sh
Windows	irm https://files.atscale.com/atscalectl/install.ps1 | iex
Docker	docker pull atscaleinc/atscalectl:0.1.0