Configure your development environment

17 min

Develop, manage, and publish a Connect Platform for Optimizely Data Platform (ODP) app using the Connect Platform for ODP command-line interface (CLI). You can configure the OCP CLI on either a Mac/Linux machine or a Windows machine. Skip directly to the section that pertains to your environment.

Note If you are migrating from OCP CLI v1, see the OCP CLI v2 migration guide for instructions on uninstalling v1 and upgrading to v2.

Prerequisites

A Connect Platform for ODP developer account.

The API key from your invitation email.

Node.js 22+ JavaScript runtime environment, required for app development. Find your platform-specific installer on the Node.js site, or use your preferred Node version manager for the installation.

A package manager for app development. Apps running Node.js 22+ support Yarn, Yarn Berry, npm, pnpm, and Bun. Apps on older runtimes require Yarn 1. See the Yarn global installation instructions or, if you are on Windows, install Yarn through Corepack.

Note If your app uses Node.js 22+ and you want to migrate from Yarn 1 to a different package manager, see the Package manager migration guide.

The OCP CLI requires Git to build an app. Find global install instructions for Git here.

Note If you are not planning to build an app, you can skip the Git install.

Configure the OCP CLI for Mac/Linux

Run the following command to make a .ocp directory:

mkdir ~/.ocp (home dir)

Using the API key you received during onboarding, create the credentials file in the .ocp directory:

echo '{"apiKey": "<value-from-invitation>"}' > ~/.ocp/credentials.json

Run the following script to install the OCP CLI:

curl -fsSL https://cli.ocp.optimizely.com/install.sh | bash

The script downloads the latest OCP CLI release, verifies the tarball checksum, installs it to ~/.local/share/ocp, and adds the ocp binary to your PATH. The CLI ships with its own runtime, so it operates independently of any local Node.js installation.

Configure the OCP CLI for Windows

Note The following instructions are for PowerShell.

Run the following command to make a .ocp directory:

New-Item -Path "~/.ocp" -Name "home dir" -ItemType "directory"

Using the API key you received during onboarding, create the credentials file in the .ocp directory:

Write-Output '{"apiKey": "<value-from-invitation>"}' | out-file "~/.ocp/credentials.json" -encoding utf8

Run the following PowerShell script to install the OCP CLI:

iwr -useb https://cli.ocp.optimizely.com/install.ps1 | iex

The script downloads the latest OCP CLI release, verifies the tarball checksum, installs it to $env:LOCALAPPDATA\ocp, and adds the ocp binary to your PATH. The CLI ships with its own runtime, so it operates independently of any local Node.js installation.

Test your OCP CLI configuration

Verify your OCP CLI configuration by running the following command:

ocp accounts whoami

The results should look similar to the following:

$ ocp accounts whoami
id: e1006b36-183e-4951-912c-416012f5a882
email: [email protected]
role: developer
githubUsername: jonhsmith
accounts:
  - 7b5d1518a0be
personal_apps: []
vendor: mycompany
vendor_apps: []

(Optional) Configure PowerShell autocomplete

The OCP CLI supports shell autocomplete for Bash, Zsh, and PowerShell, with PowerShell 7+ for Windows. To configure autocomplete, run the following command and follow the instructions displayed in the terminal:

ocp autocomplete

Restart your shell or source the relevant configuration file after configuration. Press Tab while entering an ocp command to autocomplete commands and subcommands. To autocomplete flags, enter - and press Tab. Press Tab twice to display all available options for the current input.

OCP CLI help command

Commands are grouped into namespaces:

$ ocp -h
Usage: ocp <command>

Namespaces: (`<namespace>` -h, --help for additional help)
  accounts       
  app            
  availability   
  directory      
  env            
  jobs           
  review

Commands:
  autocomplete  Display autocomplete installation instructions
  dev           Start the local development server for OCP apps
  update        Update the OCP CLI

Run the help command, -h or --help, to list commands in a namespace. See the following example:

$ ocp app -h
Usage: ocp app <command>

