A Rust CLI tool and library for building and managing multiple versions of WordPress plugins from any git reference (branch, tag, commit, PR, or GitHub Release).

Built for developers and QA engineers who need to quickly build plugins from specific PRs, switch between versions, and automate version management.

Run apvm --help for full usage or apvm <command> --help for command-specific options.

For extended CLI documentation, see the CLI crate README.

• Build from any git ref — branch, tag, commit SHA, or PR number
• Download from GitHub Releases — skip the build entirely and download pre-built assets from a GitHub Release (e.g., release:5.6.8). Currently available for BackWPup
• Special keyword refs — use tag:latest-stable, tag:latest, release:latest-stable, release:latest (and their previous-* variants) to dynamically resolve the most recent tags or releases without knowing the exact version
• Automatic ref detection — v1.0.0 resolves to a tag, develop to a branch, 123 to PR #123, and version-like inputs (e.g., 5.6.8) are checked against GitHub Releases first (when the plugin supports releases)
• Multi-variant builds — e.g., BackWPup produces free, pro-de, and pro-en variants. You can choose which ones to build (free and pro-en are the defaults for BackWPup)
• Version handling — required, embedded (auto-detected), or optional per plugin (BackWPup requires a version at build time; WP Rocket auto-detects it from source)
• Self-update — apvm update downloads and replaces the binary with the latest release, verifying SHA-256 checksums
• Self-uninstall — apvm uninstall cleanly removes the binary and its directory (with -y/--yes to skip confirmation)
• GitHub token auto-resolution — automatically finds tokens from config, GITHUB_TOKEN, GH_TOKEN, gh auth token, or the gh CLI config file

• Rust ≥ 1.94.1 (2024 edition)
• Git installed and in PATH
• GitHub authentication for private repositories (optional for public). The tool auto-detects tokens from multiple sources (config file, environment variables, gh CLI)
• Plugin-specific build tools (npm, composer, gulp, rsync, zip, etc.) as needed (try apvm info [plugin-name] to learn more about a specific plugin)

Install the latest pre-built binary with a single command — no Rust toolchain required.

If the tool was already installed, executing this again will attempt to update to latest stable version available.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/wp-media/automation-plugin-version-manager/develop/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/wp-media/automation-plugin-version-manager/develop/install.ps1 | iex

The installer will:

• Detect your OS and architecture
• Download the correct binary from the latest GitHub release
• Verify its SHA-256 checksum
• Install it to ~/.apvm/bin/ and add it to your PATH

To override the install directory, set APVM_INSTALL before running:

APVM_INSTALL=/opt/apvm curl -fsSL https://raw.githubusercontent.com/wp-media/automation-plugin-version-manager/develop/install.sh | sh

If you have the Rust toolchain installed, you can build and install from source via cargo install:

cargo install --path crates/cli

This compiles in release mode and places the apvm binary in ~/.cargo/bin/, which should already be in your PATH.

Just execute the same script for quick installation.

After pulling changes or switching branches, reinstall with --force to overwrite the existing binary:

cargo install --path crates/cli --force

The --force flag is required when reinstalling a package at the same version number.

For local development (unoptimized, faster compile):

cargo build

Binary at target/debug/apvm.

This repository includes a Node.js package powered by napi-rs, exposed as apvm-napi.

import { Apvm } from 'apvm-napi';

const apvm = await Apvm.create();
const output = await apvm.buildFromBranch('wp-rocket', 'develop', '/tmp/apvm-output');
console.log(output.result.artifacts.map((a) => a.filename));

For extended documentation about the Node.js bindings, see the NAPI crate README.

# Build from a branch
apvm build backwpup develop -v 5.1.0

# Build from a tag
apvm build backwpup v5.1.0 -v 5.1.0

# Build from a PR number
apvm build backwpup 123 -v 5.1.0

# Build from a commit SHA
apvm build backwpup abc1234 -v 5.1.0

