Add --tag option to download command by opswithranjan · Pull Request #249 · cloudsmith-io/cloudsmith-cli

opswithranjan · 2025-12-18T19:47:43Z

Summary

This PR adds tag filtering capability to the cloudsmith download command and updates the README with comprehensive download command documentation.

Changes Made

🚀 New Feature: --tag Option

Added --tag option to cloudsmith download command for filtering packages by tags
Enhanced resolve_package() function to support tag filtering across multiple metadata fields:
- Actual package tags (info, version categories)
- Package format (deb, rpm, python, etc.)
- Architecture (arm64, amd64, etc.)
- Distribution name/version (ubuntu, noble, ubuntu/noble)
- Components (main, contrib, etc.)
Added comprehensive unit tests for tag filtering functionality

📚 Documentation Updates

Added download command to README features list
Created new "Downloading Packages" section with practical examples
Documented all filtering options including the new --tag feature
Provided examples for common use cases (version, format, arch, tag filtering)

Usage Examples

# Filter by tag
cloudsmith download org/repo package --tag latest

# Combine with other filters  
cloudsmith download org/repo package --tag stable --format deb --arch arm64

# Preview downloads
cloudsmith download org/repo package --tag beta --dry-run

Testing

All existing tests pass
New unit test test_resolve_package_with_tag_filter validates tag filtering
Syntax validation and linting compliance verified
Manual testing confirmed tag filtering works with real API responses

Breaking Changes

None - this is a backward-compatible feature addition.

Copilot

Pull request overview

This PR adds tag filtering capability to the cloudsmith download command, enabling users to filter packages by tags alongside existing filters (version, format, architecture, OS). The implementation treats various package metadata fields as "tags" beyond just the explicit tags field.

Key Changes:

Added --tag option to the download command with support for filtering by actual tags, format, architecture, distribution, and components
Enhanced package resolution logic with the new _matches_tag_filter() helper function
Updated documentation with comprehensive download command examples

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
cloudsmith_cli/core/download.py	Added `_matches_tag_filter()` function and integrated tag filtering into `resolve_package()`
cloudsmith_cli/cli/commands/download.py	Added `--tag` CLI option and updated command documentation with tag filtering example
cloudsmith_cli/core/tests/test_download.py	Added unit test covering tag filtering for actual tags, format, architecture, and distro fields
README.md	Added download command to features list and created new "Downloading Packages" section with examples

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

cloudsmith_cli/core/tests/test_download.py

cloudsmith_cli/core/download.py

README.md

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

cloudsmith_cli/core/tests/test_download.py

cloudsmith_cli/core/download.py

cloudsmith_cli/core/tests/test_download.py

Copilot

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

README.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

BartoszBlizniak

Overall looks good - Got a few questions:

I can see we're starting to use a lot of "filters" for the download command. All of these are essentially being passed to the query parameter for listing packages. From code maintenance and usability, perhaps adding package_query instead of filters could allow for a better user experience (see package list command). -> This would require some re-working as it would be a breaking change, removing the filters (Future PR).
Integration test for the tag appears to be missing (you have core tests ✅)
The --tag, --os and --arch appear to be case sensitive, while --name isn't, should this be the case (no pun intended 😄)?

BartoszBlizniak · 2026-01-09T13:13:16Z

cloudsmith_cli/core/download.py

+        if isinstance(tag_category, list) and tag_filter in tag_category:
+            return True
+
+    # Check other metadata fields that appear as tags in the UI (case-sensitive)


Might be worthwhile double-checking if Cloudsmith Tags are actually case-sensitive in the API

They are. Just retested by adding some and the API returned:

"tags": { "info": [ "RANJAN", "RanJan", "Ranjan", "trivy", "upstream" ] }

opswithranjan · 2026-01-09T14:46:38Z

Thanks @BartoszBlizniak
All valid points!

Agreed! Using package_query would be cleaner. Would be happy to tackle a migration PR that adds package_query while keeping filters as convenience aliases.
You're right - I will add an integration test for the tag filtering.
Intentional choice: --name is case-insensitive for search convenience, but --tag/--os/--arch are case-sensitive to match exact API metadata values. For example, API returns "arm64" not "ARM64", and "Ubuntu" not "ubuntu". This ensures users specify tags exactly as they appear in the API/UI. Open to making them case-insensitive if preferred for better UX, though!

