OCP CLI v2 migration guide

11 min

Use the following guide to migrate from Optimizely Connect Platform (OCP) CLI v1 to v2.

New in v2

OCP CLI v2 introduces several new features and improvements, including the following:

Multiple package manager support – Lets you use your preferred package manager.

ocp updated – Lets you update the CLI to the latest version by displaying the list of available versions (ocp update --available)

ocp autocomplete – Contains Shell autocompletion for commands and options, including Bash, Zsh, and PowerShell. You need PowerShell 7+ to autocomplete Windows. Run the command and follow the instructions provided in the terminal to autocomplete.

Flexible parameter syntax – Supports both --param value and --param=value syntaxes, for example, ocp app validate --path /Users/foo/my-app/ and ocp app validate --path=/Users/foo/my-app/.

Install OCP CLI v2

Uninstall CLI v1

Uninstall OCP CLI v1 if you installed it globally through yarn to avoid conflicts.

yarn global remove @optimizely/ocp-cli

Ensure ocp command is unavailable.

which ocp           # macOS/Linux
Get-Command ocp     # Windows (powershell)
# Should return no result

Install OCP CLI v2

Explicitly request the latest beta version when running the installation script, as the default behavior is to fetch the stable release.

Run the following Bash or Zsh script for MacOS or Linus:

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

Run the following PowerShell script for Windows:

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

Avoid global installations of this package using yarn or npm. Global installations tie the CLI to the Node.js runtime version on individual machines, which can lead to unexpected conflicts and inconsistent behavior.

Instead, use the script-based approach. This method ensures the CLI operates independently of the user's local Node.js runtime, providing a more stable and predictable experience.

Verify installation

Run the following script:

ocp --version
# Should show v2.x.x (e.g., "ocp-cli v2.0.0-beta.5")
# If you see v1.x.x, the old CLI is still in your PATH - see "Uninstall old CLI" section above

Run OCP CLI commands using npx

You can 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.

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

Package manager support

OCP CLI v2 supports multiple package managers for applications running Node.js 22+ environments, including Yarn (Berry and v3+), npm, pnpm, and Bun.

Use any of these package managers in your project. The build system automatically detects your package manager from the project configuration.

📘 Note Package manager support is for Node.js 22+ runtime only. Applications using older runtimes should continue using Yarn. See the Node 22 migration guide for upgrading your app's runtime.

Migrating from Yarn 1

For applications using Node.js 22+ that require a different package manager, such as npm, pnpm, Bun, or Yarn Berry, see Package manager migration guide

Prerequisites

You must migrate to OCP CLI v2.

You must have an application running on Node.js 22+ runtime.

Validate your app

After installation, execute the following validation command to ensure it runs smoothly. A successful validation indicates your application is functional and ready for v2.

ocp app validate

Quickstart to migration

Uninstall OCP CLI v1 if previously installed through yarn or npm.

Install OCP CLI v2 or use it directly through npx.

Confirm you are on v2 by executing ocp --version. The expected output is v2.x.x.

Run ocp app validate to ensure full functionality.

(Optional) See Package manager migration guide if you are using Node.js 22+ and want to migrate from Yarn 1.