UGS CLI for CCD#

The command-line interface (CLI) is an efficient way to interact with Cloud Content Delivery (CCD). With the CLI, you can use the command line to control every aspect of your project, from file management to release pipeline organization.

The Unity Cloud Dashboard provides a lot of functionality, but you need to use the CLI for certain actions, such as to copy files to your bucket or synchronize entire folders.

For more information about the UGS CLI, refer to the Unity Gaming Services CLI documentation.

Installation#

For information on how to install the CLI, refer to the Installation guide.

Migration information#

With the integration of CCD into the UGS CLI ecosystem, there are the improvements available that are designed to enhance your experience and streamline your workflows.

Unified with UGS tooling#

Seamless integration#

CCD is now a cohesive part of the UGS CLI ecosystem. This integration means that you no longer need to install and maintain a separate tool for CCD functionalities. Install the UGS CLI once, and you're set to manage multiple UGS services efficiently including CCD.

Authentication updates#

Transition to service accounts#

The CLI now uses service accounts for authentication to provide more secure, versatile and streamlined user verification.

For more information, refer to Authentication.

Enhanced user experience#

Unified command interface#

CCD has standardized the CLI's commands, inputs, and outputs to align with other UGS services and provide two output formats (JSON and plain text). The response are more detailed and aligned with the ccd rest api.

For more information, refer to the available outputs.

Intuitive command arguments#

We now have more intuitive command arguments: Instead of asking for UUID arguments such as environment id, bucket id, badge id, release id, users should now use human friendly arguments such as environment names, bucket names, badge names, and release number.

Get started#

Prerequisites#

• If you already have a project, go to the next section. Otherwise, if you are using Unity services for the first time:

  1. Create a Unity ID account (if you don’t already have one).
  2. Log into the Unity Dashboard.
  3. Click the Projects dropdown, then Create project. In the Create project window, fill in the required details.

• To download and install the CLI, follow this guide.

• To set up CCD in the Unity Cloud Dashboard, select Products > Cloud Content Delivery > Launch. You can then fill in your details and access CCD.

Set up CCD for CLI#

1. In the Unity Cloud Dashboard, select Administration > Service accounts.
2. Select the New button.
3. Enter a name and description, and select Create.
4. Select Add key, and save the Key ID and Secret key. Note: For more detailed instructions, refer to the Service Account Authentication Documentation.
5. Select Manage organization roles > LiveOps > Cloud Content Delivery API Public Editor to grant read and write access to public endpoints of the CCD Management API.
6. Select Manage project roles, select your project, then select Next > Admin > Unity Environments Viewer to grant read access to all environments in a project.
7. Run the CLI on the machine from which you upload content.
8. Use the $ ugs login command to log into the CLI using your service account.

CCD is now ready for you to use.

CLI usage#

The basic form of a UGS CCD command in the CLI is as follows:

$ ugs ccd [command] [subcommand] [parameters]

To see the version of the CLI you are currently using, add the --version flag:

$ ugs --version

You can add the following global flags after any command:

Authentication#

Authenticates with CCD.

Usage: ugs login

Available commands:

• login: Save Service Account Key ID and Secret Key. You can save the Key ID and Secret Key with this command or system environment variables: UGS_CLI_SERVICE_KEY_ID and UGS_CLI_SERVICE_SECRET_KEY. Visit https://services.docs.unity.com/docs/service-account-auth to create or manage service account.
• logout: Clear stored Service Account Key ID and Secret Key from local configuration.
• status: Checks if the current user has any Service Account Key ID and Secret Key stored locally.

For detailed instructions on logging in, visit the UGS CLI Login Documentation.

Output#

The CLI offers two output formats to address diverse user needs for data representation: the default YAML and an optional JSON format. To obtain outputs in JSON, append -j or --json to your command. This feature simplifies data integration and processing to ensure a more efficient workflow. For example, you can do the following:

$ ugs ccd [command] --json

Configuration#

Environment setup for the UGS CLI is simple. You can use environment variables, CLI commands, or sometimes options within commands for configuration. You can use the following information to get started.

