Struct UpgradeArgs 

pub struct UpgradeArgs {
    pub version: Option<String>,
    pub check: bool,
    pub status: bool,
    pub force: bool,
    pub rollback: bool,
    pub no_backup: bool,
}

Command-line arguments for the AGPM upgrade command.

This structure defines all the options and flags available for upgrading AGPM to newer versions. The upgrade command provides multiple modes of operation from simple version checking to full upgrades with rollback support.

Command Modes

The upgrade command operates in several distinct modes:

Update Modes

• Check Only (--check): Check for updates without installing
• Status Display (--status): Show current and latest version information
• Upgrade to Latest: Default behavior when no version specified
• Upgrade to Specific Version: When version argument is provided

Safety Modes

• Normal Upgrade: Creates backup and upgrades with safety checks
• Force Upgrade (--force): Bypass version checks and force installation
• No Backup (--no-backup): Skip backup creation (not recommended)
• Rollback (--rollback): Restore from previous backup

Examples

Basic Usage

# Check for available updates
agpm upgrade --check

# Show version status
agpm upgrade --status

# Upgrade to latest version
agpm upgrade

Version-Specific Upgrades

# Upgrade to specific version
agpm upgrade 0.4.0
agpm upgrade v0.4.0

# Force upgrade even if already on target version
agpm upgrade 0.4.0 --force

Safety and Recovery

# Upgrade without creating backup (risky)
agpm upgrade --no-backup

# Rollback to previous version
agpm upgrade --rollback

Safety Features

• Automatic Backups: Creates backup of current binary before upgrade
• Rollback Support: Can restore previous version if upgrade fails
• Version Validation: Validates version strings and availability
• Network Error Handling: Graceful handling of connectivity issues
• Permission Checks: Validates write access before attempting upgrade

Fields

version: Option<String>

Target version to upgrade to (e.g., “0.4.0” or “v0.4.0”).

When specified, AGPM will attempt to upgrade to this specific version instead of the latest available version. The version string can be provided with or without the ‘v’ prefix.

Version Formats

• "0.4.0" - Semantic version number
• "v0.4.0" - Version with ‘v’ prefix (GitHub tag format)
• "0.4.0-beta.1" - Pre-release versions
• "0.4.0-rc.1" - Release candidate versions

Behavior

• If not specified, upgrades to the latest available version
• Version must exist as a GitHub release with binary assets
• Can be older than current version when used with --force
• Invalid version strings will cause the command to fail

Examples

agpm upgrade 0.4.0        # Upgrade to specific stable version
agpm upgrade v0.5.0-beta  # Upgrade to beta version
agpm upgrade 0.3.0 --force # Downgrade to older version

check: bool

Check for updates without installing.

When enabled, performs a version check against GitHub releases but does not download or install anything. This is useful for automation, CI/CD pipelines, or when you want to know about updates without immediately upgrading.

Behavior

• Fetches latest release information from GitHub
• Compares with current version using semantic versioning
• Displays update availability and version information
• Exits with status 0 regardless of update availability
• Caches version information for future use

Output Examples

# When update is available
Update available: 0.3.14 -> 0.4.0
Run `agpm upgrade` to install the latest version

# When up to date
You are on the latest version (0.4.0)

Use Cases

• CI/CD Integration: Check for updates in automated pipelines
• Notification Scripts: Alert when updates become available
• Manual Workflow: Check before deciding whether to upgrade
• Development: Verify release publication without upgrading

status: bool

Show current version and latest available.

Displays comprehensive version information including the current AGPM version and the latest available version from GitHub releases. Uses cached version information when available to avoid unnecessary API calls.

Information Displayed

• Current version of the running AGPM binary
• Latest version available on GitHub (if reachable)
• Update availability status
• Cache status (when version info was last fetched)

Caching Behavior

• First checks local cache for recent version information
• Falls back to GitHub API if cache is expired or missing
• Updates cache with fresh information when fetched
• Gracefully handles network errors by using cached data

Output Examples

# When update is available
Current version: 0.3.14
Latest version:  0.4.0 (update available)

# When up to date
Current version: 0.4.0 (up to date)

# When network is unavailable
Current version: 0.3.14
(Unable to check for latest version)

Use Cases

• Quick Status Check: See version info without upgrading
• Troubleshooting: Verify current version during support
• Documentation: Include version info in bug reports
• Development: Check version alignment across environments

force: bool

Force upgrade even if already on latest version.

Bypasses version comparison checks and forces the upgrade process to proceed regardless of the current version. This is useful for reinstalling corrupted binaries, downgrading, or testing.

Behavior Changes

• Skips “already up to date” checks
• Downloads and installs even if target version <= current version
• Enables downgrading to older versions
• Still performs all safety checks (backup, checksum verification)
• Respects other flags like --no-backup

Use Cases

• Reinstallation: Fix corrupted or modified binaries
• Downgrading: Install older version for compatibility
• Testing: Verify upgrade mechanism functionality
• Recovery: Restore known-good version after problems
• Development: Install specific versions for testing