# Explicit ref prefixes
apvm build backwpup tag:v5.1.0 -v 5.1.0
apvm build backwpup branch:develop -v 5.1.0
apvm build backwpup commit:abc1234 -v 5.1.0
apvm build backwpup pr:123 -v 5.1.0

# Download pre-built assets from a GitHub Release (no build required)
apvm build backwpup release:5.6.8

# Special keyword refs — latest/previous tags and releases
apvm build backwpup tag:latest-stable -v 5.1.0
apvm build backwpup tag:latest -v 5.1.0
apvm build backwpup release:latest-stable
apvm build backwpup release:latest

# Build specific variants only
apvm build backwpup 123 -v 5.1.0 --variants free,pro-en

# Specify output directory (default: current directory)
apvm build backwpup 123 -v 5.1.0 ./dist

# Verbose output (shows commands and full output)
apvm --verbose build backwpup 123 -v 5.1.0

Ref auto-detection rules:

Special keyword refs:

Tags are sorted by creation date (most recent first). Releases are fetched from the GitHub Releases API. Drafts are always excluded from release keywords.

apvm list

apvm info backwpup
apvm info wp-rocket

Shows repository, version requirement, available variants, and required build tools.

# Show all settings
apvm config

# Get a specific value
apvm config get token

# Set GitHub token (required for private repos and PR builds)
apvm config set token ghp_xxxxxxxxxxxx

# Set custom builds directory
apvm config set builds-dir /path/to/builds

# Remove a value (revert to default)
apvm config unset token

# Show config file path
apvm config path

apvm update

Downloads the latest release from GitHub, verifies the SHA-256 checksum, and atomically replaces the running binary. Supports macOS (arm64/x64), Linux (x64/arm64), and Windows (x64).

# Interactive (asks for confirmation)
apvm uninstall

# Skip confirmation
apvm uninstall -y

Removes the apvm binary and its bin/ directory. Does not remove configuration or build artifacts.

The CLI and NAPI bindings resolve a GitHub token from multiple sources, checked in order:

1. Config file — apvm config set token ghp_xxx
2. GITHUB_TOKEN environment variable
3. GH_TOKEN environment variable
4. gh auth token command (gh CLI ≥ 2.17.0)
5. gh CLI config file — ~/.config/gh/hosts.yml

A token is required for private repositories (e.g., BackWPup) and for building from PR numbers. It is optional for public repositories but recommended for higher API rate limits (5,000 vs 60 requests/hour).

RUST_LOG=debug apvm build backwpup 123 -v 5.1.0
RUST_LOG=trace apvm build backwpup 123 -v 5.1.0

Tracing is only enabled when RUST_LOG is set. See the tracing-subscriber EnvFilter docs for filter syntax.

crates/
├── cli/        CLI binary (clap-based), owns defaults and user interaction
├── config/     Pure configuration types (no I/O, no defaults)
├── core/       Core library: building, git, GitHub API, version detection
├── napi/       Node.js N-API bindings (napi-rs cdylib)
└── storage/    Artifact storage, deduplication, manifests, queries

• Config — pure serde types for configuration. No file I/O, no hardcoded paths.
• Core — orchestrates builds (clone → fetch → resolve ref → checkout → detect version → build → collect artifacts), downloads from GitHub Releases, git operations, and GitHub API via octocrab. For extended documentation, see the Core crate README.
• Storage — manages artifacts with commit-based deduplication, cross-platform links (symlinks on Unix, junctions on Windows), and a fluent query API.
• NAPI — Node.js bindings via napi-rs. Exposes the core library as a native addon with async support on the tokio runtime. For extended documentation, see the NAPI crate README.
• CLI — owns default paths (~/.apvm, ~/apvm-builds), provides progress display via indicatif, and delegates all logic to core. For extended documentation, see the CLI crate README.

# All tests
cargo test

# Specific crate
cargo test -p apvm-core
cargo test -p apvm-storage
cargo test -p apvm-config
cargo test -p apvm

# Node.js tests (Vitest)
npm test

The project uses GitHub Actions for continuous integration (ci.yml).

MIT — see package.json and crate manifests.