Skip to content

README.md

Latest commit

 

History

History
308 lines (220 loc) · 12.5 KB

README.md

File metadata and controls

308 lines (220 loc) · 12.5 KB

APVM CLI

The command-line interface for the Automation Plugin Version Manager. Built with Clap 4 (derive API), it provides an ergonomic terminal experience with colored output, progress spinners via indicatif, and structured debug logging via tracing.

This crate produces the apvm binary. All heavy logic is delegated to apvm-core — the CLI owns only user interaction, default paths, input sanitization, and display.

Commands

Command Description
build Build a plugin from a git reference (PR, branch, tag, commit, release)
list List all registered plugins
info Show detailed information about a plugin (repo, variants, version, tools)
config View or change configuration settings
update Download and install the latest APVM release
uninstall Remove the APVM binary from this system

Build Command

The build command is the primary command. It accepts a plugin name, a git reference, and optional flags.

apvm build <PLUGIN> <GIT_REF> [OUTPUT] [OPTIONS]

Arguments

Argument Required Default Description
<PLUGIN> Yes — Plugin name (e.g., backwpup)
<GIT_REF> Yes — Git reference (see below)
[OUTPUT] No . Output directory for build artifacts

Options

Option Short Description
--ver <VERSION> -v Package version (required for BackWPup)
--variants <LIST> Comma-separated variants (e.g., free,pro-en)
--verbose Show full command output instead of spinner

Git Reference Formats

The <GIT_REF> argument supports automatic detection or explicit prefixes:

Automatic detection (no prefix):

Input Resolved as
123 PR #123 (or branch if PR doesn't exist)
#123 PR #123 (# stripped)
develop Branch name
v1.0.0 Tag (if exists) or branch
abc1234 Commit SHA (7–40 hex characters)
5.6.8 GitHub Release (if plugin supports releases), else tag/branch

Explicit prefixes:

Prefix Example Description
pr: pr:123 Force PR interpretation
branch: branch:main Force branch interpretation
tag: tag:v1.0.0 Force tag interpretation
commit: commit:abc1234 Force commit interpretation
release: release:v5.6.8 Download from GitHub Release

Special Keyword Refs

Instead of specifying an exact tag or release version, you can use keyword shortcuts that dynamically resolve to the latest or previous reference.

Tag keywords — tags are sorted by creation date (git tag --sort=-creatordate):

Keyword Resolves to
tag:latest-stable Latest tag excluding -alpha, -beta, -rc suffixes
tag:previous-stable Previous stable tag
tag:latest Very latest tag (including prereleases)
tag:previous-latest Tag right before the latest

Release keywords — fetched from the GitHub Releases API. Drafts are always excluded:

Keyword Resolves to
release:latest-stable Latest stable release (non-prerelease, non-draft)
release:previous-stable Previous stable release
release:latest Very latest non-draft release (including prereleases)
release:previous-latest Previous non-draft release

Examples

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

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

# Download from a specific GitHub Release
apvm build backwpup release:5.6.8

# Build from the latest stable tag
apvm build backwpup tag:latest-stable -v 5.1.0

# Download the latest stable release
apvm build backwpup release:latest-stable

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

# Output to a specific directory
apvm build backwpup 123 -v 5.1.0 ./dist

# Verbose output
apvm --verbose build backwpup 123 -v 5.1.0

List Command

apvm list

Displays all registered plugins with their repository and visibility (public/private).

Info Command

apvm info <PLUGIN>

Shows detailed information about a plugin:

  • Repository URL and GitHub owner/repo
  • Default branch
  • Whether it requires authentication (private)
  • Version requirement (Required, Embedded, or Optional)
  • Default version (if any)
  • Available variants with descriptions
  • Required build tools (e.g., npm, composer, gulp, rsync, zip)

Example:

apvm info backwpup
apvm info wp-rocket

Config Command

Manages the APVM configuration file (~/.apvm/config.json).

# Show all current settings
apvm config

# Get a specific value
apvm config get token
apvm config get builds-dir

# Set a value
apvm config set token ghp_xxxxxxxxxxxx
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

Available keys:

Key Description
token GitHub Personal Access Token
builds-dir Directory to manage built artifact storage (Experimental, avoid it's use until stable)

Input values are sanitized before storage:

  • Token: trimmed, validated against known GitHub token prefixes (ghp_, gho_, ghu_, ghs_, ghr_, github_pat_). Unrecognized prefixes produce a warning but are still saved.
  • Path: expanded (~ resolved), validated as absolute.

Update Command

apvm update

Self-updates the apvm binary:

  1. Fetches the latest GitHub Release for this repository
  2. Compares the release version against the current binary version using semver
  3. Downloads the platform-appropriate binary
  4. Verifies its SHA-256 checksum against checksums.txt
  5. Atomically replaces the running binary via self-replace

Supported platforms:

OS Architecture Artifact name
macOS arm64 apvm-darwin-arm64
macOS x64 apvm-darwin-x64
Linux x64 apvm-linux-x64-gnu
Linux arm64 apvm-linux-arm64-gnu
Windows x64 apvm-win32-x64-msvc.exe

Uninstall Command

# Interactive (prompts for confirmation)
apvm uninstall

# Skip confirmation
apvm uninstall -y
apvm uninstall --yes

Removes the apvm binary and its containing bin/ directory. Uses self_replace::self_delete_outside_path for cross-platform binary deletion:

  • Unix: unlink(2) — the kernel keeps the inode alive until the process exits.
  • Windows: Renames the .exe aside, spawns a helper process with FILE_FLAG_DELETE_ON_CLOSE.

Does not remove configuration files (~/.apvm/config.json) or build artifacts (~/apvm-builds/).

GitHub Token Resolution

The CLI resolves 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 and PR builds. It is optional for public repositories but recommended for higher API rate limits (5,000 vs 60 requests/hour).

Default Paths

Path Purpose
~/.apvm/ APVM home directory
~/.apvm/config.json Configuration file
~/apvm-builds/ Default build artifacts output (experimental)

These defaults are determined using the directories crate for cross-platform home directory resolution.

Debug Logging

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 initialized when the RUST_LOG environment variable is set. The CLI uses tracing-subscriber with the EnvFilter for filter syntax.

Installation

Quick Install (recommended)

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

From Source

cargo install --path crates/cli

Development Build

cargo build
# Binary at target/debug/apvm

Dependencies

Crate Version Purpose
clap 4 CLI argument parsing (derive API)
tokio 1 Async runtime (current_thread)
indicatif 0.18 Progress bars and spinners
tracing 0.1 Structured logging
tracing-subscriber 0.3 Log formatting and filtering
semver 1 Version comparison for updates
self-replace 1 Atomic binary self-replacement
reqwest 0.13 HTTP downloads (native-tls)
sha2 0.11 SHA-256 checksum verification
directories 6 Platform home directory
tempfile 3 Staging downloaded binaries
apvm-core workspace Core build and git logic
apvm-config workspace Configuration types
apvm-storage workspace Artifact storage

Running Tests

cargo test -p apvm