Using CCD via the UGS CLI

Follow this workflow to use CCD through the UGS command line interface, such as to authenticate, create buckets, manage entries, and handle releases.

Read time 15 minutes

Last updated 5 months ago

Note

The CCD UCD CLI and its walkthrough are officially deprecated and no longer receive updates. You can transition to use the UGS CLI and this UGS CLI walkthrough instead.

Authentication
Configuration
Creating a bucket
Creating entries from a set of local files
Creating a release
Managing badges

Authentication

To authenticate with the service, you need to use a service account. Ensure that your service account has the appropriate roles assigned for the required access levels:

The Organization Role Cloud Content Delivery API Public Editor grants read and write access to public endpoints of the CCD Management API.
The Project Role Unity Environments Viewer grants read access to all environments in a project.

If you don't have a service account or need to manage your existing accounts, visit the Service Account Authentication Documentation for detailed instructions on how to create or manage your service account. Once you have your service account set up and the appropriate roles assigned, you can log into the service using the command-line interface. If you encounter any issues or need additional guidance, refer to the Getting Started section for help.

Logging In Using the CLI

To log in, simply enter the following command and follow the interactive prompts:


$ ugs login

Using Environment Variables for Authentication

As an alternative to interactive login, you can also set your credentials as environment variables. This method is particularly useful for scripting or automated workflows. To do this, set the UGS_CLI_SERVICE_KEY_ID and UGS_CLI_SERVICE_SECRET_KEY environment variables with your service account's Key ID and Secret Key respectively. Example of setting environment variables (use the appropriate method for your operating system):

For Unix-based systems (Linux, macOS)


export UGS_CLI_SERVICE_KEY_ID="your_key_id"export UGS_CLI_SERVICE_SECRET_KEY="your_secret_key"

For Windows


set UGS_CLI_SERVICE_KEY_ID=your_key_idset UGS_CLI_SERVICE_SECRET_KEY=your_secret_key

After setting these environment variables, the CLI will automatically use them for authentication, eliminating the need for interactive login during your session.

Configuration

Configure the UGS CLI to target your specific project, environment, and bucket.

Set Project ID

Link the CLI to your Unity project by setting the Project ID. Replace

<project-id>

with your actual Project ID:


$ ugs config set project-id <project-id>

See the Getting started section if you need help locating your Project ID.

Set Environment Name

To find a list of environments for your project, run this command:


$ ugs env list

Specify the environment you want to use (e.g., development, staging, production) for your CLI operations. For example, to set it to production:


$ ugs env use production

The list of environment is also available from the Unity Dashboard by selecting Projects, open your project, and then selecting the Environments tab.

Set Bucket Name

If you have a bucket ready, link it to your CLI session for asset management. Replace <bucket-name> with your actual Bucket name:


$ ugs config set bucket-name <bucket-name>

These configurations ensure your CLI commands target the correct project, environment, and bucket.

Creating a bucket

Create your first bucket. Buckets are associated with a single project. List the buckets (which should be empty at this point) for this project:


$ ugs ccd buckets list

Create a bucket called

example_bucket

for this project:


$ ugs ccd buckets create example_bucket

Note

You can only edit the bucket name via the CDD Dashboard.

Bucket and entry names are case sensitive. To see the newly-created buckets, list the buckets again for this project:


$ ugs ccd buckets list

To make it easier to work with creating entries and releases, save the newly-created bucket to the local configuration (don’t provide it as a parameter to the CLI for every operation).


$ ugs config set bucket-name example_bucket

CCD will automatically performs any commands relating to entries and releases on the bucket you specified.

Creating entries in the bucket

List entries in this newly-created bucket (it should be empty): List entries


$ ugs ccd entries list

No Entries found for current bucket. Synchronize all the files in a local folder. In this example, the local folder contains generated AssetBundles as the content: Synchronize files


$ ugs ccd entries sync ./ServerData/StandaloneOSX

This adds the files as entries to the bucket. You can list the bucket’s contents and see some basic information about each entry: List bucket's contents


