Skip to main content
The talosctl CLI is the primary tool for interacting with Talos Linux clusters. This guide covers installation on all major operating systems.

Overview

talosctl is a command-line interface that communicates with Talos Linux nodes via a secure gRPC API. You’ll use it to:
  • Create and manage local development clusters
  • Configure and bootstrap Talos nodes
  • Perform cluster operations (upgrade, reboot, etc.)
  • Retrieve logs and debug information
  • Generate and manage configurations
  • Access Kubernetes clusters running on Talos
The talosctl version should match your Talos Linux version for full compatibility. You can run different versions, but some features may not work correctly.

Installation Methods

Choose your operating system:
The easiest way to install talosctl on macOS is via Homebrew:
brew install siderolabs/tap/talosctl
This installs the latest stable release of talosctl and keeps it updated with brew upgrade.

Update talosctl

brew upgrade talosctl

Install Specific Version

# Install a specific version
brew install siderolabs/tap/[email protected]

Using curl (Alternative)

If you prefer not to use Homebrew, download the binary directly:
curl -sL https://talos.dev/install | sh
The installation script automatically detects your architecture and installs to /usr/local/bin.

Manual Installation

For manual installation with version control:
# Set your desired version
export TALOS_VERSION="v1.13.0"

# Detect architecture
export ARCH=$(uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')

# Download binary
curl -Lo /usr/local/bin/talosctl \
  https://github.com/siderolabs/talos/releases/download/${TALOS_VERSION}/talosctl-darwin-${ARCH}

# Make executable
chmod +x /usr/local/bin/talosctl

Verify Installation

After installation, verify that talosctl is working correctly:
1

Check version

talosctl version --client
Expected output:
Tag:         v1.13.0
SHA:         a1b2c3d4
Built:       2026-03-01T10:00:00Z
Go version:  go1.26
OS/Arch:     darwin/arm64
2

Verify command completion

Test that the command works:
talosctl --help
You should see the complete list of available commands and options.
3

Check installation path

Confirm the binary location:
which talosctl
Common locations:
  • macOS/Linux: /usr/local/bin/talosctl
  • Linux (user install): ~/.local/bin/talosctl
  • Windows: %USERPROFILE%\.talos\talosctl.exe

Shell Completion

Enable shell completion for easier command usage:
# Add to ~/.bashrc
source <(talosctl completion bash)

# Or install system-wide
talosctl completion bash | sudo tee /etc/bash_completion.d/talosctl
After enabling completion, restart your shell or source your configuration file for changes to take effect.

Configuration

talosctl stores its configuration in ~/.talos/config by default. This file contains:
  • Cluster endpoints (API server addresses)
  • Authentication certificates and keys
  • Context information (which cluster you’re managing)

Configuration File Location

The default location is ~/.talos/config, but you can override it:
# Use custom config file
export TALOSCONFIG=/path/to/custom/config
talosctl version

# Or specify per-command
talosctl --talosconfig /path/to/custom/config version

Initial Configuration

When you create your first cluster, talosctl automatically generates the configuration:
# Create a local cluster (generates config automatically)
talosctl cluster create

# Or generate config for existing infrastructure
talosctl gen config my-cluster https://cluster-endpoint:6443
The configuration file contains sensitive authentication material. Protect it with appropriate file permissions (typically 0600).

Version Management

Check Compatibility

Verify version compatibility between your CLI and cluster:
# Show both client and server versions
talosctl version
Output shows:
  • Client: Your local talosctl version
  • Server: The Talos version running on cluster nodes
Major version mismatches between talosctl and Talos nodes may cause compatibility issues. Always try to keep versions in sync.

Installing Multiple Versions

You can maintain multiple talosctl versions for different clusters:
# Install versions with explicit names
curl -Lo /usr/local/bin/talosctl-1.12 \
  https://github.com/siderolabs/talos/releases/download/v1.12.0/talosctl-linux-amd64

curl -Lo /usr/local/bin/talosctl-1.13 \
  https://github.com/siderolabs/talos/releases/download/v1.13.0/talosctl-linux-amd64

chmod +x /usr/local/bin/talosctl-*

# Use specific version
talosctl-1.12 version --client
talosctl-1.13 version --client

# Symlink to switch default
ln -sf /usr/local/bin/talosctl-1.13 /usr/local/bin/talosctl

Updating talosctl

Keep talosctl up to date with the latest features and bug fixes:
brew upgrade talosctl

Uninstalling talosctl

To remove talosctl from your system:
brew uninstall talosctl

Troubleshooting

The talosctl binary is not in your PATH. Add the installation directory to your PATH:
# For bash/zsh
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
Or move the binary to a directory already in your PATH:
sudo mv talosctl /usr/local/bin/
You need elevated privileges to install to /usr/local/bin:
sudo curl -sL https://talos.dev/install | sudo sh
Or install to a user-writable location:
curl -Lo ~/.local/bin/talosctl https://github.com/siderolabs/talos/releases/download/v1.13.0/talosctl-linux-amd64
chmod +x ~/.local/bin/talosctl
If you see warnings about version mismatches:
# Check versions
talosctl version

# Update talosctl to match cluster version
curl -Lo /usr/local/bin/talosctl https://github.com/siderolabs/talos/releases/download/v1.13.0/talosctl-linux-amd64
chmod +x /usr/local/bin/talosctl
If you encounter authentication errors:
  1. Verify your config file exists:
    ls -la ~/.talos/config
    
  2. Check file permissions:
    chmod 600 ~/.talos/config
    
  3. Verify cluster endpoints:
    talosctl config info
    
  4. Regenerate config if needed:
    talosctl gen config my-cluster https://cluster-endpoint:6443
    

Next Steps

Now that you have talosctl installed, you’re ready to create and manage Talos clusters:

Quickstart

Create your first local cluster in minutes using Docker.

CLI Reference

Explore all available talosctl commands and options.

Configuration

Learn about Talos machine configuration and cluster setup.

Production Deployment

Deploy Talos on bare metal, VMs, or cloud infrastructure.

Additional Resources

Build docs developers (and LLMs) love