In the following examples:
Your Cloudsmith account name or organisation name (namespace)
Your Cloudsmith Repository name (also called "slug")
The unique identifier for an Entitlement Token
The name of an Entitlement Token
The token itself - It must only contain alphanumerics, dashes, dots or underscores and it must begin with an alphanumeric.
To view all entitlement tokens for a repository, you use the
cloudsmith ents list command:
cloudsmith ents list OWNER/REPOSITORY
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
To create an entitlement token via the Cloudsmith CLI, you use the
cloudsmith ents command:
cloudsmith ents create OWNER/REPOSITORY --name=TOKEN-NAME
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
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.
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)"'
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
cloudsmith ents delete demo/example-repo/Ym4xadpEU4YS
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 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
cloudsmith ents refresh demo/examples-repo/RJol6tyAIssl
The example above shows the TestToken before and after using the
cloudsmith ents refresh command.
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
cloudsmith ents update demo/examples-repo/RJol6tyAIssl --name=NewTestToken
cloudsmith ents update demo/examples-repo/RJol6tyAIssl --token=abcedf123456
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
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
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:
The token identifiers are still unique to each token, the token names and any associated permissions that the tokens grant are synchronised.
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
The maximum download bandwidth allowed for the token. Please note that since downloads are calculated asynchronously (after
The unit of bandwidth to limit by.
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.
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.
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.
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.
The starting date/time (UTC) that the token is allowed to be used from.
The ending date/time (UTC) that the token is allowed to be used until.
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
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
You can check the bandwidth usage and token metrics for a repository with the
cloudsmith metrics command:
You can check the total bandwidth usage for a repository with the
cloudsmith metrics tokens command:
cloudsmith metrics tokens OWNER/REPOSITORY
cloudsmith metrics tokens demo/examples-repo
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
cloudsmith metrics tokens demo/examples-repo --tokens= YcLoVS7BsLHf
In addition, you can add the
--finish parameters, to display usage for a specific time period:
cloudsmith metrics tokens demo/examples-repo --tokens=YcLoVS7BsLHf \ --start=2020-04-01T00:00:00Z --finish=2020-09-07T00:00:00Z
Updated about 2 months ago