$ ugs ccd entries list

There should be 22 entries in the bucket. To get more detailed information about a specific entry, use the

entries info

command with the path of the entry: Get entry information


$ ugs ccd entries info spaceshooterdata_starfield.bundle

Your game client can now request content for an individual file in the bucket using the path associated with the entry. Make all game client requests to your project-specific subdomain at

<project_guid>.client-api.unity3dusercontent.com

. The URLs all begin with

/client_api/v1/

in the request path. None of these client requests require authentication. To get the content of an entry, such as

spaceshooterdata_starfield.bundle

, by path, enter:

https://<project_guid>.client-api.unity3dusercontent.com/client_api/v1/buckets/00000000-0000-0000-0000-000000000000/entry_by_path/content/?path=spaceshooterdata_starfield.bundle

Or to get the content of an entry by Entry ID, enter:

https://<project_guid>.client-api.unity3dusercontent.com/client_api/v1/buckets/00000000-0000-0000-0000-000000000000/entries/00000000-0000-0000-0000-000000000000/content/

Creating a release

Create a release from the current state of your entries:

Create a release


$ ugs ccd releases create -n "notes for the release"

This allows you to use these exact versions of those entries when requesting content, even if you update or remove those entries later.

Note

While you can add a note during the creation of a release by using the

-n

flag, you can only edit it afterward through the CDD Dashboard.

To get more detailed information about a release, use the

releases info

command and provide the ID of the release that you just created:

Get release information


$ ugs ccd releases info 1

To get a list of all releases you generated in this bucket, enter:

List releases in bucket


$ ugs ccd releases list

You can now directly reference the content contained within this release. This ensures you get the exact set of content that CCD uses to generate the release even if you change the entries later in the bucket. To get the content of an entry, such as

spaceshooterdata_starfield.bundle

, by path, enter:

https://<project_guid>.client-api.unity3dusercontent.com/client_api/v1/buckets/00000000-0000-0000-0000-000000000000/releases/00000000-0000-0000-0000-000000000000/entry_by_path/content/?path=spaceshooterdata_starfield.bundle

Or to get the content of an entry by Entry ID, enter:

https://<project_guid>.client-api.unity3dusercontent.com/client_api/v1/buckets/00000000-0000-0000-0000-000000000000/releases/00000000-0000-0000-0000-000000000000/entries/00000000-0000-0000-0000-000000000000/content/

You can also request the content that corresponds to the latest release in the bucket, so the client does not need to change each time CCD generates a new release. To do this, update the request to use the

release_by_badge

route and specify a badge name of

latest

(see Managing badges). For example:

https://<project_guid>.client-api.unity3dusercontent.com/client_api/v1/buckets/00000000-0000-0000-0000-000000000000/release_by_badge/latest/entry_by_path/content/?path=spaceshooterdata_starfield.bundle

Managing badges

After generating a release, you can apply a badge that uniquely identifies the release. A badge can only ever point to a single release within a bucket, but you can move badges between releases. At runtime, you can query content using the badge name rather than a specific release ID, allowing for more flexibility in workflows. For example, you might apply a badge called

qa_latest

to the latest release for your QA team to use, and move that badge to each new release as part of a process (manual or automated). To add a badge named

my_first_badge

to the release you generated in Creating a release, enter, using the

release_num

and

badge_name

as arguments:

Add a badge


$ ugs ccd badges create 1 my_first_badge

To list all the badges you applied in this bucket:

List badges in bucket


$ ugs ccd badges list

The content associated with the release that the badge references is ready for download. You can do this in a similar way to downloading content directly by Entry ID. To get the content for an entry, such as

spaceshooterdata_starfield.bundle

, by path, enter:

https://<project_guid>.client-api.unity3dusercontent.com/client_api/v1/buckets/00000000-0000-0000-0000-000000000000/release_by_badge/my_first_badge/entry_by_path/content/?path=spaceshooterdata_starfield.bundle

