Skip to content

WFCTL_INSTALLATION.md

Latest commit

 

History

History
272 lines (206 loc) · 8.09 KB

WFCTL_INSTALLATION.md

File metadata and controls

272 lines (206 loc) · 8.09 KB
Raw

wfctl Installation And Plugin Lifecycle

wfctl is published as raw release binaries, a GoCodeAlone Homebrew formula, and a Go source install. Use Homebrew when you want package-manager upgrades. Use the release binaries when you want a direct install without Homebrew.

Install wfctl

Homebrew

brew tap gocodealone/tap
brew install wfctl
wfctl --version

Upgrade with Homebrew:

brew update
brew upgrade wfctl

If a Workflow release was just published and Homebrew still shows an older formula, run brew update before checking again:

brew info gocodealone/tap/wfctl

Terminal Download Without Homebrew

Workflow releases publish raw wfctl binaries plus checksums.txt. This installer downloads the latest binary for macOS or Linux, verifies the SHA-256 checksum, and installs it into /usr/local/bin.

set -euo pipefail

os="$(uname -s | tr '[:upper:]' '[:lower:]')"
arch="$(uname -m)"
case "$arch" in
  x86_64|amd64) arch="amd64" ;;
  arm64|aarch64) arch="arm64" ;;
  *) echo "unsupported architecture: $arch" >&2; exit 1 ;;
esac
case "$os" in
  darwin|linux) ;;
  *) echo "unsupported OS: $os" >&2; exit 1 ;;
esac

asset="wfctl-${os}-${arch}"
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT

base="https://github.com/GoCodeAlone/workflow/releases/latest/download"
curl -fL "$base/$asset" -o "$tmpdir/$asset"
curl -fL "$base/checksums.txt" -o "$tmpdir/checksums.txt"

checksum_line="$(awk -v asset="$asset" '{ file = $2; sub(/^\*/, "", file); sub(/^\.\//, "", file); if (file == asset) { print $1 "  " asset; found = 1; exit } } END { if (!found) exit 1 }' "$tmpdir/checksums.txt" || true)"
if [ -z "$checksum_line" ]; then
  echo "missing checksum entry for $asset" >&2
  exit 1
fi

if command -v shasum >/dev/null 2>&1; then
  checksum_cmd=(shasum -a 256 -c -)
elif command -v sha256sum >/dev/null 2>&1; then
  checksum_cmd=(sha256sum -c -)
else
  echo "missing checksum tool: install shasum or sha256sum" >&2
  exit 1
fi

(cd "$tmpdir" && printf '%s\n' "$checksum_line" | "${checksum_cmd[@]}")
chmod +x "$tmpdir/$asset"
sudo install -d -m 0755 /usr/local/bin
sudo install -m 0755 "$tmpdir/$asset" /usr/local/bin/wfctl

wfctl --version

For a user-local install without sudo, replace the install command with:

mkdir -p "$HOME/.local/bin"
install -m 0755 "$tmpdir/$asset" "$HOME/.local/bin/wfctl"

Then ensure $HOME/.local/bin is in PATH.

Browser Download

  1. Open https://github.com/GoCodeAlone/workflow/releases/latest.
  2. Download the asset for your platform:
    • macOS Apple Silicon: wfctl-darwin-arm64
    • macOS Intel: wfctl-darwin-amd64
    • Linux x86_64: wfctl-linux-amd64
    • Linux ARM64: wfctl-linux-arm64
    • Windows x86_64: wfctl-windows-amd64.exe
  3. Download checksums.txt from the same release.
  4. Verify the checksum.

macOS or Linux:

asset=wfctl-darwin-arm64 # replace with the asset you downloaded
checksum_line="$(awk -v asset="$asset" '{ file = $2; sub(/^\*/, "", file); sub(/^\.\//, "", file); if (file == asset) { print $1 "  " asset; found = 1; exit } } END { if (!found) exit 1 }' checksums.txt || true)"
if [ -z "$checksum_line" ]; then
  echo "missing checksum entry for $asset" >&2
  exit 1
fi
if command -v shasum >/dev/null 2>&1; then
  printf '%s\n' "$checksum_line" | shasum -a 256 -c -
elif command -v sha256sum >/dev/null 2>&1; then
  printf '%s\n' "$checksum_line" | sha256sum -c -
