# Install headscale-cli with Homebrew, apk, dnf, Nix, pacman, zypper CLI for headscale, an open-source implementation of the Tailscale control server. Version 0.29.2 via Homebrew; verified 2026-07-02. ## Install ```sh sudo av install brew:headscale-cli ``` Additional install commands: ### macOS - Homebrew (100%): ```sh brew install headscale-cli ``` Evidence: local Homebrew formula metadata ### Linux - apk (92%): ```sh sudo apk add headscale ``` Evidence: Alpine Linux edge package indexes: headscale from https://dl-cdn.alpinelinux.org/alpine/edge/community/x86_64/APKINDEX.tar.gz - dnf (92%): ```sh sudo dnf install headscale ``` Evidence: Fedora Rawhide package metadata: headscale from https://dl.fedoraproject.org/pub/fedora/linux/development/rawhide/Everything/x86_64/os/repodata/e5ca8ce900cd68f5419e1c39ae517343100b306336cbaeb70a3c153121d95094-primary.xml.zst - Nix (92%): ```sh nix profile install nixpkgs#headscale ``` Evidence: nixpkgs package indexes: pkgs/by-name/he/headscale/package.nix from https://api.github.com/repos/NixOS/nixpkgs/git/trees/master?recursive=1 - pacman (92%): ```sh sudo pacman -S headscale ``` Evidence: Arch Linux sync databases: headscale from https://geo.mirror.pkgbuild.com/extra/os/x86_64/extra.db.tar.gz - zypper (92%): ```sh sudo zypper install headscale ``` Evidence: openSUSE Tumbleweed package metadata: headscale from https://download.opensuse.org/tumbleweed/repo/oss/repodata/be8d3611d25469107f32075a1697e69ec57a2b850b42348a658cc671ad5ec2b50760d02c3e59524d50da9a11d5be799bdaffba2e166e8ca8858512e3c0bd665d-primary.xml.zst ## Package facts - **Package key:** brew:headscale-cli - **Package manager:** Homebrew - **Package manager page:** - **Version:** 0.29.2 - **Source summary:** CLI for headscale, an open-source implementation of the Tailscale control server - **Homepage:** - **Repository:** - **Upstream docs:** - **License:** BSD-3-Clause - **Source archive:** - **Last updated:** 2026-07-02T02:01:09Z - **Generated:** 2026-07-09T07:20:21+00:00 ## Executables - headscale (cli) - headscale (alias) ## Build dependencies - go ## Install behavior - Post-install hook: not defined - Bottle: available on arm64_linux, arm64_sequoia, arm64_sonoma, arm64_tahoe, sonoma, x86_64_linux ## Freshness - Page generated: 2026-07-09 - Package-manager version: 0.29.2 - Package-manager updated: 2026-07-02 - Local data: ok - Upstream repository: https://github.com/juanfont/headscale - Upstream latest detected: v0.29.2 (current) ## Project history and usage headscale-cli is the packaged command-line client for Headscale, an open source, self-hosted implementation of the Tailscale control server. The package exists for operators who want the `headscale` executable on a workstation without installing the full server formula. ### Project history Headscale's repository was created in June 2020, after Tailscale popularized WireGuard-based private overlay networks with a proprietary coordination server. The upstream README states the design goal plainly: implement a self-hosted, open source alternative to the Tailscale control server for self-hosters, hobbyists, personal networks, and small open source organizations. The CLI is part of the same Go codebase as the server. It manages users, nodes, pre-auth keys, routes, DNS, policies, API keys, and other control-plane state. The remote CLI path became important when operators wanted to administer a server from another machine rather than SSHing into the host. Headscale 0.13.0 added API key support and remote control of headscale via CLI. The remote CLI documentation requires a server version of 0.13.0 or newer, TLS, an API key, and environment variables for the CLI address and key. ### Adoption history Headscale adoption is tied to the self-hosted networking community and to users who like Tailscale clients but want to operate their own control plane. The repository's popularity and package spread across Homebrew, Nix, Alpine, Fedora, Arch, and openSUSE ecosystems show that it became a standard item in self-hosting package sets. The separate Homebrew headscale-cli packaging reflects a practical operator split: servers run on Linux or containers, while administrative workstations may be macOS laptops that only need the client binary. ### How it is used Local usage starts with built-in help and server-side actions such as creating users, registering nodes, and generating pre-auth keys. Remote usage creates an API key on the server, installs the same-version headscale binary on the workstation, sets HEADSCALE_CLI_ADDRESS and HEADSCALE_CLI_API_KEY, and then runs commands such as `headscale nodes list` against the remote instance. The CLI is also part of automated Headscale operations: scripts can create users, manage registration keys, list or expire nodes, and inspect routes without touching the database directly. ### Why package nerds care headscale-cli is a package-nerd favorite because it separates admin tooling from daemon deployment. The Homebrew package lets a macOS or Linux workstation manage a Headscale server while the server itself might be installed from a distro package, container image, NixOS module, or source build. It is also a good example of packaging around a monorepo executable: the upstream project ships one binary, while package managers can expose a CLI-only formula to avoid pulling users into a server service lifecycle they did not ask for. ### Timeline - 2020-06: Headscale repository created. - 2022-02: 0.13.0 added API key support and remote CLI control. - 2022-02: Remote CLI documentation described same-version client and server requirements. - 2023-02: Headscale was presented at FOSDEM as an integration-testing driven reimplementation of Tailscale. - 2026-02: 0.28.0 continued compatibility work around tags, API shape, and Tailscale semantics. - 2026-06: 0.29.0 documented further Tailscale ACL compatibility improvements. ### Related projects - Tailscale is the upstream client ecosystem and proprietary hosted control server that Headscale reimplements for self-hosting. - WireGuard is the encrypted tunnel technology used by Tailscale clients. - DERP, MagicDNS, ACLs, routes, and OIDC are related Tailscale/Headscale control-plane concepts managed through Headscale. - NixOS modules, container images, and Linux distro packages are common deployment companions for the server while headscale-cli is used from an admin workstation. ### Sources - - - - - - - - ## Security Notes broad file, network, media, or database tool signal. - **Geiger risk:** blue / medium - broad file, network, media, or database tool signal ## Source Database Details - **Source Database:** Homebrew formula API - **Tap:** homebrew/core - **Full Name:** headscale-cli - **Version Scheme:** 0 - **Revision:** 0 - **Bottle Stable Root URL:** - **Deprecated:** no - **Disabled:** no - **Keg Only:** no - **URL Keys:** stable ## Other Package-Manager Records - Nix - headscale: installed executable or alias match | nixpkgs package indexes: pkgs/by-name/he/headscale/package.nix from https://api.github.com/repos/NixOS/nixpkgs/git/trees/master?recursive=1 - apk - headscale - 0.27.1-r5: installed executable or alias match | Alpine Linux edge package indexes: headscale from https://dl-cdn.alpinelinux.org/alpine/edge/community/x86_64/APKINDEX.tar.gz | Open source, self-hosted implementation of the Tailscale control server | https://github.com/juanfont/headscale - apk - headscale-bash-completion - 0.27.1-r5: installed executable or alias match | Alpine Linux edge package indexes: headscale-bash-completion from https://dl-cdn.alpinelinux.org/alpine/edge/community/x86_64/APKINDEX.tar.gz | Bash completions for headscale | https://github.com/juanfont/headscale - apk - headscale-fish-completion - 0.27.1-r5: installed executable or alias match | Alpine Linux edge package indexes: headscale-fish-completion from https://dl-cdn.alpinelinux.org/alpine/edge/community/x86_64/APKINDEX.tar.gz | Fish completions for headscale | https://github.com/juanfont/headscale - apk - headscale-openrc - 0.27.1-r5: installed executable or alias match | Alpine Linux edge package indexes: headscale-openrc from https://dl-cdn.alpinelinux.org/alpine/edge/community/x86_64/APKINDEX.tar.gz | Open source, self-hosted implementation of the Tailscale control server (OpenRC init scripts) | https://github.com/juanfont/headscale - apk - headscale-zsh-completion - 0.27.1-r5: installed executable or alias match | Alpine Linux edge package indexes: headscale-zsh-completion from https://dl-cdn.alpinelinux.org/alpine/edge/community/x86_64/APKINDEX.tar.gz | Zsh completions for headscale | https://github.com/juanfont/headscale - dnf - headscale - 0.28.0-1.fc45: installed executable or alias match | Fedora Rawhide package metadata: headscale from https://dl.fedoraproject.org/pub/fedora/linux/development/rawhide/Everything/x86_64/os/repodata/e5ca8ce900cd68f5419e1c39ae517343100b306336cbaeb70a3c153121d95094-primary.xml.zst | Self-hosted implementation of the Tailscale control server | https://github.com/juanfont/headscale - pacman - headscale - 0.28.0-1: installed executable or alias match | Arch Linux sync databases: headscale from https://geo.mirror.pkgbuild.com/extra/os/x86_64/extra.db.tar.gz | An open source, self-hosted implementation of the Tailscale coordination server. | https://github.com/juanfont/headscale - zypper - headscale - 0.28.0-1.4: installed executable or alias match | openSUSE Tumbleweed package metadata: headscale from https://download.opensuse.org/tumbleweed/repo/oss/repodata/be8d3611d25469107f32075a1697e69ec57a2b850b42348a658cc671ad5ec2b50760d02c3e59524d50da9a11d5be799bdaffba2e166e8ca8858512e3c0bd665d-primary.xml.zst | An open source, self-hosted implementation of the Tailscale control server | https://headscale.net ## Related links - [Source-control packages](https://www.automicvault.com/pkg/source-control-tools/) - Belongs to a source-control command family. - [Secret-risk packages](https://www.automicvault.com/pkg/secret-risk-packages/) - Has protected-tool coverage, approval-gate, or non-low Geiger security signals. - [Terminal utility packages](https://www.automicvault.com/pkg/terminal-utilities/) - Matched terminal and command-line workflow metadata. - [Networking and protocol packages](https://www.automicvault.com/pkg/networking-protocol-tools/) - Matched network, protocol, or remote-service metadata. - [go](https://www.automicvault.com/pkg/brew/go/) - Build dependency declared by Homebrew. - [boringtun](https://www.automicvault.com/pkg/brew/boringtun/) - Shares av.db curated category or tags: cli, networking, vpn, wireguard. - [tailscale](https://www.automicvault.com/pkg/brew/tailscale/) - Shares av.db curated category or tags: cli, networking, vpn, wireguard. - [wgcf](https://www.automicvault.com/pkg/brew/wgcf/) - Shares av.db curated category or tags: cli, networking, vpn, wireguard. - [wireguard-go](https://www.automicvault.com/pkg/brew/wireguard-go/) - Shares av.db curated category or tags: cli, networking, vpn, wireguard. - [wireguard-tools](https://www.automicvault.com/pkg/brew/wireguard-tools/) - Shares av.db curated category or tags: cli, networking, vpn, wireguard. - [dsvpn](https://www.automicvault.com/pkg/brew/dsvpn/) - Shares av.db curated category or tags: cli, networking, vpn. - [edgevpn](https://www.automicvault.com/pkg/brew/edgevpn/) - Shares av.db curated category or tags: cli, networking, vpn. - [fastd](https://www.automicvault.com/pkg/brew/fastd/) - Shares av.db curated category or tags: cli, networking, vpn. - [openfortivpn](https://www.automicvault.com/pkg/brew/openfortivpn/) - Local package facts share a topical domain. Shared terms: cli, networking, open, vpn. ## Combined YAML source View the package source record on GitHub. [combined/headscale-cli.yml](https://github.com/automic-vault/db/blob/main/combined/headscale-cli.yml) ## Sources - Nucleus package database - Geiger risk classifier - package-page enrichment - curated package history - package version freshness - av.db category and tag curation - package relationship graph - external package-manager database matches - cross-ecosystem install command graph