Configure your OCP development environment
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 use an AI coding agent such as Claude Code, Cursor, or GitHub Copilot, install the OCP skill for accurate, OCP-specific code suggestions and guidance. See the installation guide.
Prerequisites
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.
- A Developer role for at least one OCP instance in your organization. See Developer Portal overview.
- An API key generated in the Developer Portal. See Developer Portal overview.
- 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 Node.js runtimes earlier than version 22 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. See the Git global installation instructions.
Note
If you are not planning to build an app, you can skip the Git install.
Generate your API key
The OCP CLI authenticates with an API key that you generate and manage in the Developer Portal. See Developer Portal overview for information on generating the API key.
Important
Regenerating invalidates your previous key immediately. Any OCP CLI session or CI/CD pipeline that uses the old key fails until you update it.
Work in multiple organizations
The OCP CLI uses one API key at a time. To manage the apps that belong to a different organization, replace the key in ~/.ocp/credentials.json with that organization's key. See Developer Portal overview for information on generating API keys for multiple organizations.
Run ocp accounts whoami to confirm which developer account your current key resolves to. The vendor field in the Profile section identifies the developer organization bound to the configured API key.
The OptiID account access section reflects your Opti ID user rather than the API key. It is the same for every key you configure. Replacing the key changes the Profile fields and the Vendor apps list, but not the accounts you can reach. See Understand the output for a description of each section.
Configure the OCP CLI for Mac or Linux
- Run the following command to make a .ocp directory:
mkdir ~/.ocp (home dir)- Create the credentials file in the .ocp directory using the API key you generated in the Developer Portal:
echo '{"apiKey": "<your-api-key>"}' > ~/.ocp/credentials.json- Run the following script to install the OCP CLI:
curl -fsSL https://cli.ocp.optimizely.com/install.sh | bashThe 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.
- Run the following command to make a .ocp directory:
New-Item -Path "~/.ocp" -Name "home dir" -ItemType "directory"- Create the credentials file in the .ocp directory using the API key you generated in the Developer Portal:
Write-Output '{"apiKey": "<your-api-key>"}' | 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 | iexThe 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 whoamiThe results look similar to the following:
$ ocp accounts whoami
Profile
id c19a5189-5a0d-4b7f-8272-f26b5d954320
email [email protected]
role deployer
vendor acme
username jsmith
github username johnsmith
created 2025-01-01 15:00
OptiID account access
Organization Acme Corporation
OCP/ODP accounts
tracker Id name availability zone type
euYdNiVdeR Acme Test us OCP
KcTMuByrxc-eu1 Acme Test EU eu OCP
KDMqBYgRRd-au Acme Test AU au ODP
Personal apps (1)
john_personal_app
Vendor apps (1)
acme_appThe OptiID account access section lists the accounts you can reach. For a description of each section of the output, see Understand the output.
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 autocompleteRestart 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:
Example | What 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-cacheNote
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 CLIRun 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 commandsAdding 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 versionsFor 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/ocpRun the following script for Windows:
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\ocp"