else
  echo "missing checksum tool: install shasum or sha256sum" >&2
  exit 1
fi
chmod +x "./$asset"
sudo install -d -m 0755 /usr/local/bin
sudo install -m 0755 "./$asset" /usr/local/bin/wfctl

Replace wfctl-darwin-arm64 with the file you downloaded. On Linux, install sha256sum or shasum if neither command is available.

Windows PowerShell:

certutil -hashfile .\wfctl-windows-amd64.exe SHA256

Compare the printed hash to the wfctl-windows-amd64.exe row in checksums.txt, then place the executable in a directory on %PATH%.

From Source

Use this path when you already have Go installed and want a source build:

go install github.com/GoCodeAlone/workflow/cmd/wfctl@latest

This installs into $(go env GOPATH)/bin or $(go env GOBIN). Ensure that directory is in PATH.

Update wfctl

Homebrew installs should be updated by Homebrew:

brew update
brew upgrade wfctl

Release-binary installs can self-update:

wfctl update --check
wfctl update

wfctl update downloads the latest GitHub release for the current platform, verifies checksums.txt when available, and replaces the current executable. It is not recommended for Homebrew-managed binaries because it bypasses Homebrew's cellar and formula state.

Diagnose And Repair Local State

Use wfctl doctor to inspect the binary, workflow config, plugin manifest, lockfile, and installed project plugins without changing files:

wfctl doctor
wfctl doctor --online

Use wfctl repair to turn common project plugin diagnostics into an ordered repair plan. The default is a dry-run:

wfctl repair

Apply the automatic repairs only when the plan looks correct:

wfctl repair --apply

Automatic repair is limited to regenerating .wfctl-lock.yaml from wfctl.yaml and installing locked project plugins into data/plugins or the directory passed with --plugin-dir. Binary updates, missing project files, global plugin changes, and provider-specific fixes remain explicit manual commands.

Project Plugin Lifecycle

Workflow projects should commit a human-edited wfctl.yaml manifest and the generated .wfctl-lock.yaml lockfile. The manifest states intent; the lockfile pins resolved versions and portable archive checksums for CI.

# Find a plugin.
wfctl plugin search auth

# Add a plugin to wfctl.yaml and regenerate .wfctl-lock.yaml.
wfctl plugin add workflow-plugin-auth@v0.4.0

# Refresh the lockfile after editing wfctl.yaml.
wfctl plugin lock

# Install all locked project plugins into data/plugins.
wfctl plugin install

# CI path: install exactly from the lockfile and do not write files.
wfctl plugin ci

wfctl plugin install without a plugin argument checks wfctl.yaml and .wfctl-lock.yaml. If the lockfile is missing or stale, local installs regenerate it before installing. Use wfctl plugin ci or wfctl plugin install --locked in CI to fail on stale locks instead of modifying the checkout.

By default, project plugin install commands write to data/plugins. Override the install directory with --plugin-dir; commands that load installed project plugins may also honor WFCTL_PLUGIN_DIR as documented in their individual help.

Global Plugin Lifecycle

Global plugins are operator tools available outside a single project. They do not modify wfctl.yaml or .wfctl-lock.yaml.

wfctl plugin install -g workflow-plugin-portfolio
wfctl plugin list -g
wfctl plugin info -g workflow-plugin-portfolio
wfctl plugin update -g workflow-plugin-portfolio
wfctl plugin update -g --all
wfctl plugin remove -g workflow-plugin-portfolio

The default global directory is ${XDG_DATA_HOME:-$HOME/.local/share}/wfctl/plugins. Override it with WFCTL_GLOBAL_PLUGIN_DIR.

Project-local plugin commands take precedence over global plugin commands, so a repository can pin the plugin version it expects while operators keep global tools installed for ad hoc use.

Plugin Integrity And Compatibility

Registry installs fail closed when wfctl cannot verify plugin archive checksums. GitHub release downloads can auto-fetch checksums.txt; registry manifests can also carry SHA-256 values directly. Use --skip-checksum only for trusted internal URLs.

Registry installs and locks also resolve compatibility evidence for the current Workflow engine version. Use --compat-mode warn to allow warnings during migration, or --force only when you intentionally accept known-failing or missing compatibility evidence while keeping checksum enforcement.

Useful References