Package Search Syntax

Cloudsmith provides a powerful and flexible query language that enables you to instantly find any package, in any repository, based on a comprehensive set of attributes. This syntax can be used in multiple areas of the product.

Our search syntax allows you to move beyond simple name-based searches and build highly specific queries using a wide range of criteria, including package format, version, size, upload date, dependencies, and even policy violation status. By combining these terms with boolean operators (AND, OR, NOT) and advanced matching logic, you can construct precise filters to isolate the exact artifacts you need, directly from the Web UI, API, or CLI.

Note

📘 The search syntax is fully "boolean", in that you can combine queries together with AND (i.e. find this AND that), or OR (i.e. find this OR that), or NOT (i.e. find NOT this). This is optional, if you don't put any boolean operators (AND/OR) in, we'll just assume that you want AND by default.

Search Terms

For all queries you can use:
~ for negation. (Example: ~foo)

For string queries you can use:
^ - to anchor to start of term. (Example: ^foo)
$ - to anchor to end of term. (Example: foo$)
* - for fuzzy matching. (Example: foo*bar)

For number or date queries you can use:
> - for values greater than. (Example: >foo)
>= - for values greater / equal. (Example: >=foo)
< - for values less than. (Example: <foo)
<= - for values less / equal. (Example: <=foo)

Please note, when you use a query like uploaded: >'1 month ago', that becomes uploaded > dd/mm/yy (i.e, within the last month).

For version queries you can use:
> - for versions greater than. (Example: >1.2.3.)
>= - for versions greater / equal. (Example: >=1.2.3)
< - for versions less than. (Example: <1.2.3)
<= - for versions less / equal. (Example: <=1.2.3)
~= - for versions greater than or equal to, upto the next incompatible version. (Example: ~=1.2.0)

Note

Remember: You can use any combination of AND, OR and NOT. You can use parentheses to group terms if required, as AND has a higher precedence than OR, and it may change the meaning of queries without it.

A Short Working Example

Suppose that you had the following packages:

• AlphaLib, Version: 1.0
• AlphaLib, Version: 1.1
• AlphaLib, Version: 2.0
• BetaLib: Version: 0.9

To find "AlphaLib" packages that are in the version 1.x series only, your query would be:
name:^AlphaLib$ AND version:~=1.0.

Which would provide the following results:

• AlphaLib, Version: 1.0
• AlphaLib, Version: 1.1

To bring the query down, we added the following parts:

• name:^AlphaLib$ - Find a package name that is exactly "AlphaLib". Without the ^ (starts-with) and $ (ends-with), the query would be fuzzy, and potentially find packages called "AlphaLib2" or "FreeAlphaLib" too.
• AND - We want to search for both the name and version together. Both must match for the results.
• version:~=1.0 - Find package versions that are at-least 1.0, upto the next incompatible version (2.0).

Searching Packages via the Cloudsmith web app

At the top of every page is the search box:

Additional help and examples are available by hovering over the "? Search syntax" at the right side of the search box.

Searching Packages via the Cloudsmith API

Please see the Cloudsmith full API reference to learn how to:

• List all of the packages in a Workspace (Organization).
• List all of the packages in a Repository.

Then, you can use the query field in the URL request to search a package by any of the next fields:

• name
• filename
• version
• distribution
• architecture
• format
• status

For example, to retrieve all packages named ms:

curl -sL --request GET \
  --url "https://api.cloudsmith.io/v1/packages/<MY_WORKSPACE>/<MY_REPO>/?query=name:ms" \
  --header 'Authorization: Bearer <MY_API_TOKEN>'

Alternatively, you can use jq to search for a package in a repository by using any of the fields available in the json returned by the request. For example:

curl -sL "https://api.cloudsmith.io/v1/packages/<MY_WORKSPACE>/<MY_REPO>/" \
  --header 'Authorization: Bearer <MY_API_TOKEN>' \
  | jq '.[] | select(.name == "requests")'

Searching Packages via the Cloudsmith CLI

To search packages using the Cloudsmith CLI, you use the cloudsmith list packages command in combination with the -q option:

cloudsmith list packages OWNER/REPOSITORY -q "SEARCH_TERMS"

Example
To search for all debian packages:

cloudsmith list packages cloudsmith/examples -q "format:deb"

Example
To search for the latest rpm and composer packages:

cloudsmith list packages cloudsmith/examples -q "tag:latest AND (format:rpm OR format:composer)"

Example
To search for all python packages larger than 2KB with more than 50 downloads:

cloudsmith list packages cloudsmith/examples -q "format:python AND downloads:>50 AND size:>2048"

Sorting Packages

Sorting Packages via the Cloudsmith web app

At the top of each repository packages page is the sorting dropdown:

The available sorting options are:

• Name (A-Z)
• Name (Z-A)
• Uploaded At (Oldest FIrst)
• Uploaded At (Newest First)
• Size (Smallest First)
• Size (Biggest First)
• Total Downloads (Ascending)
• Total Downloads (Descending)

Note that currently, the UI only supports sorting by one field at a time.

Sorting Packages via the Cloudsmith API

Please see the Cloudsmith full API reference to learn how to:

• List all of the packages in a Workspace (Organization).
• List all of the packages in a Repository.

Then, use the sort option to rank the result by any or many or the sort fields listed in the next section.

For example, to retrieve all of the packages of the workspace <MY_WORKSPACE> organized by ascending number of downloads:

curl -sL --request GET \
  --url "https://api.cloudsmith.io/v1/packages/<MY_WORKSPACE>/?sort=downloads" \
  --header 'Authorization: Bearer <MY_API_TOKEN>'

Sorting search results is simple with Cloudsmith. A collection of one or more fields can be supplied in CSV (comma-separated value) format, and the results will be sorted based on the order of the fields provided.

Sort Fields

For all fields you can use:
- to sort by descending order. (Example: -date, -version)

A Short Worked Example

Suppose that you had the following packages:

To sort packages by size descending, your sort query would be:

-size

Which would provide the following results

• cloudsmith-java-app, Size: 6910 bytes
• cloudsmith-example-cli, Size: 722 bytes
• cloudsmith-example-cli, Size: 719 bytes
• cloudsmith-example-pdf, Size: 309 bytes

To sort packages by format alphabetically, with version descending, your sort query would be:

-format,-version

Which would provide the following results:

• cloudsmith-java-app, Format: Maven, Version: 1.0.0
• cloudsmith-example-cli, Format: Python, Version: 1.2.0
• cloudsmith-example-cli, Format: Python, Version: 1.1.5
• cloudsmith-example-pdf, Format: Raw, Version: 1.1.0

Sorting combined with Searching

Sorting can also be combined with querying. If you wanted to sort by most downloaded Python packages, your query and sort would be:

query=format:python&sort=-downloads

Which would provide the following results:

• cloudsmith-example-cli, Format: Python, Version: 1.2.0, Downloads: 1000
• cloudsmith-example-cli, Format: Python, Version: 1.2.0, Downloads: 500