Configure your development environment

Develop, manage, and publish an Optimizely Connect Platform (OCP) app using the OCP command-line interface (CLI). You can configure the OCP CLI on either a Mac/Linux machine or a Windows machine. Skip directly to the section that pertains to your environment.

Prerequisites

• An OCP developer account.
• The API key from your invitation email.
• Node.js 18 JavaScript runtime environment. Find your platform-specific installer here, or use your preferred Node version manager for the install.
• Yarn; find global install instructions for Yarn here. If you are on Windows, we suggest installing Yarn through Corepack, as described here.

  🚧

  Important

  OCP requires Yarn 1 (classic). Make sure you have the supported version installed (yarn -v).

• The OCP CLI requires Git to build an app. Find global install instructions for Git here.

  📘

  Note

  If you are not planning to build an app, you can skip the Git install.

Configure the OCP CLI for Mac/Linux

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

   Shell

   mkdir ~/.ocp (home dir)
   

2. Using the API key you received during onboarding, create the credentials file in the .ocp directory:

   Shell

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

3. Run the following Yarn command to install the OCP CLI:

   Shell

   yarn global add @optimizely/ocp-cli
   

4. Set your PATH variable:

   Shell

   export PATH="$(yarn global bin):$PATH"
   

Configure the OCP CLI for Windows

📘

Note

The following instructions are for PowerShell.

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

   PowerShell

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

2. Using the API key you received during onboarding, create the credentials file in the .ocp directory:

   PowerShell

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

3. Run the following Yarn command to install the OCP CLI:

   PowerShell

   yarn global add @optimizely/ocp-cli
   

4. Ensure the value returned from yarn global bin is on your path:

   PowerShell

   yarn global bin
   

   📘

   Note

   The output should look similar to the following:

   PowerShell

   C:\Users\[YOUR_USERNAME]\AppData\Local\Yarn\bin
   

   If it does not, follow these instructions to set your Path variable.

Test your OCP CLI configuration

Verify your OCP CLI configuration by running the following command:

ocp accounts whoami

The results should 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: []

OCP CLI help command

Commands are grouped into namespaces:

$ ocp -h
Usage: ocp <command>

Namespaces: (`<namespace>` -h, --help for additional help)
  accounts       
  app            
  availability   
  directory      
  env            
  jobs           
  review

Run the help command, -h or --help, to list commands in a namespace, for 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, for 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-previous-app-env-values   Use app env values (.env file) from the previous version of the app. Any values in local .env file will be ignored
  --bumpDevVersion, --bump-dev-version                       Bump dev version before building. Allows quickly testing dev versions

OCP CLI commands

The table below lists all available OCP CLI commands with their parameters and descriptions.

Additional flags/options for OCP CLI commands

You can append various flags/options for some of the OCP CLI commands, listed below.

ocp app logs

• --tail – Tails the logs.
• --appId
• --buildId
• --appVersion
• --trackerId
• --jobId
• --installId
• --from – A start time as an ISO string, an epoch timestamp, or relative string (for example, 5m for 5 minutes). Default is 24h.
• --to – An end time as an ISO string, an epoch timestamp, or relative string (for example, 5m for 5 minutes).
• --search – String to search for in log messages. Can be specified multiple times.
• --availability or -a – The availability region that will be targeted (default is US).

ocp app getLogLevel or ocp app get-log-level

• --trackerId – Specific Tracker ID to filter by.
• --availability – The availability region that will be targeted (default is US).

ocp app setLogLevel or ocp app set-log-level

• --trackerId – Specific Tracker ID to filter by.
• --timeToLive – Expiration period for the log level as a relative string (for example, 5m for 5 minutes). Default is 2 hours (2h).
• --availability – The availability region that will be targeted (default is US).

ocp app prepare

• --noProgress or --no-progress – Do not display any progress indicators.
• --upgradeDeps or --upgrade-deps – Automatically update dependencies.
• --publish – Automatically publish if the upload is successful.
• --usePreviousAppEnvValues or --use-previous-app-env-values – Use app env values (.env file) from the previous version of the app. Any values in the local .env file will be ignored.
• --bumpDevVersion or --bump-dev-version – Bump dev version before building. Allows you to quickly test dev versions.

ocp app validate

• --noProgress or --no-progress – Do not display any progress indicators.
• --upgradeDeps or --upgrade-deps – Automatically update dependencies.

ocp directory unpublish

• --force or -f
• --noProgress or --no-progress
• --availability or -a – The availability region that will be targeted (default is US).

ocp directory publish

• --noProgress or --no-progress

ocp directory list

• --allStatuses – Includes all statuses. The stopped status is not included by default.
• --availability or -a – The availability region that will be targeted (default is US).

ocp directory upgrade

• --toVersion or -v – The desired version (for example, 1.0.0).
• --availability or -a – The availability region that will be targeted (default is US).

ocp jobs list

• --version – Specific versions to filter by.
• --trackerId – Specific Tracker IDs to filter by.
• --function – Specific job function to filter by.
• --status – Specific job status to filter by. Possible values: PENDING, SCHEDULED, RUNNING, COMPLETE, ERROR, TERMINATED.
• --minDuration – Show jobs that have been running longer than the given duration (for example, 5m = 5 minutes).
• --sortBy – Column to sort the jobs by. Possible values: id, function, trackerId, status, error, createdAt, triggeredAt, scheduledAt, terminatedAt, updatedAt, duration. The default column to sort by is updatedAt.
• --sortDirection – Sort resulting jobs in ascending or descending order. Possible values: asc or desc. The default sort direction is asc.
• --limit – Number of jobs to list. The default is 50.
• --columns – Columns to display. Possible values: id, version, function, trackerId, trigger, status, error, createdAt, triggeredAt, scheduledAt, terminatedAt, updatedAt, duration. The default columns are id, version, function, trackerId, status, updatedAt.
• --from – A start time as an ISO string, an epoch timestamp, or relative string (for example, 5m = 5 minutes). The default time value is 24h.
• --to – An end time as an ISO string, an epoch timestamp, or relative string (for example, 5m = 5 minutes).
• --availability or -a – The availability region that will be targeted (default is US).

ocp jobs trigger

• --parameters – Parameters to pass to the job.
• --availability or -a – The availability region that will be targeted (default is US).