Commands:
  init       Create a new app project                                            
  logs       Fetch app logs
  package    Prepare a package for manual upload                                 
  prepare    Validate, package, upload and build an app to prepare for publishing
  register   Register an app version                                             
  validate   Validate an app locally                                             

ocp <command> -h, --help for help on specific commands

Adding the help context on a command displays documentation for the command with all available options. See the following example:

$ ocp app prepare -h
Usage: ocp app prepare [<path>] [--noProgress | --no-progress] [--upgradeDeps | --upgrade-deps] [--publish] [--usePreviousAppEnvValues | --use-previous-app-env-values]
                [--bumpDevVersion | --bump-dev-version]

Parameters:
  path   The root directory of the app

Flags:
  --noProgress, --no-progress                                Don't display any progress indicators                                                                             
  --upgradeDeps, --upgrade-deps                              Automatically update dependencies                                                                                 
  --publish                                                  Automatically publish if the upload is successful                                                                 
  --usePreviousAppEnvValues, --use-previous-app-env-values   Use app env values (.env file) from the previous version of the app. Any values in local .env file will be ignored
  --bumpDevVersion, --bump-dev-version                       Bump dev version before building. Allows quickly testing dev versions

Run OCP CLI commands using npx

You can also run OCP CLI commands directly using npx, without requiring any installation. However, ensure your shell has the correct Node.js runtime version for the application to function as expected. See the following example:

npx @optimizely/ocp-cli-v2 app init
npx @optimizely/ocp-cli-v2 app validate
npx @optimizely/ocp-cli-v2 app package

OCP CLI commands

The table below lists all available OCP CLI commands with their parameters and descriptions.

