Oculus Platform Command Line Utility Reference

The Oculus Platform Command Line Utility lets you upload builds to your release channels much faster than using the Oculus dashboard web interface, and it enables larger upload packages. It also allows you to incorporate automated uploads into your existing build system.

The Oculus Platform CLI uploads builds faster because it analyzes your build and only uploads the parts that have changed since your last upload.

This topic contains the following sections:

• Download and Install the Utility
• Obtain Credentials to Use the Utility
• Command Quick Reference
• Get Help with the Utility
• Upload a Rift Build
• Download a Rift Build
• Clone a Rift Build
• Add the Entitlement Check to an Executable
• Redistributable ID Reference
• Upload a Quest Build
• Download a Quest Build
• Upload a Go Build
• Download a Go Build
• Set Release Channel
• Manage Add-ons

Download and Install the Utility

1. Select the appropriate download for your system:

   • Windows 32-bit and 64-bit
   • Mac OS X
2. Copy the command line utility to the directory of your choice.

3. For Mac, you will need to change to access permissions of the tool for it to execute:

   • Change directories (cd) to the location of the file.
   • At the command prompt, type: chmod +x ./ovr-platform-util.
   • Run the tool by typing ./ovr-platform-util and a command.

Obtain Credentials to Use the Utility

You may need the App ID, App Secret or Build ID to complete some of the commands.

Find the App ID and App Token

• Sign in to the Oculus developer portal with an admin account for your organization and navigate to https://dashboard.oculus.com.
• Find the app in the list of apps for your organization
• Navigate to the Getting Started API page to find the App ID and App Secret. The following image shows an example:

Use the app secret wherever you are prompted for the access token. You can also obtain a user token that can be used with some commands with the get-access-token command)

Note: You must use an admin account to view the app secret. Visit the Members page under Settings for your organization to verify the admin accounts.

Obtain Build ID

You will need a Build ID to download an existing build. You can obtain the build ID two different ways:

• Obtain the Build ID from the output when you successfully upload an app build with the command-line tool.

OR

• Obtain the Build ID on the developer dashboard by navigating to Manage Build page.
• Click the ellipses for a channel, and View Channel Builds
• The URL of this page displays the App ID and the Build ID. The following image shows an example:

Command Quick Reference

The utility supports Rift, Quest and Go uploads and downloads. In addition, there are commands to manage the tool and get help.

Following is a list of commands for the tool:

Manage the Utility

Manage Rift Builds

Manage Quest Builds

Manage Go Builds

Get Help with the Utility

Use the following command to get a list of commands and other help for the utility.

$ ovr-platform-util.exe help

You will be promped for the account access credentials and when successfully entered, returns the token for use with commands that require an access token.

Check the Tool Version

You can check what version of the tool you have by using the version command

$ ovr-platform-util version

This will generate ouput like the following:

Oculus Platform Command Line Utility - 1.54.0.000001 (Built on Tue Jul 28 2020)

Configure the Tool to Self Update

You can configure the tool to self update using the self-update command.

$ ovr-platform-util self-update

This will result in output like the following:

Checking for the latest version
Already running the latest version 1.54.0.000001

Get the App Access Token

Use the following command to get a user access token for the app.

$ ovr-platform-util.exe get-access-token

You will be promped for the account access credentials and when successfully entered, returns the token for use with commands that accept a user token.

Upload a Rift Build

Following is the syntax and options for uploading a Rift app to the Oculus store.

Syntax

$ ovr-platform-util upload-rift-build -a <AppID> -s <Token> -d <BuildPath> -l <LaunchFile>
-c <ReleaseChannel> -v <Number> -n <Text> [-p <Arguments>] [-L <2DLaunchFile>] [-P <2DArguments>]
[-r <RedistID>[,]...] [-f {true|false}] [-w {7SP1|8.1|10}] [--add-entitlement-check]

Options

This upload example uses the fictitious app “Rabbit Hole” and assumes the following sample parameters:

• App ID: 10001234
• App Secret Token: 1234abcd.
• Build Directory: C:\Rabbit Hole
• Launch File: C:\Rabbit Hole\bin\badrabbits.exe
• New version: 1.1
• Release Note: Fixes the rabbit spawn bug.

Simple Rift Upload Example

To upload version 1.1 of Rabbit Hole to the RC release channel, enter:

$ ovr-platform-util upload-rift-build --app-id 10001234 --app-secret 1234abcd
-d "C:\Rabbit Hole" -l "bin\badrabbits.exe"
-n "Fixes the rabbit spawn bug." -v 1.1 -c rc

Upload with Redistributables Example

If the app requires .NET Framework 3.5 and Visual C++ 2013 x86 redistributable files, enter:

$ ovr-platform-util upload-rift-build --app-id 10001234 --app-secret 1234abcd -d "C:\Rabbit Hole" -l "bin\badrabbits.exe" -n "Fixes the rabbit spawn bug."
-v 1.1 -c rc -r "606493776156948, 910524935693407"

2D Mode with Firewall Exception Example

If the app requires a Windows Firewall exception, Windows 10 as a minimum version, and has a 2D mode executable file and argument string of badrabbits2d.exe -force2dfix, enter:

$ ovr-platform-util upload-rift-build --app-id 10001234 --app-secret 1234abcd
-d "C:\Rabbit Hole" -l "bin\badrabbits.exe"
-n "Fixes the rabbit spawn bug." -v 1.1  -c rc -L badrabbits2d.exe
-P "-force2dfix" -f -w "10"

Multi-line Release Note Example

If you have a multi-line release note, enter:

$ ovr-platform-util upload-rift-build --app-id 10001234 --app-secret 1234abcd -d "C:\Rabbit Hole" -l "bin\badrabbits.exe"
-n  "Carrots now available as in-app purchases.\nBlue rabbits no longer \"glitch\" and get stuck in terrain.\nSpawn sound spatialization adjusted for realism."
-v 1.1 -c rc

Download a Rift Build

Following is the syntax and options for downloading a Rift app to the Oculus store.

Syntax

$ ovr-platform-util download-rift-build -b <BuildID> -d <Directory>

Options

Rift Download Example

To download the app build with build ID 3141592653589793 to “C:\Pie Thrower”:

1. Enter:

   $ ovr-platform-util download-rift-build -b 3141592653589793 -d "C:\Pie Thrower"
   

2. Provide the email address and password of an Oculus user authorized to download the app.
3. The build should download to the specified directory.

Add the Entitlement Check to an Executable

Add Oculus Platform Entitlement Check to specified executables.

Syntax

$ ovr-platform-util add-entitlement-check -b <BuildID> -d <Directory>

Options

Clone a Rift Build

This command will clone an existing Rift build to create a new build. You can optionally modify any of the metadata for the build. The new build will be placed in the release channel specified by the destination_channel parameter. The build to be cloned can either be picked from another channel by using the source_channel or specified explicitly by using the build_id parameter.

Syntax

ovr-platform-util clone-rift-build --app_id <AppID> --app_secret <Secret> --source_channel <Channel> --destination_channel <Channel> [OPTIONS]

Options

Clone Rift Build Example

ovr-platform-util clone-rift-build --app_id 10001234 --app_secret 1234abdc --source_channel alpha --destination_channel beta --launch_params "server=beta"

Redistributable ID Reference

Following is a list of redistributable packages and their associated IDs.

Upload Quest Build

Following is the syntax and options for uploading a Quest app to the Oculus store.

Syntax

ovr-platform-util upload-quest-build --app_id <ID> --app_secret <Token> --apk <path/to/Your.apk> --obb <path/to/Your.obb> --assets-dir <path/to/DLCs/dir> --channel <ReleaseChannel> --notes <ReleaseNotes>

Options

Examples

This upload example uses the fictitious app “Rabbit Hole”.

• App ID: 10001234
• App Secret Token: 1234abcd
• APK Path: C:\Rabbithole.apk
• APK Package name: com.oculus.rabbits

