Configure your OCP development environment

22 min

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

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 | 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
  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_app

The 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 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:

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-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"