Or to get the content of an entry by Entry ID, enter:

https://<project_guid>.client-api.unity3dusercontent.com/client_api/v1/buckets/00000000-0000-0000-0000-000000000000/release_by_badge/my_first_badge/entries/00000000-0000-0000-0000-000000000000/content/

Release promotion and bucket restriction

Releases can be copied from one bucket to another, a process referred to as promotion. This is especially useful when you want to move a release to a different bucket and environment or a more restricted bucket. Create a second bucket and update its permission to be a promotion only bucket. This means the bucket will only accept promoted releases and won't allow direct creation, update, or deletion of entries from service accounts with the user type "user".


$ ugs ccd buckets create example_restricted_bucket$ ugs ccd buckets permissions update example_restricted_bucket --action Write --role User --permission Deny

Finally, promote your release to the target bucket by specifying the release number, the target bucket's name and target environment:


$ ugs ccd releases promote 1 example_bucket_2 production

Deprecated UCD CLI Walkthrough

This section demonstrates how to set up an actual Unity game project with Cloud Content Delivery (CCD) and Addressables, allowing you to easily integrate a pipeline of assets from Unity Editor into CCD.

Note

The Addressables Asset System isn’t required for using CCD.

Using a very simple mobile game called Loady Dungeons, you will learn how to:

Configure and manage assets using Addressable Assets
Generate AssetBundles
Set up a project in the Unity Dashboard
Set up the command-line interface
Create CCD buckets and badges in the Unity Dashboard
Upload AssetBundles

After reading this walkthrough, you will know how to effectively serve content to your users, and how to use the Addressable Asset system in Unity with CCD.

Note

This walkthrough uses Unity 2021.3.18f1.

Download the project

The first thing you need to do to follow along with this walkthrough is to download the latest version of our sample game from GitHub, Loady Dungeons.

Test the project

Open Unity Editor.
Open the Loady Dungeons project.
Open the MainMenu scene.
Click on the Game tab.
In the Aspect dropdown, click +.
1. Create a new aspect of Type "Aspect Ratio", with a Width and Height of 9 and 16, respectively. This makes the game preview look more like it's running on a phone.
2. Click OK.
3. Deselect Low Resolution Aspect Ratios.
Press the Editor's Play button to try the game.

Note

Playing the game in its initial state means you can't load the first level. Progressing through this walkthrough fixes this limitation by associating the required assets to use CCD with Addressables.

Install the Addressable Assets package

In order to mark assets as addressable, you need to install the Addressables package directly in Unity Editor.

Note

This project already has an Addressables package pre-installed, but if you are following along with a custom project or want to upgrade to a newer verified version, install the Addressables package through the Package Manager.

Select Window > Package Manager.
Search for the latest version of Addressables verified for the version of Unity Editor you’re using. This example uses version 1.16.19.
Select the version you need, then Install.

Configure game assets as addressable

Addressable assets provide an easy way to handle asset management overload by loading assets by address. Now that you have the Addressables package installed, it’s time to mark your game assets as addressable.

Open the Scenes folder in the Project window.
Select the following assets:

Level_00
Level_01
Level_02
Level_03

In the Inspector window, select Addressable for each.
Open the Addressables Groups window from Window > Asset Management > Addressables > Groups.
Create the following new groups using Create > Group > Packed Assets:

Level 00
Level 01
Level 02
Level 03
Hats

Drag the Scenes assets from the default group into their corresponding groups. For example, drag the Level_01 scene from the default group into the new Level 01 group you created.
Drag the entire contents from the Hats folder (not the folder itself) in the Project window (Prefabs > Hats) into the Hats group.
Select each of the assets from the Addressables Groups window, and rename their lengthy Addressable field to something simpler in the Inspector window. You can select all the assets, right-click > Simplify Addressable Names to automatically rename them. For the scene asset Level_00, rename its Addressable field from Assets/Scenes/Level_00.unity to Level_00.

