Install plexctl

plexctl is the operator client for the plexsphere /v1 API. Download a prebuilt binary from the plexsphere download page, or build it from source.

Option A — download a prebuilt binary (recommended)

Statically-linked binaries for Linux, macOS, and Windows are published to the plexsphere download page at get.plexsphere.com, alongside a SHA256SUMS manifest you verify the download against. Pick the file that matches your platform:

Platform	File
Linux x86-64	plexctl-linux-amd64
Linux arm64	plexctl-linux-arm64
macOS Apple silicon	plexctl-darwin-arm64
macOS Intel	plexctl-darwin-amd64
Windows x86-64	plexctl-windows-amd64.exe

Download

Fetch the binary for your platform and the checksum manifest into the same directory. For example, on Linux x86-64:

curl -fLO https://get.plexsphere.com/plexctl-linux-amd64
curl -fLO https://get.plexsphere.com/SHA256SUMS

Verify and install

Confirm the checksum before trusting the binary, then drop it on your $PATH.

On Linux:

sha256sum --ignore-missing -c SHA256SUMS
chmod +x plexctl-linux-amd64
sudo install -m 0755 plexctl-linux-amd64 /usr/local/bin/plexctl
plexctl --version

On macOS, shasum ships in place of sha256sum — substitute the darwin-arm64 (Apple silicon) or darwin-amd64 (Intel) file for your hardware:

shasum -a 256 --ignore-missing -c SHA256SUMS
chmod +x plexctl-darwin-arm64
sudo install -m 0755 plexctl-darwin-arm64 /usr/local/bin/plexctl
plexctl --version

On the first run macOS may block the binary under Gatekeeper. Clear the quarantine flag with xattr -d com.apple.quarantine plexctl, or approve the binary under System Settings → Privacy & Security.

On Windows, verify the hash with PowerShell, then place the binary on a directory in your PATH (renaming it to plexctl.exe):

Get-FileHash .\plexctl-windows-amd64.exe -Algorithm SHA256
# compare the printed hash against the matching line in SHA256SUMS

Option B — build from source

Prefer to build it yourself, or need a platform the download page does not list? Clone the repository and run the Makefile target.

Prerequisites

• A Go toolchain matching /.go-version (Go 1.26). See ../../contributing/toolchain.md.
• make and git on $PATH.
• A directory on $PATH for the binary (~/.local/bin, /usr/local/bin, …).

Build the binary

git clone https://github.com/plexsphere/plexsphere.git
cd plexsphere
make plexctl-build
# → bin/plexctl (stamped with the build metadata)

make plexctl-build compiles cmd/plexctl/ into bin/plexctl and stamps the build metadata. Building with a bare go build produces an unstamped 0.0.0-dev binary that is not suitable for incident reports — always use the Makefile target.

Install onto $PATH

install -m 0755 bin/plexctl ~/.local/bin/plexctl   # user-local
sudo install -m 0755 bin/plexctl /usr/local/bin/plexctl   # system-wide

Enable shell completion

plexctl completion bash | sudo tee /etc/bash_completion.d/plexctl >/dev/null

Replace bash with zsh, fish, or powershell as needed; see ../../reference/cli/plexctl/completion.md for the per-shell install path.

Verification

plexctl --version
# version=<version> commit=<sha> date=<rfc3339>

version is whatever git describe --tags --always --dirty resolved to at link time. A downloaded release binary prints its release tag; a binary you built yourself from a checkout with no reachable tag prints the short commit sha, so version and commit read the same — that is expected, not a broken stamp. A version=0.0.0-dev line does mean the binary was built without the Makefile ldflags — rebuild with make plexctl-build.

See also

• Log in with plexctl — the first device-code login.
• ../../reference/cli/plexctl.md — the full CLI reference.