opswithranjan · 2026-01-30T12:20:13Z

Addressed #2.
As for #1, since it’s gonna be a breaking change, let’s keep the current filters for now and will plan to include that in a future PR.

…ommand

estebangarcia · 2026-02-03T13:58:53Z

cloudsmith_cli/core/download.py

+    if (
+        pkg.get("format") == tag_filter
+        or any(arch.get("name") == tag_filter for arch in pkg.get("architectures", []))
+        or pkg.get("identifiers", {}).get("deb_component") == tag_filter
+    ):
+        return True
+
+    # Check distro-related fields
+    distro_name_raw = pkg.get("distro", {}).get("name")
+    distro_version_raw = pkg.get("distro_version", {}).get("name")
+    distro_combo = ""
+    if distro_name_raw and distro_version_raw:
+        # Only build combined tag when both parts are present
+        distro_combo = f"{distro_name_raw}/{distro_version_raw}"
+
+    if (
+        tag_filter == distro_name_raw
+        or tag_filter == distro_version_raw
+        or (distro_combo and tag_filter == distro_combo)
+    ):
+        return True


question: Any reason why this is also checking format, arch and distro-related things for what's only supposed to be a tag filter? Why should the user use this instead of the other existing flags for these use cases?

Great question! The reason I included format, arch, and distro fields in the tag filter is that Cloudsmith UI presents all of these as “tags” on the package details page. I wanted the --tag option to feel familiar and work the same way users see and interact with tags in the UI, even though, technically, some of those are metadata fields.

I agree it might be clearer and more consistent to have --tag only match actual tags, and require users to use --format, --arch, etc. for the other filters. I’m happy to update the implementation to do that if that feels like a better approach, just let me know your preference!

opswithranjan added 2 commits December 19, 2025 00:58

Add --tag option to download command

10396c5

Add download command in Readme

d387674

Copilot AI review requested due to automatic review settings December 18, 2025 19:47

opswithranjan requested a review from a team as a code owner December 18, 2025 19:47

Copilot started reviewing on behalf of opswithranjan December 18, 2025 19:48 View session

Copilot AI reviewed Dec 18, 2025

View reviewed changes

Add Changelog and make distro tags case case-insensitive

f06ea01

opswithranjan requested a review from Copilot December 18, 2025 20:06

Copilot started reviewing on behalf of opswithranjan December 18, 2025 20:07 View session

Copilot AI reviewed Dec 18, 2025

View reviewed changes

cloudsmith_cli/core/tests/test_download.py Outdated Show resolved Hide resolved

cloudsmith_cli/core/download.py Outdated Show resolved Hide resolved

cloudsmith_cli/core/tests/test_download.py Show resolved Hide resolved

Fix tag filtering consistency and add comprehensive tests

831ac02

opswithranjan requested a review from Copilot December 18, 2025 20:23

Copilot started reviewing on behalf of opswithranjan December 18, 2025 20:23 View session

Copilot AI reviewed Dec 18, 2025

View reviewed changes

README.md Outdated Show resolved Hide resolved

Update README.md

628c873

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

opswithranjan force-pushed the ceng-624-add-tag-option-for-cli-download-command branch from b5cf8ac to 628c873 Compare December 18, 2025 21:12

opswithranjan requested a review from BartoszBlizniak January 8, 2026 18:00

BartoszBlizniak reviewed Jan 9, 2026

View reviewed changes

add integration tests for tag filtering

90cf467

Merge branch 'master' into ceng-624-add-tag-option-for-cli-download-c…

7daa3bc

…ommand

estebangarcia reviewed Feb 3, 2026

View reviewed changes

Conversation

opswithranjan commented Dec 18, 2025

Summary

Changes Made

🚀 New Feature: --tag Option

📚 Documentation Updates

Usage Examples

Testing

Breaking Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

BartoszBlizniak left a comment

Choose a reason for hiding this comment

Uh oh!

BartoszBlizniak Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

opswithranjan Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

opswithranjan commented Jan 9, 2026

Uh oh!

opswithranjan commented Jan 30, 2026

Uh oh!

estebangarcia Feb 3, 2026

Choose a reason for hiding this comment

Uh oh!

opswithranjan Feb 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

3 participants