Use environment variables#

Environment variables allow you to configure the CLI without having to enter details every time you run a command. Open your terminal and run these commands to set your environment variables:

For Unix-based Systems (Linux, macOS):#

export UGS_CLI_SERVICE_KEY_ID="your_key_id"
export UGS_CLI_SERVICE_SECRET_KEY="your_secret_key"
export UGS_CLI_ENVIRONMENT_NAME="your_environment_name"
export UGS_CLI_ENVIRONMENT_ID="your_environment_id"
export UGS_CLI_BUCKET_NAME="your_bucket_name"
export UGS_CLI_PROJECT_ID="your_project_id"

For Windows#

For Windows users, open Command Prompt and enter:
set UGS_CLI_SERVICE_KEY_ID=your_key_id
set UGS_CLI_SERVICE_SECRET_KEY=your_secret_key
set UGS_CLI_ENVIRONMENT_NAME=your_environment_name
set UGS_CLI_ENVIRONMENT_ID=your_environment_id
set UGS_CLI_BUCKET_NAME=your_bucket_name
set UGS_CLI_PROJECT_ID=your_project_id

Use CLI Commands for configuration#

The CLI also supports direct configuration through commands. Here are some examples to set the active environment, project-id and bucket-name:

ugs env use <environment-name>
ugs config set project-id <project-id>
ugs config set bucket-name <bucket-name>

Use Option with a command:#

The CLI supports specifying a bucket for any ccd command using the option -b.

ugs ccd entries list -b <bucket-name>

buckets#

Manages buckets for a project.

Usage: ugs ccd buckets [command]

Available commands:

• create <bucket-name> [-d, --description <description>] [-p, --private]: Create bucket for a project.
• delete <bucket-name>: Delete bucket.
• info <bucket-name>: Get bucket information.
• list: List buckets in the current project.
• permissions update <bucket-name>: Set permissions for a bucket.

entries#

Manages entries for the current bucket.

Usage: ugs ccd entries [command]

Available commands:

• copy <local-path> <remote-path>: Create entry for current bucket from a local file.
• delete <entry-path>: Delete entry from the current bucket.
• download <entry-path>: Download entry content from current bucket.
• info <entry-path>: Get entry info from current bucket.
• list: List entries for current bucket.
• sync <local-dir-path>: Sync entries from local directory for current bucket.
• update <entry-path>: Update entry for current bucket.

releases#

Manages the releases for the current bucket.

Usage: ugs ccd releases [command]

Available commands:

• create: Create release from latest version of current bucket.
• info <release-num>: Get release info for specific release.
• list: List releases for current bucket.
• promote <release-num> <target-bucket-name> <target-environment-name>: Promote specified release to another bucket.
• promotions status <promotion-id>: Get the status of a promotion.
• update <release-num>: Update an existing release.

Bucket and entry names are case-sensitive.

badges#

Manages badges for a release.

Usage: ugs ccd badges [command]

Available commands:

• create <release-num> <badge-name>: Create a badge for a release.
• delete <badge-name>: Delete a badge.
• list: List badges in the current project.

CLI examples#

Here are some examples of how you might use the UGS CLI for CCD:

• To create a bucket:
  $ ugs ccd buckets create "MyBucket" --description "This is my bucket." --private
• To set the current bucket as the active bucket:
  $ ugs config set bucket "MyBucket"
• To synchronize a local folder with the current bucket:
  $ ugs ccd entries sync ./myLocalDir
• To list all buckets for a project:
  $ ugs ccd buckets list --sort-by name --sort-order desc
• To view a list of all entries in the current bucket:
  $ ugs ccd entries list
• To delete a bucket:
  $ ugs ccd buckets delete "MyBucket"

These examples should give you a good starting point for using CCD with the UGS CLI. Remember that each command has additional flags and options which can be viewed by using the --help flag with the command.

For a sequential example of how to use the command-line interface, see Using CCD via the CLI.

Deprecated UCD CLI#