Rename scene asset Level_00’s Addressable field to Level_00
Rename scene asset Level_01’s Addressable field to Level_01
Rename scene asset Level_02’s Addressable field to Level_02
Rename scene asset Level_03’s Addressable field to Level_03
Rename prefab asset Hat00’s Addressable field to Hat00
Rename prefab asset Hat01’s Addressable field to Hat01
Rename prefab asset Hat02’s Addressable field to Hat02
Rename prefab asset Hat03’s Addressable field to Hat03

Configure profiles and building AssetBundles

At this stage, create a new Addressables profile to save all the associated settings related to development of the game to this development profile:
Click Window > Asset Management > Addressables > Groups.
Select Profile > Manage Profiles from the dropdown.
In the resulting Addressables Profiles window, select Create > Profile.
A profile named New Profile appears. Right-click it and select Rename Profile. Name it “Development Profile”.
Right-click Development Profile > Set Active. This sets the Development Profile as the current profile in use.
Now, build your AssetBundle, which is an archive file that contains non-code assets for your game. This is so that the Editor’s play mode uses our AssetBundles instead of local assets.
Click Window > Asset Management > Addressables > Groups.
Select Build > New Build > Default Build Script from the dropdown.
Select Play Mode Script > Use Existing Build from the dropdown.

Get started with CCD

Now you are ready to hook this game into the Cloud Content Delivery (CCD) service, ultimately leveraging Addressables and AssetBundles. The benefit of CCD is that it is a managed cloud service that hosts and delivers content to your application’s users worldwide without having to reinstall a new version of the application.To get started with CCD:

Go to the Unity Dashboard.
Sign in using your Unity ID.
From the projects dropdown, click Create Project.
Name it “Loady Dungeons Workshop”.
Click Create project.
Open the Loady Dungeons Workshop project and take note of the Project ID.
Select the Environments tab.
If you don't already have a development environment, create one.
From the Dashboard landing page, locate and select Cloud Content Delivery.

The Command-line interface (optional)

If you prefer to use the optional command-line interface (CLI) to manage your project:

Download the CLI for your operating system.
Make sure to include the CLI’s folder in your computer’s Environment Variables.
Open the command line and navigate to your project’s folder.
Type the following command to make sure the CLI is successfully configured:
```
ucd help
```

See CCD Command-line interface (CLI).

Buckets

At this point, it is time to create buckets to assist in the different stages of creation for this project.

Create buckets

From the CCD landing page, click Buckets on the left.
Select Loady Dungeons Workshop from the projects dropdown (if not already selected).
Click Create Bucket.
Name the bucket “Loady Dungeons Sample”.
Give the bucket an optional description.
Choose whether this bucket is:

Open to all: Anyone can modify content in this bucket.
Promotion only: Owners and managers can modify content through promotion. No one can upload to or delete content from this bucket.

To restrict read access to this bucket, select Enable Bucket Privacy. Private buckets only allow users with an access token to read the content.\
Note
You cannot change the bucket privacy settings after you create the bucket.
Select Next.
Make sure both production and development environments are checked.
Select Create.

The Loady Dungeons Sample bucket should now appear on the Cloud Content Delivery Buckets page in the Unity Dashboard, for both development and production environments. You can switch between environments using the environments dropdown at the top of the page. Take note of the buckets’ Bucket ID in both environments because you need to use them later in your remote load path.

Generate AssetBundles and upload content manually

Generate AssetBundles

An AssetBundle is an archive file that contains platform-specific non-code assets that Unity can load at run time.To generate AssetBundles:

In your Unity Editor project, click Window > Asset Management > Addressables > Groups.
In the Profile dropdown, make sure that Development Profile is selected. If it isn’t, select it now.
In the Profile dropdown, select Manage Profiles.
With Development Profile selected, set the following:

RemoteBuildPath:
```
AssetBundles/[BuildTarget]
```
, where
```
[BuildTarget]
```
is the default subfolder.

RemoteLoadPath:

