Oculus Platform Command Line Utility

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

Compared to using the Oculus Dashboard, the Oculus Platform Command Line Utility uploads builds faster because it analyzes your build and only uploads the parts that have changed since your last upload.

Install the Command Line Utility

  1. Go to https://dashboard.oculus.com/tools/cli
  2. Under Download, click the correct download for your system: Mac OS X OR Windows 32-bit and 64-bit
  3. Copy the command line utility to the directory of your choice.
  4. 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 App ID, Secret and Build ID

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

Find the App ID and App Secret

  • Sign in to the Oculus developer portal 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:

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:


Available Commands

The utility supports both Rift and mobile uploads and downloads. Following is a list of commands for the tool:

TaskCommand
Upload a Rift buildupload-rift-build
Download a Rift builddownload-rift-build
Clone an existing Rift buildclone-rift-build
Add an entitlement check to a Rift executable (.exe).add-entitlement-check
Upload a mobile buildupload-mobile-build
Download a mobile builddownload-mobile-build
Move build to a different release channelset-release-channel-build
Get the version of the Oculus utilityversion
Update the Oculus utilityself-update

For the full syntax and parameter descriptions, see the Oculus Platform Command Line Utility page.

To toggle between the available reference information, click the headings such as upload-rift-build, upload-mobile-build, download-rift-build, and download-mobile-build

Rift Examples

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.

Note: See Oculus Platform Command Line Utility for the full syntax and parameters list reference.

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

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.

Mobile 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

Note: See Oculus Platform Command Line Utility for the full syntax and parameters list reference.

Simple Mobile Upload Example

To upload Rabbit Hole to the Alpha release channel, 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

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

If you split version 2 of Rabbit Hole into separate APK and APK expansion files (see APK Expansion File Requirements) we 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

If you have a mobile build with required assets, include a path to the assets and a config file that designates them as required or as IAP.

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 

Mobile Download Example

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

  1. Enter:
    ovr-platform-util download-mobile-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.

Set Release Channel Example (Rift or Mobile)

Shows the command 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