OCP CLI

Interfacing with Optimizely Connect Platform (OCP).

Installation

OCP CLI requires a recent version of nodejs as well as Yarn. We suggest installing Yarn through corepack, as described here: https://yarnpkg.com/getting-started/install

Install OCP CLI with:

yarn global add @optimizely/ocp-cli

Commands can then be executed as follows:

ocp
ocp <namespace> -h

Per-ticket builds

A branch can be published to its own staging release channel so testers can run it without waiting for a release.

1. Run the Publish a per-ticket CLI build workflow (Actions → Run workflow).
2. Pick the branch and set channel to the ticket, e.g. OCP-2226.

The build is published as <version>-<ticket>.<run> to channels/<ticket>/. It is not published to npm and creates no git tag, GitHub release or changelog entry, so npm i @optimizely/ocp-cli-v2@… will never find it.

Every CLI build updates from the production bucket, so to switch to the ticket channel, point that one update at the staging bucket:

OCP_S3_BUCKET=zaius-public-stag01 ocp update ocp-2226

The channel name is the ticket in lower case. ocp update remembers it in ~/.local/share/ocp/channel, but later updates go back to production, where the ticket channel does not exist: background autoupdates quietly skip, and a plain ocp update fails with Error: HTTP 403: Invalid channel <ticket>. Run the command above again to pick up newer builds of the channel, or export OCP_S3_BUCKET in that shell to keep autoupdates on it.

To go back to the released CLI, leave the channel:

ocp update stable

OCP_S3_BUCKET only takes effect on CLI versions that ship without a hardcoded update host (releases after 2.0.14). On older versions, run ocp update first.

Releasing

Releasing is two steps: a reviewed PR that bumps the version, then a workflow that publishes whatever is on main. The workflow never writes to main — an org ruleset requires a status check that a freshly built commit can never carry, so a direct push is always rejected.

1. Open a bump PR. From a branch off main:

git fetch --tags --force                     # the changelog is rebuilt from the tag set
npm version <version> --no-git-tag-version   # e.g. 2.0.12 or 2.0.12-beta.1
npx [email protected]

Commit both files as Release <version>, then get the PR reviewed and merged like any other change.

The GitHub release notes are this version's CHANGELOG.md section, printed by scripts/release-notes.sh <version>. The release workflow fails before publishing anything if that section has no entries.

auto-changelog regenerates the whole file from the tags present locally, so the diff is not limited to the new section. Expect the previous release to gain its date and Release <version> commit — its section was written before that tag existed. If older sections churn too, your clone's tag set differs from the last generator's; git fetch --tags --force first keeps that from recurring.

2. Run the release. Actions → Release and publish → Run workflow against main. It tags the commit, publishes to npm, creates the GitHub release, and uploads signed tarballs to staging and production. A prerelease version (anything with a -suffix) goes to the beta npm dist-tag and the beta update channel; everything else goes to latest and stable.

Use Dry run to validate the build and print what would be published without changing anything.

The workflow releases exactly the version in package.json — it does not bump anything. Forgetting step 1 means re-releasing the current version, which fails once npm rejects the duplicate.

A failed release is not resumable. npm is published before the tag is pushed, so a failure in between leaves the version on npm with no tag, release or tarballs, and it cannot be republished. Recovering means deprecating that version and releasing the next one.

Commands

PR Lane Support

To route CLI requests to a PR lane deployment of the backend, set the OCP_PR_LANE environment variable:

OCP_PR_LANE=OCP-1831 ocp app prepare

Use OCP_DEBUG=1 to see the lane header in request/response logs:

OCP_DEBUG=1 OCP_PR_LANE=OCP-1831 ocp app prepare

ocp dev-server

Start the local development server for OCP applications.

The @optimizely/ocp-local-env package is automatically managed by this command:

• First run: Automatically installs the package globally
• Daily check: Checks for updates once per day and auto-upgrades when available
• No manual installation required

Options:

• -p, --port <port> - Port to run the server on (default: 3000)
• -c, --config <path> - Path to custom config file
• --path <path> - Path to the OCP app root directory (default: current directory)
• -v, --verbose - Enable verbose logging
• --no-open - Don't automatically open browser

Examples:

# Start server in current directory on default port
ocp dev-server start

# Start on custom port
ocp dev-server start -p 4000

# Start with specific app directory
ocp dev-server start --path /path/to/my-app

# Short version to start server
ocp dev