https://PROJECT_ID.client-api.unity3dusercontent.com/client_api/v1/buckets/BUCKET_ID/release_by_badge/latest/entry_by_path/content/?path=

Replace
```
PROJECT_ID
```
with the ID of your project. If you didn’t take note of your Project ID earlier, find it by clicking on your user name in the corner of the Unity Dashboard, then Account > Project Management > Loady Dungeons Workshop.
Replace
```
BUCKET_ID
```
in the path with the ID of the bucket you want to use, the Loady Dungeons Sample bucket created in your development environment in this example. If you didn’t take note of its
```
BUCKET_ID
```
earlier, find it in your list of buckets in the Unity Dashboard.
The
```
latest
```
in the path refers to the badge called Latest, an automatically generated badge assigned to the most recent release.

Return to the Addressables Groups window.
Select Hats.
In the Inspector panel, set:
Build Path: RemoteBuildPath
Load Path: RemoteLoadPath
Repeat for Level 00, Level 01, Level 02, and Level 03

This sets the build path and load paths for these four sets of assets to the paths we specified for the Development Profile.

Still in the Groups window, click on the Build dropdown, then select New Build > Default Build Script. This saves the AssetBundles at the RemoteBuildPath location.
To use the build we just made as the basis for a playtest, click on the Play Mode Script > Use Existing Build.
Click the Play button in Unity Editor to test the game.
- Press Start in the game. Notice how the game is now stuck.

Upload the content

At this point, we want to upload this content into the Development bucket we set up in CCD earlier.

Select the Loady Dungeons Sample bucket in your development environment from the CCD section of the Unity Dashboard.
Select Upload using the dashboard if the bucket is empty, or Upload Content if the bucket already contains entries.
Drag and drop, or select the Browse button to upload content from the folder where you built your AssetBundles to your CCD Development bucket. Your files are in the folder specified as the RemoteBuildPath from earlier.
Select Upload 5 Files (four levels and Hats).
After the upload process, select Refresh Page to update the status of the bucket's information. The entries appear as Unreleased Changes. This means that the entries are present in the bucket but have not yet been wrapped up in a Release.
To make a release, select Create Release. This takes the AssetBundles you uploaded to the Loady Dungeons Sample bucket in your development environment and binds them into a Release. Follow the onscreen prompts to finish the process.

Notice that CCD automatically applies the automatically created

latest

badge to this release, marking it as the newest release created in this bucket.

Note

You can also upload content using the CLI.

Generate AssetBundles and upload content with CCD Management package

The CCD Management package with Addressables 1.19.15+ facilitates building, uploading and releasing Addressable content.

Note

You need to upgrade the Addressables versions and install the CCD Management package through the Package Manager.

Select Window > Package Manager.
Search for Addressables, select the version 1.19.15+, then Install.
Search for CCD Management, select the version 2.0.1+, then Install.

Generate AssetBundles

In your Unity Editor project, click Window > Asset Management > Addressables > Groups.
In the Profile dropdown, make sure that Development Profile is selected.
In the Profile dropdown, select Manage Profiles.
In the Profiles window, select Development Profile, then change the Remote dropdown to use Cloud Content Delivery.
Note
At this point if you don't already have the CCD Management package installed, Unity Editor prompts you to add it. Click on the Install CCD Management SDK Package button to install it.
In the next list of options, choose the Loady Dungeons Sample bucket created earlier.
In the subsequent list, choose the Latest badge.
Return to the Addressables Groups window.
Select Hats.
In the Inspector panel, under Content Packaging & Loading:
Set Build and Load Paths: Remote
Repeat for Level 00, Level 01, Level 02, and Level 03

This sets the build path and load paths for these four sets of assets to the paths pairs specified for the Development Profile. See Profile for more information on path pairs.

In the Groups window, click on the Build dropdown, then select New Build > Default Build Script. This saves the AssetBundles at the RemoteBuildPath location.
To use the build we made as the basis for a playtest, click on the Play Mode Script > Use Existing Build.
Select the Play button in Unity Editor to test the game.
Select Start in the game. Notice how the game is now stuck.

