cli: Add tag-aware upgrade operations

Implement bootc upgrade --tag and --list-tags to simplify
tag-based image version management for customers who version
images using tags.

This adds:
- bootc upgrade --tag <tag>: Upgrade to different tag of current image
- bootc upgrade --list-tags: List available tags from registry
- Automatic composition with --check for verification

The --tag option derives the target image by replacing the tag
portion of the current booted image reference. Only works when
booted from registry transport images.

Organizations version container images with tags (:latest, :dev,
:test, :prod) and this allows them to upgrade between versions
without retyping full registry paths or using switch (which is
semantically about changing images, not versions).

Assisted-by: Claude Sonnet 4.5
Signed-off-by: gursewak1997 <gursmangat@gmail.com>

Author: gursewak1997

crates/lib/src/cli.rs

@@ -29,6 +29,8 @@ use indoc::indoc;
 use ostree::gio;
 use ostree_container::store::PrepareResult;
 use ostree_ext::container as ostree_container;
+use ostree_ext::container::Transport;
+use ostree_ext::oci_spec;
 
 use ostree_ext::keyfileext::KeyFileExt;
 use ostree_ext::ostree;
@@ -123,6 +125,17 @@ pub(crate) struct UpgradeOpts {
     #[clap(long, conflicts_with_all = ["check", "download_only"])]
     pub(crate) from_downloaded: bool,
 
+    /// Upgrade to a different tag of the currently booted image.
+    ///
+    /// This derives the target image by replacing the tag portion of the current
+    /// booted image reference. Only works when booted from a registry image.
+    #[clap(long)]
+    pub(crate) tag: Option<String>,
+
+    /// List available tags for the currently booted image repository.
+    #[clap(long, conflicts_with_all = ["apply", "download_only", "from_downloaded"])]
+    pub(crate) list_tags: bool,
+
     #[clap(flatten)]
     pub(crate) progress: ProgressOptions,
 }
@@ -1047,7 +1060,26 @@ async fn upgrade(
     let repo = &booted_ostree.repo();
 
     let host = crate::status::get_status(booted_ostree)?.1;
-    let imgref = host.spec.image.as_ref();
+
+    // Handle --list-tags: show available tags and exit
+    if opts.list_tags {
+        let current_image = host.spec.image
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("No image source specified in booted deployment"))?;
+        return list_tags_for_current_image(current_image).await;
+    }
+
+    // Handle --tag: derive target from current image + new tag
+    let derived_image = if let Some(ref tag) = opts.tag {
+        let current_image = host.spec.image
+            .as_ref()
+            .ok_or_else(|| anyhow::anyhow!("No image source specified in booted deployment"))?;
+        Some(derive_image_with_tag(current_image, tag)?)
+    } else {
+        None
+    };
+
+    let imgref = derived_image.as_ref().or_else(|| host.spec.image.as_ref());
     let prog: ProgressWriter = opts.progress.try_into()?;
 
     // If there's no specified image, let's be nice and check if the booted system is using rpm-ostree
@@ -1220,6 +1252,70 @@ async fn upgrade(
     Ok(())
 }
 
