Entitlements via the CLI

In the following examples:

Identifier

Description

OWNER

Your Cloudsmith account name or organisation name (namespace)

REPOSITORY

Your Cloudsmith Repository name (also called "slug")

IDENTIFIER

The unique identifier for an Entitlement Token

TOKEN-NAME

The name of an Entitlement Token

TOKEN-STRING

The 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)

ents list commandents list command

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
ents list --show-tokens optionents list --show-tokens option

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:

ents create commandents create command

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
cloudsmith ents deletecloudsmith ents delete

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
ents refresh commandents refresh command

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
ents update --name commandents update --name command

ents update --name command

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

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:

cloudsmith ents sync commandcloudsmith ents sync command

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:

cloudsmith ents list examples-repocloudsmith ents list examples-repo

cloudsmith ents list examples-repo

cloudsmith ents list demo repocloudsmith ents list demo repo

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 Flag

Description

--limit-bandwidth

The 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-unit

The unit of bandwidth to limit by.

--limit-num-clients

The 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-downloads

The 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-query

The 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-query

The 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-from

The starting date/time (UTC) that the token is allowed to be used from.

--limit-date-range-to

The ending date/time (UTC) that the token is allowed to be used until.

--refresh-token

The 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

Did this page help you?