plexsphere

Appearance

Install plexctl ​

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

Every release publishes the same statically-linked binaries for Linux, macOS, and Windows through two channels:

  • the plexsphere download page at get.plexsphere.com, which anyone can reach and which mirrors the newest release; and
  • the assets of the GitHub Release, which only members of the plexsphere organisation can download while the repository is private.

Both channels carry a SHA256SUMS manifest and a cosign signature bundle per binary, named after the binary with a .sigstore.json suffix. Pick the file that matches your platform:

PlatformFile
Linux x86-64plexctl-linux-amd64
Linux arm64plexctl-linux-arm64
macOS Apple siliconplexctl-darwin-arm64
macOS Intelplexctl-darwin-amd64
Windows x86-64plexctl-windows-amd64.exe

Download from the download page ​

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

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

Download from the GitHub Release ​

Organisation members fetch the same files with the GitHub CLI, naming the release they want in place of vX.Y.Z:

shell
gh release download vX.Y.Z --repo plexsphere/plexsphere \
  --pattern 'plexctl-linux-amd64*' --pattern SHA256SUMS

The first pattern matches the binary and its .sigstore.json bundle.

Verify the signature ​

The release workflow signs every binary with cosign keyless signing. Check the bundle before you trust the binary: it proves the file was built by the release workflow of the plexsphere repository for a release tag. Install cosign first, then:

shell
cosign verify-blob --bundle plexctl-linux-amd64.sigstore.json \
  --certificate-identity-regexp '^https://github\.com/plexsphere/plexsphere/\.github/workflows/release\.yaml@refs/tags/v[0-9]+\.[0-9]+\.[0-9]+$' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
  plexctl-linux-amd64

Verified OK means the signature holds. When you know the release you downloaded, pin it exactly: replace the pattern with --certificate-identity https://github.com/plexsphere/plexsphere/.github/workflows/release.yaml@refs/tags/vX.Y.Z.

Verify the checksum and install ​

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

On Linux:

shell
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:

shell
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):

powershell
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 ​

shell
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 ​

shell
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 ​

shell
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 ​

shell
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 ​