Command	Parameters	Description
ocp -h	N/A	The help context for the CLI is -h. It provides information about your environment when you run ocp -h and provides contextual help when you add -h after any command.
ocp -v or ocp --version	N/A	Displays the installed CLI version.
ocp autocomplete	N/A	Displays shell autocompletion installation instructions. Supports Bash, Zsh, and PowerShell, with PowerShell 7+ for Windows. Run the command and follow the instructions provided in the terminal.
ocp update	N/A	Updates the CLI to the latest version. You can append --available to display the list of available versions.
ocp accounts whoami	N/A	Returns your account information.
ocp accounts whois	<user>	Returns basic account information for a specific user. Requires a user input, for example, ocp accounts whois "user".
ocp app init	<appId>	Creates a new app project and initializes the app. Requires the app ID, for example, ocp app init <appId>.
ocp app logs	<appId> or <buildId>	Returns app logs. Requires the app ID or build ID, for example, ocp app logs <buildId>. See additional flags and options.
ocp app getLogLevel or ocp app get-log-level	<appId@appVersion>	Returns the log level for the app version that you specify. Requires the app ID and version in the following format: <appId@appVersion>. See additional flags and options.
ocp app setLogLevel or ocp app set-log-level	<appId@appVersion> <logLevel>	Sets the log level for the app version that you specify. Options are debug, info, warn, error, never. Requires the app ID and version in the following format: <appId@appVersion>. See additional flags and options.
ocp app package	<path>	Prepares a package for manual upload. Requires the path for the root directory of the app, for example, ocp app package <path>.
ocp app prepare	<path>	Validates, packages, uploads, and builds an app to prepare for publishing. Requires the path for the root directory of the app, for example, ocp app prepare <path>. See additional flags and options.
ocp app register	<id> <name>	Registers an app version. Requires the app ID and name, for example, ocp app register <id> <name>. You can append --availability or --a to define the availability region to which the app is registered (default is US).
ocp app validate	<path>	Validates an app locally. Requires the path for the root directory of the app, for example, ocp app validate <path>. See additional flags and options.
ocp app abandon	<appId@appVersion>	Ceases the processing of the specified app version that you have not published yet. You can append --noPrompt or --no-prompt to use the default answer (yes) to any prompt question, except for destructive operations. For example, ocp app abandon <appId@appVersion>.
ocp availability list	N/A	Lists all availability regions (US, EU, AU).
ocp dev	N/A	Starts the local development server for OCP apps. This is a quick-start command. For more configuration options, use ocp dev-server start.
ocp dev-server start	N/A	Starts the local development server with configuration options. Optionally specify the path to the OCP app root directory. See additional flags and options.
ocp directory unpublish	<appId@appVersion>	Unpublishes an app version (uninstalls everywhere and undeploys). Requires the app ID and version in the following format: <appId@appVersion>. For example, ocp directory unpublish <appId@appVersion>. See additional flags and options.
ocp directory publish	<appId@appVersion>	Publishes (makes available) a specific app version that has been reviewed and approved. Requires the app ID and version in the following format: <appId@appVersion>. For example, ocp directory publish <appId@appVersion>. You can append --noProgress or --no-progress.
ocp directory info	<appId>	Gets information about an app. Requires the app ID, for example, ocp directory info <appId>. You can append --availability or --a to define the availability region of the app (default is US).
ocp directory install	<appId@appVersion> <trackerId>	Installs a specific app version into an account. Requires the app ID and version (in the following format: <appId@appVersion>), and the tracker ID of the account to which you want to install the app. For example, ocp directory install <appId@appVersion> <trackerId>. You can append --availability or --a to define the availability region of the app (default is US).
ocp directory list	<appId>	Lists registered app versions. Lists all apps by default if you do not define the app ID, for example, ocp directory list <appId>. See additional flags and options.
ocp directory listFunctions or ocp directory list-functions	<appId> <trackerId>	Lists the functions exposed by an app installation. Requires the app ID and tracker ID, for example, ocp directory listFunctions <appId> <trackerId>. You can append --availability or --a to define the availability region of the app (default is US).
ocp directory listGlobalFunctions or ocp directory list-global-functions	<appId>	Lists the global functions exposed by an app. Requires the app ID, for example, ocp directory listGlobalFunctions <appId>. You can append --availability or --a to define the availability region of the app (default is US).
ocp directory listInstalls or ocp directory list-installs	<appId@appVersion>	Lists installations of a specific app version. Requires the app ID and version (in the following format: <appId@appVersion>). For example, ocp directory listInstalls <appId@appVersion>. You can append --availability or --a to define the availability region of the app (default is US).
ocp directory status	<appId@appVersion>	Gets the status of a particular app ID and version. Requires the app ID and version (in the following format: <appId@appVersion>). For example, ocp directory status <appId@appVersion>. You can append --availability or --a to define the availability region of the app (default is US).
ocp directory uninstall	<appId> <trackerId>	Uninstalls an app from an account. Requires the app ID and tracker ID, for example, ocp directory uninstall <appId> <trackerId>. You can append --availability or --a to define the availability region of the app (default is US).
ocp directory upgrade	<appId <trackerId>	Upgrades the install to a specific app version. Requires the app ID and tracker ID, for example, ocp directory upgrade <appId> <trackerId>. See additional flags and options.
ocp env get	N/A	Gets the current environment of the OCP CLI.
ocp env set	<env>	Sets the current environment for the OCP CLI. Requires the environment name.
ocp jobs list	<appId>	Lists jobs. Requires the app ID for which you want to view jobs, for example, ocp jobs list <appId>. See additional flags and options.
ocp jobs terminate	<jobId>	Terminates a job. Requires the ID of the job to terminate. You can append --availability or --a to define the availability region (default is US).
ocp jobs trigger	<appId@appVersion> <jobName> <trackerId>	Triggers a job. Requires the app ID and version (in the following format: <appId@appVersion>), job name, and tracker ID of the account for which you want to trigger the job. For example, ocp jobs trigger <appVersion> <jobName> <trackerId>. See additional flags and options.
ocp review list	<appId>	Lists app versions currently under review. You can optionally define the app ID of the app for which you want to view versions under review (for example, ocp review list <appId>. Lists all apps by default.
ocp review open	<appId@appVersion>	Opens a review in your browser. Requires the app ID and version (in the following format: <appId@appVersion>). For example, ocp review open <appId@appVersion>

Additional flags/options for OCP CLI commands

You can append various flags/options for some of the OCP CLI commands, listed below.

ocp app logs

--tail – Tails the logs.

--appId

--buildId

--appVersion

--trackerId

--jobId

--installId

--from – A start time as an ISO string, an epoch timestamp, or relative string (for example, 5m for 5 minutes). Default is 24h.

--to – An end time as an ISO string, an epoch timestamp, or relative string (for example, 5m for 5 minutes).

--search – String to search for in log messages. Can be specified multiple times.

--availability or -a – The availability region that will be targeted (default is US).

ocp app getLogLevel or ocp app get-log-level

--trackerId – Specific Tracker ID to filter by.

--availability – The availability region that will be targeted (default is US).

ocp app setLogLevel or ocp app set-log-level

--trackerId – Specific Tracker ID to filter by.

--timeToLive – Expiration period for the log level as a relative string (for example, 5m for 5 minutes). Default is 2 hours (2h).

--availability – The availability region that will be targeted (default is US).

ocp app prepare

--noProgress or --no-progress – Do not display any progress indicators.

--upgradeDeps or --upgrade-deps – Automatically update dependencies.

--publish – Automatically publish if the upload is successful.

--usePreviousAppEnvValues or --use-previous-app-env-values – Use app env values (.env file) from the previous version of the app. Any values in the local .env file will be ignored.

--bumpDevVersion or --bump-dev-version – Bump dev version before building. Allows you to quickly test dev versions.

ocp app validate

--noProgress or --no-progress – Do not display any progress indicators.

--upgradeDeps or --upgrade-deps – Automatically update dependencies.

ocp dev-server start

--port or -p – Port to run the server on (default: 3000).

--verbose or -v – Enable verbose logging.

--noOpen or --no-open – Do not automatically open the browser.

--config or -c – Path to custom configuration file.

--path – Path to the OCP app root directory.

ocp directory unpublish

--force or -f

--noProgress or --no-progress

--availability or -a – The availability region that will be targeted (default is US).

ocp directory publish

--noProgress or --no-progress

ocp directory list

--allStatuses – Includes all statuses. The stopped status is not included by default.

--availability or -a – The availability region that will be targeted (default is US).

ocp directory upgrade

--toVersion or -v – The desired version (for example, 1.0.0).

--availability or -a – The availability region that will be targeted (default is US).

ocp jobs list

--version – Specific versions to filter by.

--trackerId – Specific Tracker IDs to filter by.

--function – Specific job function to filter by.

--status – Specific job status to filter by. Possible values include the following: PENDING, SCHEDULED, RUNNING, COMPLETE, ERROR, TERMINATED.

--minDuration – Display jobs that were running longer than the given duration (for example, 5m = 5 minutes).

--sortBy – Column to sort the jobs by. Possible values include the following: id, function, trackerId, status, error, createdAt, triggeredAt, scheduledAt, terminatedAt, updatedAt, duration. The default column to sort by is updatedAt.

--sortDirection – Sort resulting jobs in ascending or descending order. Possible values include the following: asc or desc. The default sort direction is asc.

--limit – Number of jobs to list. The default is 50.

--columns – Columns to display. Possible values include the following: id, version, function, trackerId, trigger, status, error, createdAt, triggeredAt, scheduledAt, terminatedAt, updatedAt, duration. The default columns are id, version, function, trackerId, status, updatedAt.

--from – A start time as an ISO string, an epoch timestamp, or relative string (for example, 5m = 5 minutes). The default time value is 24h.

--to – An end time as an ISO string, an epoch timestamp, or relative string (for example, 5m = 5 minutes).

--availability or -a – The availability region that is targeted (default is US).

ocp jobs trigger

--parameters – Parameters to pass to the job.

--availability or -a – The availability region that will be targeted (default is US).

Uninstall OCP CLI

If you want to completely remove OCP CLI from your system, run the following script for MacOS or Linux:

rm -rf ~/.local/share/ocp ~/.local/bin/ocp

Run the following script for Windows:

Remove-Item -Recurse -Force "$env:LOCALAPPDATA\ocp"