README
VIP (Internal) CLI
Internal CLI Tools for VIP Go Sandboxes and the internal API.
Installation
Make sure you have an open connection to the Automattic proxy and are able to tunnel local traffic to port 8080.
npm i -g @automattic/vip-go-internal-cli
vipgo config set PROXY=socks://127.0.0.1:8080
vipgo login
Using an Ad blocker?
Make sure you allow HTTPS traffic to pixel.wp.com
- the domain the CLI connects to in order to track command usage - otherwise your output will be polluted with the following error:
✕ Unexpected error: Please contact the Platform team with the following error:
Error: connect ECONNREFUSED 0.0.0.0:443
at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1146:16)
E.g. on PiHole, use sudo pihole -w pixel.wp.com
.
Usage
Show available commands:
vipgo --help
You can append --help
to any sub-command to see options and sub-sub-commands.
Development
To start hacking:
- Clone this repository.
cd
to the cloned directory.- Run
npm install
to install dependencies. - Hack the code.
- Build your changes using
npm run build
. - Manually test your changes by calling
node build/bin/vipgo.js {related-command}
.
Test
To lint and execute the full test suite:
npm run test
Connecting to local VIP Go API
Note: changing this setting will also affect the installed npm package, and not only your cloned repository. Remember to clear this setting when you are done testing!
Testing in production is not good, so if you need to test against a locally running copy of GOOP, you can prepend a specific env variable to all commands as follows:
VIP_API_URL=http://localhost:2999 ./build/bin/vipgo.js sandbox list
To avoid typing every time, save the variable in your config file:
./build/bin/vipgo.js config set VIP_API_URL=http://localhost:2999
Then re-login with a user id and token valid for your local GOOP installation. By default, the local GOOP development environment will accept user id 1 with an empty API token.
Note 1: Your development version will use the same config as the globally installed module and any changes to the config will impact that.
Note 2: You can use npm link
to link your development copy with your globally installed version to simplify development.
Tracks
We track all vipgo
commands with the vip_internal_cli_command_triggered
Tracks event
While developing locally, the Tracks event name changes to vip_internal_cli_local_command_triggered
In addition to native Tracks parameters, we also track the command name, sub command name, command parameters and GOOP User ID.
Note that sensitive command parameters can be redacted by adding to the TRACKS_UNTRACKED_COMMAND_OPTIONS
array in the src/constants.js
file.
Publishing a New Release
Major / Minor Versions
npm run publish-please --dry-run
to ensure there are no publishing blockers- Note: if some tests are failing, chances are your CLI points to the local GOOP! This will break nock!
- Set the version:
npm version patch
for non-breaking changes/bugfixes and small updatesnpm version minor
if there are some new features or breaking changes
git push --tags
npm run publish-please
- Edit the release in Github to include a description of the changes. You can use this script to generate the changelog (instructions in its README, but it should be pretty straightforward).
- Manually bump the version in
package.json
to the next patch and append-dev
git push
- Post on the VIP Go P2 with details about the new release.
- Bump the spec files for the PHP images in the wpvip-dockerfiles repo (example) to update on sandboxes and work with VIP Systems to get it released.
Note: doing the steps 3 and 4 can help with debugging in case someone is running the dev version (via vipgo -V
).
Patch Version
For a critical fix (or a small number of fixes), we can git checkout
the last release and add/or cherry-pick some changes.
Then bump the version number with npm version patch
and npm publish
. This is especially nice if there are already some bigger changes in the trunk branch and you don’t want to push a normal release.
It is necessary to update the Rolling Release Doc even if it is a patch version bump.
Caveats
- We don’t publish the
src
directory because it's not used and just makes builds larger (skipped via.npmignore
). - Microsoft Windows users will require Windows 10 or later with a Linux Subsystem installed.
- When debugging the Site Details commands, in order to make the commands work when pointing to local GOOP and API Gateway, please override the Proxy like in the example given below:
VIP_API_URL=http://localhost:2999 API_GATEWAY_URL=http://localhost:3999 DISABLE_SDS_PROXY=true ./build/bin/vipgo.js site details get <siteId>