Entitlements via the CLI

In the following examples:

IdentifierDescription
OWNERYour Cloudsmith account name or organisation name (namespace)
REPOSITORYYour Cloudsmith Repository name (also called "slug")
IDENTIFIERThe unique identifier for an Entitlement Token
TOKEN-NAMEThe name of an Entitlement Token
TOKEN-STRINGThe token itself - It must only contain alphanumerics, dashes, dots or underscores and it must begin with an alphanumeric.

Listing Entitlement Tokens

To view all entitlement tokens for a repository, you use the cloudsmith ents list command:

cloudsmith ents list OWNER/REPOSITORY

Example:

cloudsmith ents list demo/examples-repo

This will show all the tokens associated with a repository and their creation / updated date and identifier. The token identifier is unique to each individual entitlement token and is quite important, as you use it with other entitlement commands (such as delete)

968

ents list command

Note that by default, the token itself is not shown. To see the token, you must add the --show-tokens option to the command. For example:

cloudsmith ents list demo/examples-repo --show-tokens
970

ents list --show-tokens option


Creating Entitlement Tokens

To create an entitlement token via the Cloudsmith CLI, you use the cloudsmith ents command:

cloudsmith ents create OWNER/REPOSITORY --name=TOKEN-NAME

Example:

cloudsmith ents create demo/examples-repo --name=TestToken

The entitlement token identifier is shown in the output of the cloudsmith create command:

968

ents create command

Additionally, you can manually specify the token itself (rather than have Cloudsmith create it for you) using the --token=TOKEN-STRING option:

cloudsmith ents create demo/examples-repo --name=TestToken --token=abcdef123456

📘

If you manually specify a token, it must be between 8 - 48 characters in length. It must only contain alphanumerics, dashes, dots or underscores and it must begin with an alphanumeric.

Batch Create Example

If you wanted to create a batch of Entitlement Tokens at once, you could script it with a loop using the Cloudsmith CLI:

for I in $(seq 1 10); do
  cloudsmith ents create OWNER/REPOSITORY --name "Customer $I"
done

You could then retrieve a list of all entitlements, plus their tokens with:

cloudsmith ents ls OWNER/REPOSITORY --show-tokens -F json | jq -r '.data[] | "\(.name) = \(.token)"'

Deleting Entitlement Tokens

Before you can delete an entitlement token, you need to get the identifier for the entitlement token. This can be obtained from the cloudsmith ents list command or from the cloudsmith ents create command.

To delete an entitlement token, you use the cloudsmith ents delete command:

cloudsmith ents delete OWNER/REPOSITORY/IDENTIFIER

Example:

cloudsmith ents delete demo/example-repo/Ym4xadpEU4YS
966

cloudsmith ents delete

📘

A deleted token will still be able to be used for static assets (that are cached at the Package Delivery Network) for approximately 10 minutes until the PDN has to re-authenticate once its cache expires


Refreshing Entitlement Tokens

Refreshing an entitlement token generates a new token, but retains any permissions granted by the token. This has the effect of invalidating the current token.

You can refresh an entitlement token using the cloudsmith ents refresh command:

cloudsmith ents refresh OWNER/REPOSITORY/IDENTIFIER

Example:

cloudsmith ents refresh demo/examples-repo/RJol6tyAIssl
969

ents refresh command

The example above shows the TestToken before and after using the cloudsmith ents refresh command.


Updating Entitlement Tokens

To modify a token name or the token itself, you use the cloudsmith ents update command:

cloudsmith ents update OWNER/REPOSITORY/IDENTIFIER --name=TOKEN-NAME --token=TOKEN-STRING

Examples:

cloudsmith ents update demo/examples-repo/RJol6tyAIssl --name=NewTestToken
969

ents update --name command

cloudsmith ents update demo/examples-repo/RJol6tyAIssl --token=abcedf123456
968

ents update --token command

📘

A refreshed token will still be able to be used for static assets (that are cached at the Package Delivery Network) for approximately 10 minutes until the PDN has to re-authenticate once its cache expires


Synchronising Tokens

You can synchronise all of the entitlement tokens from one Repository to another Repository using the cloudsmith ents sync command:

