Dev GuideUser Guides
Dev GuideAPI Reference
Dev GuideUser GuidesGitHubDev CommunityOptimizely AcademySubmit a ticketLog In
Dev Guide
GitHubDev CommunityOptimizely AcademySubmit a ticket

Configure your OCP development environment

Configure the development environment needed for building custom apps for Optimizely Connect Platform (OCP).

Develop, manage, and publish an Optimizely Connect Platform (OCP) app using the OCP command-line interface (CLI). Configure the OCP CLI on a Mac or Linux machine or a Windows machine. Skip 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

Configure the OCP CLI for Mac or Linux

  1. Run the following command to make a .ocp directory:

    mkdir ~/.ocp (home dir)

  2. Create the credentials file in the .ocp directory using the API key you received during onboarding:

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

  3. 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. It also 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.

  1. Run the following command to make a .ocp directory:

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

  2. Create the credentials file in the .ocp directory using the API key you received during onboarding:

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

  3. 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 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: []

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

(Optional) Configure OCP autocomplete

The OCP CLI supports shell autocomplete for Bash, Zsh, and PowerShell 7+. 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.

Autocomplete dynamic values

Autocomplete suggests values for command arguments and flags fetched from your account. After setting up autocomplete, press Tab at the position where a value is expected:

ExampleWhat Tab suggests
ocp directory list-installs <Tab>App IDs you have access to
ocp directory publish my_app@<Tab>Versions of my_app (type @ to switch from app names to that app's versions)
ocp jobs list --appId <Tab> --appVersion <Tab>App versions for the given app
ocp app set-log-level [email protected] <Tab>Valid log levels
ocp jobs list <appId> --status=<Tab> --version=<Tab>Supported job statuses and versions for the app
ocp ... -a <Tab>Availability shards (us, eu, etc.)

Static option lists, such as log levels, job statuses, environments, and sort directions, are always available. Dynamic values, such as app IDs or versions, are fetched from the platform on first use and cached locally so subsequent Tab presses are instant.

Refresh the autocomplete cache

The autocomplete cache is refreshed automatically in the background after ocp autocomplete is run. If you registered a new app or published a new version and want it to display immediately in suggestions, refresh the cache manually:

ocp autocomplete --refresh-cache
📘

Note

If a refresh fails (for example, due to a network issue), the cache retains its stored values so autocomplete continues to work with the most recent known data. Any entries that were not refreshed are listed at the end of the command's output.

Local development server

The OCP CLI includes a built-in local development server that helps you develop and test your apps locally before publishing. Start the local development server with:

# Quick start (recommended)
ocp dev

# With additional configuration options
ocp dev-server start --port=3001 --verbose
📘

Note

The local development server is available through the OCP CLI. For additional configuration options, use ocp dev-server start --help.

For detailed usage instructions, see Test your app locally.

OCP CLI commands

Commands are grouped into namespaces.

$ ocp -h
Usage: ocp <command>

Namespaces: (`<namespace>` -h, --help for additional help)
  accounts
  app
  availability
  dev-server
  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 app env values (.env file) from the previous version of the app. 
                                     Any values in local .env file are ignored
  --bumpDevVersion                   Bump dev version before building. Allows quickly testing dev versions

For the full list of OCP CLI commands, namespaces, flags, and options, see the OCP CLI command reference.

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"