x-optimizely-cli is a command line tool giving developers the power to build Optimizely X experiments, link pages to experiments, create variations, and push your experiments with variations and pages intact to Optimizely's X platform using the Optimizely v2 REST API directly from your terminal.
x-optimizely-cli was developed by roboboogie to increase our experimentation velocity. We like to build tests using our editors and using git for version control. This makes it much simpler, faster and more familiar. Thanks to FunnelEnvy for giving us such a great product in optimizely-cli for Optimizely Classic from which we based this tool on. We also want to thank Web Marketing ROI for releasing optimizely-x-cli which was a great reference from which our final tool has been put together.
Bonus: If you already are using optimizely-cli, you can run x-optimizely-cli in the same directory.
Get ready to experiment.
You'll need to have node.js installed locally to run
xoptcli. To view variations locally you can use either the Tampermonkey or Greasemonkey extensions. We've included a script at the end to help running your tests locally with the aformentioned extensions.
This will install x-optimizely-cli on your system and give you access to the
xoptcli executable globally.
npm i -g @teamroboboogie/x-optimizely-cli
Create a directory to host your Optimizely project locally and change directories.
Lets you view available commands.
xoptcli or xoptcli -h, -help
-h, -help- view available commands
an API token, then run this command. This will create a hidden directory labeled
your API token.
xoptcli set-token <token>
<token>- API token generated through Optimizely.
xoptcli set-token 1:7robo847SYSwow9384GS-Fr488GJslkjLKUIJNkjlkjis_ioi_2
Initializes a new Optimizely X project in the directory you are currently in, creating a project.json file with the
xoptcli init <project_id>
<project_id>– The project ID from optimizely where you want to host experiments in this directory. Required.
xoptcli init 1740413223
Creates a local experiment with an "Original" variation that has a starting weight or traffic allocation of 100%.
Optimizely uses a scale of 10000, so that's what you will see in original/variation.json.
xoptcli experiment <folder> <name> <page_ids>
<folder>– The name of the local directory for the new experiment. Required.
<name>– The name of the new experiment you will see in Optimizely X. Required.
<page_ids>- As many page IDs, but at least one, which to attach to your experiment. Page IDs must be created through Optimizely X before adding them to your experiment. Required.
xoptcli experiment "robo-test" "Test3:Funnel" "10198685817,10248681248"
Creates a local variation and builds the necessary source files. Setting
xoptcli variation <experiment> <folder> <name> <traffic_allocation>
<experiment>- The directory for this experiment. Required.
<folder>- The name of the local folder for the new variation. Required.
<name>– The name of the new variation you will see in Optimizely X. Required.
<traffic_allocation>- The weight or traffic allocation allotted to the variation with a total
xoptcli variation roboboogie-test/ "variation-1" "v:1 variation directory name" "5000"
Creates or udates an experiment and all variation to your Optimizely X project. On create, it will assign a default
metric "Overall Revenue", because it is required by the API to have a metric. With the
-m option you
can push metrics with experiments. This is really helpful for adding groups of metrics at once, like checkout funnel
xoptcli push-experiment <path>
-m, --metrics– push with metrics (will overwrite remote metrics).
<path>- the path to the directory of the experiment you want to push.
xoptcli push-experiment roboboogie-test/
Pulls a specific experiment to a specific file, allowing you to sync whats on Optimizely X with your local project folder. As of right now we do not support multiple versions of code for different pages in the same experiment (it's even confusing to type that out!). We do support pulling metrics though!
xoptcli pull-experiment <folder> <experiment_id>
-m, --metrics– pull with metrics (syncing with local metrics). Unfortunately the experiment api does not return the name of a metric. If it exists locally it will retain the name, but otherwise it may be preferable to search for the event_id within your "pull-pages -m" output.
<folder>- name of folder where you want put the experiment, will write over experiment. Required.
<experiment_id>- id of experiment you want pulled.
xoptcli pull-experiment "my-great-experiment" 11124913096
Pulls all pages for a project into a single json file with the option for metrics attached to those pages. This is mostly for reference.
xoptcli pull-pages [options] <file>
<file>- name of file where you want to store the json dump. Required.
xoptcli pull-pages -m pages.json
Host a variation locally. Add
xoptcli=activate as a parameter after you've run the command below and
your preferred extension will inject the CSS and JS of the variation you choose. Or point your browser at http(s)://localhost:8080 (default port) for usage info. If you
are using the -s option, your browser may need you to give it permission to load unsafe scripts before script
injection can take place. You can do that by going to http(s)://localhost:8080 and toggeling the advanced section and then clicking
the "proceed to unsafe localhost" option.
xoptcli host [option] <path> [port]
<path>- the path to the directory of the variation you want to host. Required.
<port>- the port where you want to host the server. Optional: Default is 8080.
xoptcli host -s roboboogie-test/variation-1/ 8082
If you're using a mac and have a bash_profile, you can get access to tab completion by running the following:
xoptcli completion >> ~/.bash_profile && source ~/.bash_profile
This will add code to your bash profile to make the commands available and then tell bash to source your newly updated profile. If you are using a mac and don't have a bash profile, check out this one that updates your git prompts, letting you know when you need to push code by changing the colors when git is out of date with your current branch.
As promised, here is an injection script for local development from FunnelEnvy that you can add to Tampermonkey or Greasemonkey:
// @name X-Optimizely-CLI Injection Script
// @author FunnelEnvy w/slight robo modifications
// @homepage https://teamroboboogie.com/xoptcli
// @source https://github.com/teamroboboogie/x-optimizely-cli
// @namespace xoptcli
// @description Inject local experiment JS / CSS into a Chrome page for development
// @include /xoptcli=activate/
// @require http://ajax.googleapis.com/ajax/libs/jquery/1.6.4/jquery.js
var scriptElement = document.createElement('script');
scriptElement.src = '//localhost:8080/variation.js';
var stylesheet = document.createElement('link');
stylesheet.rel = 'stylesheet';
stylesheet.href = '//localhost:8080/variation.css';