cloudsmith ents sync OWNER/TARGET-REPO  SOURCE-REPO

Example:

cloudsmith ents sync demo/demo-repo examples-repo

This example synchronises all the entitlement tokens from the examples-repo repository to the demo-repo repository:

967

cloudsmith ents sync command

If we now list the entitlement tokens in each of these repositories, we can see that they contain the same entitlement tokens:

967

cloudsmith ents list examples-repo

969

cloudsmith ents list demo repo

📘

The token identifiers are still unique to each token, the token names and any associated permissions that the tokens grant are synchronised.


Token Restrictions

You can add usage restrictions to a token with the cloudsmith ents restrict command:

cloudsmith ents restrict OWNER/REPOSITORY/IDENTIFIER <restriction-flags>

The available flags that you can add to set restrictions are:

Restrict Command FlagDescription
--limit-bandwidthThe maximum download bandwidth allowed for the token. Please note that since downloads are calculated asynchronously (after
the download happens), the limit may not be imposed immediately but at a later point.
--limit-bandwidth-unitThe unit of bandwidth to limit by. Note that 1GB = 1000000000 Bytes.
--limit-num-clientsThe maximum number of unique clients allowed for the token. Please note that since clients are calculated asynchronously (after the download happens), the limit may not be imposed immediately but at a later point.
--limit-num-downloadsThe maximum number of downloads allowed for the token. Please note that since downloads are calculated asynchronously (after the download happens), the limit may not be imposed immediately but at a later point.
--limit-package-queryThe package-based search query to apply to restrict downloads to. This uses the same syntax as the standard search used for repositories (see Searching / Filtering for more details). This will still allow access to non-package files, such as metadata. For package formats that support dynamic metadata indexes, the contents of the metadata will also be filtered.
--limit-path-queryThe path-based search query to apply to restrict downloads to. This supports boolean logic operators such as OR/AND/NOT and parentheses for grouping. The path evaluated does not include the domain name, the namespace, the entitlement code used, the package format, etc. and it always starts with a forward slash.
--limit-date-range-fromThe starting date/time (UTC) that the token is allowed to be used from.
--limit-date-range-toThe ending date/time (UTC) that the token is allowed to be used until.
--refresh-tokenThe reset period used will be used to automatically trigger a reset of the token limits. Available options are daily, weekly, fortnightly, monthly, bi-monthly, quarterly and annual

For Example:

cloudsmith entitlements restrict demo/examples-repo/GYwg00eEElKs \
        --limit-bandwidth=1 \
        --limit-bandwidth-unit=gigabyte \
        --limit-num-clients=10 \
        --limit-num-downloads=1000 \
        --limit-package-query="package-darwin-amd64"  \
        --limit-path-query=tag:latest \
        --limit-date-range-from=2020-01-01T00:00:00Z \
        --limit-date-range-to=2077-01-01T00:00:00Z \
        --refresh-token=daily

Token Usage Metrics

You can check the bandwidth usage and token metrics for a repository with the cloudsmith metrics command:

Repository Usage

You can check the total bandwidth usage for a repository with the cloudsmith metrics tokens command:

cloudsmith metrics tokens OWNER/REPOSITORY

Example:

cloudsmith metrics tokens demo/examples-repo

Specific Token Usage

To check the bandwidth used by a specific token you add the --tokens parameter and the token identifier, or a comma-separated list of token identifiers, to the cloudsmith metrics tokens command:

cloudsmith metrics tokens OWNER/REPOSITORY --tokens=IDENTIFIER

Example:

cloudsmith metrics tokens demo/examples-repo --tokens= YcLoVS7BsLHf

In addition, you can add the --start and --finish parameters, to display usage for a specific time period:

Example:

cloudsmith metrics tokens demo/examples-repo --tokens=YcLoVS7BsLHf \
--start=2020-04-01T00:00:00Z --finish=2020-09-07T00:00:00Z


Cloudsmith is the new standard in Package / Artifact Management and Software Distribution

With support for all major package formats, you can trust us to manage your software supply chain.


Start My Free Trial Now
Cookie Declaration (Manage Cookies)