Skip to content

CLI Upgrade Command

The upgrade-cli command checks for and installs updates to the Sites CLI tool.

Overview

The upgrade command allows you to: - Check for available CLI updates - Install the latest CLI version - Keep your CLI up to date with new features and security fixes

Global Flags

  • --debug, -d, --verbose - Show debug information
  • --insecure, -k - Skip TLS certificate verification
  • --force, -f, -y, --yes - Force operations without prompting
  • --output, -o - Output format: json, yaml, or table

Command

sitesctl upgrade-cli

Check for and install CLI updates.

Usage: 

sitesctl upgrade-cli [flags]

Flags:

  • --check - Check for available upgrade without installing
  • Default: false (will install if update available)
  • Use to preview updates before installing

Examples:

# Check and install available upgrades
sitesctl upgrade-cli

# Only check for upgrades (don't install)
sitesctl upgrade-cli --check

# Check with JSON output
sitesctl upgrade-cli --check --output json

# Install with debug information
sitesctl upgrade-cli --debug

What it does:

Without --check flag: 1. Connects to the ECMWF update server 2. Checks for newer CLI versions 3. If update available: - Downloads the new version - Verifies checksum (MD5) - Replaces the current binary - Reports success 4. If no update available: - Reports "No upgrades available"

With --check flag: 1. Connects to the update server 2. Checks for newer versions 3. Verifies the update package 4. Reports if upgrade is available 5. Does NOT install the update

Output Messages:

Message Meaning
"Upgrade available" Newer version exists (check mode)
"No upgrades available" You have the latest version
"Upgrade successful" New version installed
"Please restart the CLI to use the new version" Restart needed after upgrade

Versioning

CLI versions follow this format: 

YYYYMMDD.HHMM

Example: 20240227.1430 - 20240227 - Release date: February 27, 2024 - 1430 - Release time: 14:30

Version comparison: - Newer timestamps = newer versions - Easy to identify release dates - Multiple releases possible per day

Check your version: 

sitesctl --version
# or
sitesctl -v

Automatic Upgrade Checks

The CLI can automatically check for updates in the background.

Configuration:

Enable/disable in config: 

# Enable automatic checks (default)
sitesctl config auto-upgrade --value=true

# Disable automatic checks
sitesctl config auto-upgrade --value=false

# Check current setting
sitesctl config show

How it works: - When enabled, the CLI checks for updates ~10% of the time - Checks happen on random command executions - Prevents slowdown on every command - If a newer version is found, the CLI downloads and replaces the binary - The new version takes effect on the next CLI invocation - Manual upgrade is still available

Behavior: 

# With auto-upgrade enabled
$ sitesctl list
Checking for upgrades, please wait...
Upgrade successful
Please restart the CLI to use the new version
[normal command output]

# Next invocation uses the new version
$ sitesctl --version

Update Process

Before Upgrading

  1. Check current version: 

    sitesctl --version

  2. Verify connectivity: 

    sitesctl upgrade-cli --check

  3. Review what's new (check release notes if available)

During Upgrade

  1. CLI downloads new binary from ECMWF update server
  2. Verifies MD5 checksum for integrity
  3. Replaces the running binary
  4. Reports success/failure

Important: Don't interrupt the upgrade process

After Upgrading

  1. Verify new version: 

    sitesctl --version

  2. Test basic functionality: 

    sitesctl auth whoami

  3. Review any breaking changes in release notes

Rollback

If the upgrade causes issues:

Built-in rollback: - If verification fails, CLI automatically rolls back - No manual action needed

Manual rollback: - Reinstall previous version from ECMWF repository - Download from: https://get.ecmwf.int/service/rest/v1/search/assets/?repository=sites-cli - Or restore from backup if you made one

Best Practices

Regular Updates

  1. Check monthly for updates
  2. Enable auto-checks for notifications
  3. Update regularly for security patches
  4. Test after upgrade to ensure compatibility

Production Environments

  1. Test first in development environment
  2. Review changes before upgrading
  3. Schedule upgrades during maintenance windows
  4. Backup scripts that depend on CLI
  5. Document CLI version in project requirements

CI/CD Systems

Pin CLI version for reproducibility: 

# Download specific version
curl -L -O https://get.ecmwf.int/repository/sites-cli/linux/sitesctl-20240227.1430

# Verify checksum
md5sum sitesctl-20240227.1430

# Install
chmod +x sitesctl-20240227.1430
mv sitesctl-20240227.1430 /usr/local/bin/sitesctl

Or use latest in development: 

# In CI pipeline
sitesctl upgrade-cli
sitesctl --version

Troubleshooting

Cannot Connect to Update Server

Problem: 

Error: Could not connect to update server

Solutions: - Check internet connectivity - Verify firewall allows HTTPS to get.ecmwf.int - Try with --insecure if certificate issues (not recommended) - Check if behind a corporate proxy