Safety Considerations

Force mode still maintains safety features:

• Creates backups unless --no-backup is specified
• Verifies download checksums for integrity
• Validates that target version exists and has binary assets
• Provides rollback capability if installation fails

Examples

# Reinstall current version
agpm upgrade --force

# Downgrade to older version
agpm upgrade 0.3.0 --force

# Force upgrade to specific version
agpm upgrade 0.4.0 --force

rollback: bool

Rollback to previous version from backup.

Restores the AGPM binary from the backup created during the most recent upgrade. This provides a quick recovery mechanism if the current version has issues or if you need to revert to the previous version.

Rollback Process

1. Validates that a backup file exists
2. Replaces current binary with backup copy
3. Preserves file permissions and metadata
4. Implements retry logic for Windows file locking
5. Provides success/failure feedback

Requirements

• A backup must exist from a previous upgrade
• Backup file must be readable and valid
• Write permissions to the AGPM binary location
• Current binary must not be locked by running processes

Error Conditions

• No backup file found (never upgraded with backup enabled)
• Backup file is corrupted or unreadable
• Insufficient permissions to replace current binary
• File locking prevents replacement (Windows)

Platform Considerations

• Windows: Implements retry logic for file locking issues
• Unix: Preserves executable permissions and ownership
• All Platforms: Validates backup integrity before restoration

Examples

# Simple rollback
agpm upgrade --rollback

# Check if backup exists first
ls ~/.local/bin/agpm.backup  # Unix example
agpm upgrade --rollback

Post-Rollback

After successful rollback:

• Previous version functionality is restored
• Version cache is not automatically cleared
• Future upgrades will work normally

no_backup: bool

Skip creating a backup before upgrade.

Disables the automatic backup creation that normally occurs before upgrading the AGPM binary. This removes the safety net of being able to rollback if the upgrade fails or the new version has issues.

⚠️ WARNING

Using this flag is not recommended for most users. Backups provide crucial recovery capability with minimal overhead. Only disable backups in specific scenarios where they cannot be created or are unnecessary.

When to Consider Using

• Disk Space Constraints: Extremely limited storage where backup would cause space issues
• Permission Issues: File system permissions prevent backup creation
• Read-Only Installations: When binary is in read-only file system
• Container Environments: Ephemeral environments where persistence is not needed
• Alternative Backups: When external backup mechanisms are in place

Risks

Without backups:

• No automatic rollback if upgrade fails
• Cannot use agpm upgrade --rollback command
• Must manually reinstall if new version has issues
• Requires external recovery mechanisms

Alternative Recovery

If backups are disabled, ensure alternative recovery methods:

• Package manager installation (reinstall via brew, apt, etc.)
• Manual download from GitHub releases
• Container image rollback
• Version control system with binary tracking

Examples

# Upgrade without backup (not recommended)
agpm upgrade --no-backup

# Force upgrade without backup
agpm upgrade 0.4.0 --force --no-backup

# Check-only mode (backups not relevant)
agpm upgrade --check

Trait Implementations

impl Args for UpgradeArgs

fn group_id() -> Option<Id>

Report the ArgGroup::id for this set of arguments

fn augment_args<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate Self via FromArgMatches::from_arg_matches_mut

fn augment_args_for_update<'b>(__clap_app: Command) -> Command

Append to Command so it can instantiate self via FromArgMatches::update_from_arg_matches_mut

impl CommandFactory for UpgradeArgs

fn command<'b>() -> Command

Build a Command that can instantiate Self.

fn command_for_update<'b>() -> Command

Build a Command that can update self.

impl Debug for UpgradeArgs

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl FromArgMatches for UpgradeArgs

fn from_arg_matches(__clap_arg_matches: &ArgMatches) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn from_arg_matches_mut( __clap_arg_matches: &mut ArgMatches, ) -> Result<Self, Error>

Instantiate Self from ArgMatches, parsing the arguments as needed.

fn update_from_arg_matches( &mut self, __clap_arg_matches: &ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

fn update_from_arg_matches_mut( &mut self, __clap_arg_matches: &mut ArgMatches, ) -> Result<(), Error>

Assign values from ArgMatches to self.

impl Parser for UpgradeArgs

fn parse() -> Self

Parse from std::env::args_os(), exit on error.

fn try_parse() -> Result<Self, Error>

Parse from std::env::args_os(), return Err on error.

fn parse_from<I, T>(itr: I) -> Self

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Parse from iterator, exit on error.

fn try_parse_from<I, T>(itr: I) -> Result<Self, Error>

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Parse from iterator, return Err on error.

fn update_from<I, T>(&mut self, itr: I)

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Update from iterator, exit on error.

fn try_update_from<I, T>(&mut self, itr: I) -> Result<(), Error>

where I: IntoIterator<Item = T>, T: Into<OsString> + Clone,

Update from iterator, return Err on error.