Entitlement Tokens via the CLI

In the following examples:

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)

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

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:

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

Note

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

Note

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

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

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

Note

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:

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

Note

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:

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