Checksum Verification Failed

Problem: 

Error: Checksum verification failed

Solutions: - Retry the upgrade (may be download corruption) - Check available disk space - Report to support if persists

Permission Denied

Problem: 

Error: Permission denied

Solutions: 

# Run with appropriate permissions
sudo sitesctl upgrade-cli

# Or if installed in user directory
sitesctl upgrade-cli

Upgrade Fails Silently

Problem: Upgrade reports success but version unchanged

Solutions: - Check if CLI binary is in a read-only location - Verify you have write permissions - Run with --debug for more information - Check if binary is in use by another process

Version Confusion

Problem: --version shows old version after upgrade

Solutions: - Restart your terminal session - Check if multiple CLI installations exist - Verify PATH order 

which sitesctl
sitesctl --version

Scripting Examples

Check and Upgrade in Script

#!/bin/bash
# Upgrade CLI if needed

check_output=$(sitesctl upgrade-cli --check 2>&1)

if echo "$check_output" | grep -q "Upgrade available"; then
  echo "Upgrade available. Installing..."
  sitesctl upgrade-cli
  echo "Upgrade complete. Version: $(sitesctl --version)"
else
  echo "Already at latest version: $(sitesctl --version)"
fi

Upgrade with Notification

#!/bin/bash
# Upgrade and send notification

old_version=$(sitesctl --version)

sitesctl upgrade-cli

new_version=$(sitesctl --version)

if [ "$old_version" != "$new_version" ]; then
  echo "CLI upgraded from $old_version to $new_version" | \
    mail -s "Sites CLI Upgraded" admin@example.com
  echo "Upgraded: $old_version -> $new_version"
else
  echo "No upgrade performed. Version: $new_version"
fi

Pre-commit Hook for Version Check

#!/bin/bash
# .git/hooks/pre-commit
# Warn if CLI version is old

current_version=$(sitesctl --version | grep -oE '[0-9]{8}\.[0-9]{4}')
check_output=$(sitesctl upgrade-cli --check 2>&1)

if echo "$check_output" | grep -q "Upgrade available"; then
  echo "WARNING: Newer Sites CLI version is available"
  echo "Current version: $current_version"
  echo "Run: sitesctl upgrade-cli"
  echo ""
fi

# Continue with commit
exit 0

Automated Weekly Upgrade

#!/bin/bash
# Cron job: 0 2 * * 0 (weekly on Sunday at 2 AM)

logfile="/var/log/sitesctl-upgrade.log"

{
  echo "=== Upgrade Check: $(date) ==="

  sitesctl upgrade-cli --check

  if [ $? -eq 0 ]; then
    sitesctl upgrade-cli
    echo "New version: $(sitesctl --version)"
  fi

  echo ""
} >> "$logfile" 2>&1

Update Sources

The CLI downloads updates from ECMWF's official repository:

Repository URL: 

https://get.ecmwf.int/repository/sites-cli/

Available platforms: - Linux (x86_64) - macOS (x86_64, ARM64) - Windows (x86_64)

Selection: The CLI automatically detects your platform and downloads the appropriate binary.

Security

Verification

  • All downloads are verified with MD5 checksum
  • Downloads use HTTPS (encrypted connection)
  • Binaries are signed by ECMWF
  • Automatic rollback on verification failure

Trust

  • Updates come only from official ECMWF servers
  • Cannot be modified in transit (HTTPS + checksum)
  • Automatic verification before installation
  • Safe to enable auto-checks

Recommendations

  1. Enable auto-checks for security notifications
  2. Upgrade promptly when security fixes are released
  3. Verify source - only upgrade via sitesctl or official downloads
  4. Use official binaries - don't use third-party builds

Manual Installation

If upgrade-cli doesn't work, manually download and install:

Linux / macOS

# Download latest version
platform="linux"  # or "darwin" for macOS
curl -L -O "https://get.ecmwf.int/repository/sites-cli/${platform}/sitesctl-latest"

# Make executable
chmod +x sitesctl-latest

# Replace current installation
sudo mv sitesctl-latest /usr/local/bin/sitesctl

# Verify
sitesctl --version

Windows

  1. Download from repository via web browser
  2. Replace existing sitesctl.exe
  3. Verify version in PowerShell: sitesctl --version

Release Information

Where to find release notes: - ECMWF Sites documentation: https://sites.ecmwf.int/docs/sites/ - Support portal: https://support.ecmwf.int - Internal announcements (if applicable)

Typical update schedule: - Security fixes: As needed - Bug fixes: Monthly - New features: Quarterly - Major versions: Annually

Upgrade recommendations: - Security updates: Install immediately - Bug fixes: Install within a week - New features: Test in development, then upgrade - Major versions: Review breaking changes, plan migration

See Also