For Quest enter:

$ ovr-platform-util upload-quest-build --app-id 10001234 --app_secret 1234abcd --apk C:\RabbitHole.apk --channel alpha --notes "Fixes the rabbit spawn bug."

Download Quest Build

Following is the syntax and options for downloading a Quest app from the Oculus store.

Syntax

ovr-platform-util download-quest-build -b <BuildID> -d <Directory>

Options

Download Example

The following example shows how to download the app build with build ID 3141592653589793 to “C:\Pie Thrower”.

For Quest enter:

$ ovr-platform-util download-quest-build -b 3141592653589793 -d "C:\Pie Thrower"

Upload Go Build

Following is the syntax and options for uploading a Go app to the Oculus store.

Syntax

ovr-platform-util upload-mobile-build --app_id <ID> --app_secret <Token> --apk <path/to/Your.apk> --obb <path/to/Your.obb> --assets-dir <path/to/DLCs/dir> --channel <ReleaseChannel> --notes <ReleaseNotes>

Options

Simple Upload Example

The following examples show how to upload Rabbit Hole to the Alpha release channel. This upload example uses the fictitious app “Rabbit Hole”.

• App ID: 10001234
• App Secret Token: 1234abcd
• APK Path: C:\Rabbithole.apk
• APK Package name: com.oculus.rabbits

For Go enter:

$ ovr-platform-util upload-mobile-build --app-id 10001234 --app_secret 1234abcd --apk C:\RabbitHole.apk --channel alpha --notes "Fixes the rabbit spawn bug."

Multi-line Release Note Example (Go)

For Go, if you have a multi-line release note, enter:

$ ovr-platform-util upload-mobile-build --app-id 10001234 --app-secret 1234abcd
--apk C:\RabbitHole.apk --channel alpha
--notes "Carrots now available as in-app purchases.\nBlue rabbits no longer \"glitch\" and get stuck in terrain.\nSpawn sound spatialization adjusted for realism."

Expansion File Example (Go)

If you split version 2 of Rabbit Hole into separate APK and APK expansion files (see APK Expansion File Requirements) you specify the full path to the expansion file with --obb. Enter:

$ ovr-platform-util upload-mobile-build --app-id 10001234 --app-secret 1234abcd
--apk C:\RabbitHole.apk --obb C:\main.2.com.oculus.rabbits.obb
--channel alpha --notes "Split data and code to provide smaller and faster patch updates."

Required Assets Example (Go)

If you have a build with required assets, include a path to the assets and a config file that designates them as required or as IAP. Following is an example for Go:

$ ovr-platform-util upload-mobile-build --app-id 10001234 --app-secret 1234abcd
--apk C:\RabbitHole.apk --assets_dir ~\path\to\assets\ --asset_files_config '{"Asset1.obb": {"required": true}, "Asset2.obb": {"sku": "IAP_SKU"}}'
--channel alpha

Download Go Build

Syntax

ovr-platform-util download-mobile-build -b <BuildID> -d <Directory>

Options

Download Example

The following examples show how to download the app build with build ID 3141592653589793 to “C:\Pie Thrower”.

For Go, enter:

$ ovr-platform-util download-mobile-build -b 3141592653589793 -d "C:\Pie Thrower"

1. Provide the email address and password of an Oculus user authorized to download the app.
2. The build should download to the specified directory.

Set a Release Channel

Syntax

ovr-platform-util set-release-channel-build --app_id <AppID> --app_secret <Secret> --source_channel <Channel> --destination_channel <Channel>

Options

Release Channel Example The following example shows how to set the release channel for a build from Beta to RC

$ ovr-platform-util set-release-channel-build --app-id 10001234 --app-secret 1234abcd  --source-channel beta --destination-channel rc

Manage Add-ons

You can manage add-ons with the utility and upload-add-on command. For more information, see Add-ons.

Syntax

$ ovr-platform-util.exe upload-add-on --app_id <AppID> --app_secret <Secret> --token <Token> --file <file> --sku <sku> --min-version-code <min-version>

Options