Add --tag option to download command

[opswithranjan]

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.

[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.

[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.

[BartoszBlizniak]

Overall looks good - Got a few questions:

1. 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).
2. Integration test for the tag appears to be missing (you have core tests ✅)
3. The --tag, --os and --arch appear to be case sensitive, while --name isn't, should this be the case (no pun intended 😄)?

[BartoszBlizniak]

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

[opswithranjan]

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

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

[opswithranjan]

Thanks @BartoszBlizniak
All valid points!

1. 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.
2. You're right - I will add an integration test for the tag filtering.
3. 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!