+/// Derive a new image reference by replacing the tag of the current image
+fn derive_image_with_tag(current: &ImageReference, new_tag: &str) -> Result<ImageReference> {
+    // Only works for registry transport
+    if current.transport()? != Transport::Registry {
+        anyhow::bail!(
+            "The --tag option only works with registry images, current transport is '{}'",
+            current.transport
+        );
+    }
+
+    // Parse the current image reference
+    let reference: oci_spec::distribution::Reference = current.image.parse()?;
+
+    // Build new image reference with the new tag (stripping any digest)
+    let registry = reference.registry();
+    let repository = reference.repository();
+    let new_image = format!("{}/{}:{}", registry, repository, new_tag);
+
+    Ok(ImageReference {
+        image: new_image,
+        transport: current.transport.clone(),
+        signature: current.signature.clone(),
+    })
+}
+
+/// List available tags for the current image repository
+async fn list_tags_for_current_image(current: &ImageReference) -> Result<()> {
+    // Only works for registry transport
+    if current.transport()? != Transport::Registry {
+        anyhow::bail!(
+            "The --list-tags option only works with registry images, current transport is '{}'",
+            current.transport
+        );
+    }
+
+    // Parse the image to extract repository (without tag/digest)
+    let reference: oci_spec::distribution::Reference = current.image.parse()?;
+
+    // Construct repository name: registry + repository
+    let registry = reference.registry();
+    let repository = reference.repository();
+    let repo_name = format!("{}/{}", registry, repository);
+
+    let repo = format!("docker://{}", repo_name);
+
+    // Use skopeo to list tags
+    let output = tokio::process::Command::new("skopeo")
+        .arg("list-tags")
+        .arg(&repo)
+        .output()
+        .await
+        .context("Failed to execute skopeo")?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        anyhow::bail!("Failed to list tags: {}", stderr);
+    }
+
+    let stdout = String::from_utf8_lossy(&output.stdout);
+    println!("{}", stdout);
+
+    Ok(())
+}
+
 pub(crate) fn imgref_for_switch(opts: &SwitchOpts) -> Result<ImageReference> {
     let transport = ostree_container::Transport::try_from(opts.transport.as_str())?;
     let imgref = ostree_container::ImageReference {
@@ -2203,6 +2299,78 @@ mod tests {
         assert_eq!(args.as_slice(), ["container", "image", "pull"]);
     }
 
+    #[test]
+    fn test_parse_upgrade_options() {
+        // Test upgrade with --tag
+        let o = Opt::try_parse_from(["bootc", "upgrade", "--tag", "v1.1"]).unwrap();
+        match o {
+            Opt::Upgrade(opts) => {
+                assert_eq!(opts.tag, Some("v1.1".to_string()));
+                assert!(!opts.list_tags);
+            }
+            _ => panic!("Expected Upgrade variant"),
+        }
+
+        // Test upgrade with --list-tags
+        let o = Opt::try_parse_from(["bootc", "upgrade", "--list-tags"]).unwrap();
+        match o {
+            Opt::Upgrade(opts) => {
+                assert!(opts.tag.is_none());
+                assert!(opts.list_tags);
+            }
+            _ => panic!("Expected Upgrade variant"),
+        }
+
+        // Test that --list-tags and --apply are mutually exclusive
+        let result = Opt::try_parse_from(["bootc", "upgrade", "--list-tags", "--apply"]);
+        assert!(result.is_err());
+
+        // Test that --list-tags and --download-only are mutually exclusive
+        let result = Opt::try_parse_from(["bootc", "upgrade", "--list-tags", "--download-only"]);
+        assert!(result.is_err());
+
+        // Test that --tag works with --check (should compose naturally)
+        let o = Opt::try_parse_from(["bootc", "upgrade", "--tag", "v1.1", "--check"]).unwrap();
+        match o {
+            Opt::Upgrade(opts) => {
+                assert_eq!(opts.tag, Some("v1.1".to_string()));
+                assert!(opts.check);
+            }
+            _ => panic!("Expected Upgrade variant"),
+        }
+    }
+
+    #[test]
+    fn test_derive_image_with_tag() {
+        // Test basic tag replacement
+        let current = ImageReference {
+            image: "quay.io/example/myapp:v1.0".to_string(),
+            transport: "registry".to_string(),
+            signature: None,
+        };
+        let result = derive_image_with_tag(&current, "v1.1").unwrap();
+        assert_eq!(result.image, "quay.io/example/myapp:v1.1");
+        assert_eq!(result.transport, "registry");
+
+        // Test tag replacement with digest (digest should be stripped)
+        let current_with_digest = ImageReference {
+            image: "quay.io/example/myapp:v1.0@sha256:abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890".to_string(),
+            transport: "registry".to_string(),
+            signature: None,
+        };
+        let result = derive_image_with_tag(&current_with_digest, "v2.0").unwrap();
+        assert_eq!(result.image, "quay.io/example/myapp:v2.0");
+
+        // Test that non-registry transport fails
+        let non_registry = ImageReference {
+            image: "/path/to/oci".to_string(),
+            transport: "oci".to_string(),
+            signature: None,
+        };
+        let result = derive_image_with_tag(&non_registry, "v1.1");
+        assert!(result.is_err());
+    }
+
     #[test]
     fn test_generate_completion_scripts_contain_commands() {
         use clap_complete::aot::{Shell, generate};

docs/src/man/bootc-upgrade.8.md

@@ -69,6 +69,21 @@ Soft reboot allows faster system restart by avoiding full hardware reboot when p
 
     Apply a staged deployment that was previously downloaded with --download-only
 
+**--tag**=*TAG*
+
+    Upgrade to a different tag of the currently booted image
+
+    This derives the target image by replacing the tag portion of the current booted image reference.
+    Only works when booted from a registry image. Can be combined with --check to verify the tag
+    without staging the deployment.
+
+**--list-tags**
+
+    List available tags for the currently booted image repository
+
+    Queries the registry for all available tags. Only works when booted from a registry image.
+    This option exits after displaying tags and does not perform an upgrade operation.
+
 <!-- END GENERATED OPTIONS -->
 
 # EXAMPLES
@@ -85,6 +100,22 @@ Upgrade with soft reboot if possible:
 
     bootc upgrade --apply --soft-reboot=auto
 
+Upgrade to a different tag:
+
+    bootc upgrade --tag v1.2
+
+List available tags for the current image:
+
+    bootc upgrade --list-tags
+
+Check if a specific tag has updates before applying:
+
+    bootc upgrade --tag prod --check
+
+Upgrade to a tag and immediately apply:
+
+    bootc upgrade --tag v2.0 --apply
+
 # SEE ALSO
 
 **bootc**(8), **bootc-switch**(8), **bootc-status**(8), **bootc-rollback**(8)