Upload the content

To generate, upload, and release this content into the Loady Dungeons Sample bucket we set up in CCD earlier:

In your Unity Editor project, click Window > Asset Management > Addressables > Groups.
Select Build & Release.

The CCD Management package uses the default build script behavior to generate the Addressable bundles. Then, the management package uploads all groups associated with the path pair that is connected to the Loady Dungeons Sample bucket and latest badge that we set up earlier to those remote targets. Finally, the management package creates a release for those remote targets and updates their badge to

latest

Promote the release

After you’ve uploaded your assets to the Loady Dungeons Sample bucket in your development environment and you tie those assets into a release, you can put these latest changes out for public consumption. That’s why we also created the bucket in your production environment. The buckets in your production environment contain releases ready for your players. This means moving the release from the bucket in your development environment to the one in your production environment by a process called promotion.To promote the release from the bucket in your development environment to the one in your production environment:

If not already there, in the Unity Dashboard, go to the Loady Dungeons Workshop CCD project, make sure the development environment is selected in the environments dropdown, and select the Loady Dungeons Sample bucket.
Select Promote Release.
In the Target Environment dropdown, select production.
In the Target Bucket dropdown, select Loady Dungeons Sample.
Add optional release notes.
Select Next and follow the onscreen prompts.
Select Promote Release.

Again, notice that CCD automatically applies the automatically created

latest

badge to this release, marking it as the newest release created in this bucket.Before you test the game, you need to modify the profile variables to point to the correct bucket. There are two ways to do this:

You can have a different player build per environment. Your Development build would have debug symbols and the
```
bucket_id
```
variable set to your bucket from the development environment, and your Production build would have debug symbols disabled and the
```
bucket_id
```
variable set to your bucket from the production environment, but they would use the same content.
Use static properties in a profile variable or TransformInternalId to dynamically change the bucket the catalog is reaching out to at runtime. For more about the static profile variables and transforming internal IDs in Addressables, see Transforming resource URLs.

Test the game:

In Unity Editor, press the Editor's Play button.
Press Start in-game.
Press Play in-game. You can now play the game within Unity Editor.

You’ve now successfully moved the release and all its assets from Development to Production, ready to deploy to your users.

Using Addressables with private buckets

To read the data from private buckets, you need to have a valid Bucket Access Token.As of Addressables 1.19.4, you can use the WebRequestOverride feature to add Bucket Access Token as a header to the request, which the following example demonstrates.


void Start(){	textComponent = GetComponent<Text>();	Addressables.WebRequestOverride = webRequest =>	{		webRequest.SetRequestHeader("Authorization", "Basic "+token);		//  Debug.Log($"Fetching: {webRequest.url}");	};	Addressables.LoadAssetAsync<TextAsset>("Assets/one.txt").Completed += handle =>	{		textComponent.text = handle.Result.text;		// Debug.Log($"Text is now: {handle.Result.text}");	};}

In this example,

token

is the base64 encoded Bucket Access Token value.

Using CCD via the UGS CLI

Authentication

Logging In Using the CLI

Using Environment Variables for Authentication

For Unix-based systems (Linux, macOS)

For Windows

Configuration

Set Project ID

Set Environment Name

Set Bucket Name

Creating a bucket

Creating entries in the bucket

Creating a release

Create a release

Get release information

List releases in bucket

Managing badges

Add a badge

List badges in bucket

Release promotion and bucket restriction

Deprecated UCD CLI Walkthrough

See Deprecated UCD CLI Walkthrough

Download the project

Test the project

Install the Addressable Assets package

Configure game assets as addressable

Configure profiles and building AssetBundles

Get started with CCD

The Command-line interface (optional)

Buckets

Create buckets

Generate AssetBundles and upload content manually

Generate AssetBundles

Upload the content

Generate AssetBundles and upload content with CCD Management package

Generate AssetBundles

Upload the content

Promote the release

Using Addressables with private buckets