The Oculus Platform Utility is a command-line tool that enables 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 Utility 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:
Select the appropriate download for your system:
For Mac, you will need to change the access permissions of the utility for it to execute:
cd
) to the location of the filechmod +x ./ovr-platform-util
./ovr-platform-util
and a commandYou will need the App ID, App Secret or User Token, and Build ID to complete some of the commands. Note that:
get-access-token
command.Find the App ID, App Secret and/or User Token
Navigate to the Getting Started API page to find the App ID and generate an App Secret and User Token. Note that 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. The following image shows an example of the API page:
Obtain Build ID
You will need a Build ID to download an existing build. You can find this in a couple of different ways:
Oculus offers a UI integration of the Oculus Platform Utility for Unreal Engine and Unity.
For Unreal Engine, see Upload Apps to the Oculus Store with the Oculus Platform Tool.
For Unity, in the Unity Editor, go to Oculus > Tools, and choose the Oculus Platform Tool. Fill out the required information and click the Upload button.
The utility supports Rift and Quest uploads and downloads. In addition, there are commands to manage the utility and get help.
Following is a list of commands for the utility:
Task | Command |
---|---|
Get help with the utility | help |
Get the version of the Oculus platform utility | version |
Update the Oculus platform utility | self-update |
Get the app access token | get-access-token |
Task | Command |
---|---|
Upload a Rift build | upload-rift-build |
Download a Rift build | download-rift-build |
Clone an existing Rift build | clone-rift-build |
Move build to a different release channel | set-release-channel-build |
Upload an add-on files such as DLC or IAP | upload-add-on |
The following commands help you manage apps that target Quest devices.
Task | Command |
---|---|
Upload a Quest build | upload-quest-build |
Download a Quest build | download-quest-build |
Move build to a different release channel | set-release-channel-build |
Upload an add-on files such as DLC or IAP | upload-add-on |
Use the following command to get a list of commands and other help for the utility.
$ ovr-platform-util.exe help
You can check what version of the utility you have by using the version
command
$ ovr-platform-util version
This will generate output like the following:
Oculus Platform Command Line Utility - 1.54.0.000001 (Built on Tue Jul 28 2020)
You can configure the utility 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
Use the following command to get a user access token for the app. You can use this token in place of the app secret for many commands.
$ ovr-platform-util.exe get-access-token
You will be prompted for the account access credentials and when successfully entered, returns the token for use with commands that require an access token.
Following is the syntax and parameters for uploading a Rift app to the Oculus store.
$ ovr-platform-util upload-rift-build -a <AppID> --app_secret <App-Secret> --token <User-Token> -d <BuildPath> -l <LaunchFile> -c <ReleaseChannel> -v <Number> -n <Text> --assets-dir <assset-dir> --asset-files-config <config.json> --language-packs-dir [-p <Arguments>] [-L <2DLaunchFile>] [-P <2DArguments>] [-r <RedistID>[,]...] [-f {true|false}] [--help {true|false}] [--clean {true|false}] [--add-entitlement-check {true|false}] [--help {true|false}] [--inherit-assets {true|false}]
Syntax | Description |
---|---|
-d <buildPath> --build_dir <buildPath> | Required. Specifies the full path to the directory containing your build files. |
-a <ID> -app_id <ID> | Required. Specifies the ID of your app. Obtained from the API tab of your app in the Oculus Dashboard. |
-s <app-secret> --app_secret <app-secret> | Required. Specifies the app secret. Obtained from the API tab of your app in the Oculus developer dashboard. |
-t <token> --token <token> | Either app secret or user token required. A user token obtained by the get-access-token command or from the API tab of your app in the Oculus developer dashboard. |
-c <releaseChannel> --channel <ReleaseChannel> | Required. Specifies the release channel for uploading the build. Release channel names are not case-sensitive. |
-v <version-number> --version <version-number> | Required. Specifies the version number shown to users. |
-l <launchFile> --launch_file <launchFile> | Required. Specifies the relative path from the the build directory to the executable that launches your app. |
-n <text> --notes <text> | Optional. Specifies the release note text shown to users. Enclose the text in quotation marks. Encode double quotes as ". Encode newlines as \n. |
-p <arguments> --launch_params <arguments> | Optional. Specifies any arguments passed to the launcher. |
--assets-dir <dirPath> | Optional Specifies the path to the directory with DLCs for this build. |
--asset-files-config <filePath> | Optional. Specifies the path to the file that configures required assets or associates DLC assets with in-app purchases |
--language-packs-dir <file-path> | Optional. The path to the directory that contains language packs. |
-L <2DLaunchFile> --launch_file_2d <2DLaunchFile> | Optional. Specifies the relative path from the build directory to the executable that launches your app in 2D mode. |
-P <2DArguments> --launch_params_2d <2DArguments> | Optional. Specifies any arguments passed to the launcher in 2D mode. |
-r <redistID>,<redistID2>... --redistributables <redistID>,<redistID2>.... | Optional. Specifies one or more redistributable IDs. Enclose the IDs with quotation marks. Separate multiple redistributable IDs with commas. Example - “RedistID1,RedistID2”. See the Redistributable section for a complete list of redistributables and their IDs |
-f {true/false} --firewall_exceptions {true/false} | Optional. Specifies if a Windows Firewall exception is required. True or False. Default is false. |
For the full syntax and parameter descriptions, see the Oculus Platform Command Line Utility page.
Syntax | Description |
--help | Optional. Show help for the command |
--clean | Optional. Skips the caching layer and performs a fresh upload. Use this if you want to force the tool to start over and recompute the checksums of an interrupted upload session instead of continuing where it left off. |
--add-entitlement-check | Optional. Adds entitlement check code to the executable. Use this if you want to automate the entitlement check process in your application. |
--inherit-asset-files | Optional. A boolean that indicates whether to inherit asset files from the previous build. The default is false. |
--exclude-addons | Optional. A boolean that indicates whether to exclude the add-ons associated with this app. The default is false. |
This upload example uses the fictitious app “Rabbit Hole” and assumes the following sample parameters. Note that the example shows Windows file syntax.
*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 --token 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 --token 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 --token 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
Following is the syntax and parameters for downloading a Rift app to the Oculus store.
$ ovr-platform-util download-rift-build -b <BuildID> -d <Directory>
Syntax | Description |
---|---|
-b <buildID> --build_id <buildID> | Required. Specifies the build ID you want to download. You can obtain this from the CLI output after successfully uploading an app build with the command line tool. |
-d <directory> --output_dir <directory> | Required. Specifies the directory you want to download the build to. |
Rift Download Example
To download the app build with build ID 3141592653589793 to “C:\Pie Thrower”:
$ ovr-platform-util download-rift-build -b 3141592653589793 -d "C:\Pie Thrower"
Add Oculus Platform Entitlement Check to specified executables.
$ ovr-platform-util add-entitlement-check -b <BuildID> -d <Directory>
Syntax | Description |
---|---|
-d <buildPath> --build_dir <buildPath> | Required. Specifies the full path to the directory containing your build files. |
-d <directory> --output_dir <directory> | Required. Specifies the directory you want to download the build to. |
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.
ovr-platform-util clone-rift-build --app_id <AppID> --app_secret <App-Secret> --token <User-Token> --source_channel <Channel> --destination_channel <Channel> [OPTIONS]
Syntax | Description |
---|---|
-a <ID> -app_id <ID> | Required. Specifies the ID of your app. Obtained from the API tab of your app in the Oculus Dashboard. |
-s <app-secret> --app_secret <app-secret> | Either app secret or user token required. Specifies the app secret. Obtained from the API tab of your app in the Oculus developer dashboard. |
-t <token> --token <token> | Either app secret or user token required. A user token obtained by the get-access-token command or from the API tab of your app in the Oculus developer dashboard. |
--destination_channel <channel> | Required. Specifies the release channel to be updated. |
--source_channel <channel> | Optional. If specified, the build from this channel will be copied to the destination channel. |
-b <buildID> --build_id <buildID> | Optional. Specifies the build ID you want to download. You can obtain this from the CLI output after successfully uploading an app build with the command line tool. |
-v <version-number> --version <version-number> | Required. Specifies the version number shown to users. |
-l <launchFile> --launch_file <launchFile> | Required. Specifies the relative path from the the build directory to the executable that launches your app. |
-n <text> --notes <text> | Optional. Specifies the release note text shown to users. Enclose the text in quotation marks. Encode double quotes as ". Encode newlines as \n. |
-p <arguments> --launch_params <arguments> | Optional. Specifies any arguments passed to the launcher. |
-L <2DLaunchFile> --launch_file_2d <2DLaunchFile> | Optional. Specifies the relative path from the build directory to the executable that launches your app in 2D mode. |
-P <2DArguments> --launch_params_2d <2DArguments> | Optional. Specifies any arguments passed to the launcher in 2D mode. |
-r <redistID>,<redistID2>... --redistributables <redistID>,<redistID2>.... | Optional. Specifies one or more redistributable IDs. Enclose the IDs with quotation marks. Separate multiple redistributable IDs with commas. Example - “RedistID1,RedistID2”. See the Redistributable section for a complete list of redistributables and their IDs |
-f {true/false} --firewall_exceptions {true/false} | Optional. Specifies if a Windows Firewall exception is required. True or False. Default is false. |
-w {"7SP1"/8.1/10} --windows_min_version {"7SP1"/8.1/10} | Optional. Specifies the minimum required Windows version. The versions that can be specified are “7SP1”, 8.1, 10. The default is “7SP1”. |
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"
Following is a list of redistributable packages and their associated IDs.
Name | Redistributable ID |
---|---|
.NET Framework 3.5 | 606493776156948 |
.NET Framework 4.0 | 133610290311340 |
.NET Framework 4.5.1 | 1617306711884127 |
.NET Framework 4.7.1 | 1667821599930345 |
DirectX (June 2010) | 822786567843179 |
OpenAL 1.1 | 1147517301974655 |
Visual C++ | 20051604897159783747 |
Visual C++ | 2008118440348500045 |
Visual C++ | 2010532320330249657 |
Visual C++ | 2010 x861008652072555515 |
Visual C++ | 20121683508698536289 |
Visual C++ | 2012 x861002692246447245 |
Visual C++ | 20131675031999409058 |
Visual C++ | 2013 x86910524935693407 |
Visual C++ | 2015 Update 31183534128364060 |
Visual C++ | 2015 x86 Update 31113033105419344 |
Visual C++ | 20171315322525257173 |
Visual C++ | 2017 x861064693870299984 |
Visual C++ | 20192657209094360789 |
Visual C++ | 2019 x862556834837738356 |
Vulkan Runtime | 1.0.65.11824471960899274 |
Vulkan Runtime | 1.1.73.01941020095932382 |
Following is the syntax and parameters for uploading a Quest app to the Oculus store.
ovr-platform-util upload-quest-build --app_id <ID> --app_secret <App-Secret> --token <User-Token> --apk <path/to/Your.apk> --obb <path/to/Your.obb> --assets-dir <path/to/DLCs/dir> --channel <ReleaseChannel> --notes <ReleaseNotes> --asset-files-config <config.json> --language-packs-dir <path> [--help {true|false}] [--inherit-assets {true|false}] [--exclude-addons {true|false}]
Syntax | Description |
---|---|
-a <ID> -app_id <ID> | Required. Specifies the ID of your app. Obtained from the API tab of your app in the Oculus Dashboard. |
-s <app-secret> --app_secret <app-secret> | Either app secret or user token required. Specifies the app secret. Obtained from the API tab of your app in the Oculus developer dashboard. |
-t <token> --token <token> | Either app secret or user token required. A user token obtained by the get-access-token command or from the API tab of your app in the Oculus developer dashboard. |
--apk <filePath> | Required. Specifies the path to the APK file to upload. |
--assets-dir <dirPath> | Optional Specifies the path to the directory with DLCs for this build. |
--asset-files-config <filePath> | Optional. Specifies the path to the file that configures required assets or associates DLC assets with in-app purchases |
--obb <filePath> | Optional. Specifies the path to the Expansion file (OBB) to upload. |
-c <releaseChannel> --channel <ReleaseChannel> | Required. Specifies the release channel for uploading the build. Release channel names are not case-sensitive. |
-n <text> --notes <text> | Optional. Specifies the release note text shown to users. Enclose the text in quotation marks. Encode double quotes as ". Encode newlines as \n. |
--language-packs-dir <file-path> | Optional. The path to the directory that contains language packs. |
Syntax | Description |
--help | Optional. Show help for the command |
`` --inherit-asset-files | Optional. A boolean that indicates whether to inherit asset files from the previous build. The default is false. |
`` --exclude-addons | Optional. A boolean that indicates whether to exclude the add-ons associated with this app. The default is false. |
This upload example uses the fictitious app “Rabbit Hole”. Note that these examples show syntax used on Windows.
For Quest enter:
$ ovr-platform-util upload-quest-build --app-id 10001234 --token 1234abcd --apk C:\RabbitHole.apk --channel alpha --notes "Fixes the rabbit spawn bug."
Following is the syntax and parameters for downloading a Quest app from the Oculus store.
ovr-platform-util download-quest-build -b <BuildID> -d <Directory>
Syntax | Description |
---|---|
-b <buildID> --build_id <buildID> | Required. Specifies the build ID you want to download. You can obtain this from the CLI output after successfully uploading an app build with the command line tool. |
-d <directory> --output_dir <directory> | Required. Specifies the directory you want to download the build to. |
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"
ovr-platform-util set-release-channel-build --app_id <AppID> --app_secret <App-Secret> --token <User-Token> --source_channel <Channel> --destination_channel <Channel>
Syntax | Description |
---|---|
-d <buildPath> --build_dir <buildPath> | Required. Specifies the full path to the directory containing your build files. |
-s <app-secret> --app_secret <app-secret> | Either app secret or user token required. Specifies the app secret. Obtained from the API tab of your app in the Oculus developer dashboard. |
-t <token> --token <token> | Either app secret or user token required. A user token obtained by the get-access-token command or from the API tab of your app in the Oculus developer dashboard. |
-d <directory> --output_dir <directory> | Required. Specifies the directory you want to download the build to. |
--destination_channel <channel> | Required. Specifies the release channel to be updated. |
-b <buildID> --build_id <buildID> | Optional. Specifies the build ID you want to download. You can obtain this from the CLI output after successfully uploading an app build with the command line tool. |
--source_channel <channel> | Optional. If specified, the build from this channel will be copied to the destination channel. |
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
The utility enables you to manage add-ons such as downloadable content (DLC) and in-app purchases (IAP) with the upload-add-on
command. For more information, see Add-ons.
$ ovr-platform-util.exe upload-add-on --app_id <AppID> --app_secret <App-Secret> --token <User-Token> --file <file> --sku <sku> --min-version-code <min-version>
Syntax | Description |
---|---|
-a <ID> -app_id <ID> | Required. Specifies the ID of your app. Obtained from the API tab of your app in the Oculus Dashboard. |
-s <app-secret> --app_secret <app-secret> | Either app secret or user token required. Specifies the app secret. Obtained from the API tab of your app in the Oculus developer dashboard. |
-t <token> --token <token> | Either app secret or user token required. A user token obtained by the get-access-token command or from the API tab of your app in the Oculus developer dashboard. |
-f <file-path> --file <file-path> | Required. The path to the asset file to upload. |
-p <SKU> --sku <SKU> | Required. The SKU associated with the add-on item. |
-v <version-code> --min-version-code <version-code> | Required. The minimum build number of the app to associate this add-on item with. |
Add-on Example
The following examples show how to upload the add-on “carrot”.
$ ovr-platform-util upload-add-on --app-id 10001234 --app-secret 1234abcd --file C:\rabbit-hole\dlc\ --sku carrot