Advanced usage

When running commands with VIP-CLI it is possible nest commands, loop commands, reference file input, write command output to a file, and other advanced operations.

Automation

VIP-CLI can be used for automating common flows and tasks both locally and in CI contexts (e.g., trigger a data sync on a schedule, run WP-CLI commands across multiple environments).

For a VIP-CLI command to be successfully run against an environment, it must be authenticated and run by a user account that has sufficient permissions to interact with that application. To set up automation for VIP-CLI commands, a user account should be created for a machine user and a config file created for authentication. Follow security best practices for all login credentials and authentication methods for the machine user.

A machine user can sign in to the VIP Dashboard with any of the supported login methods: a GitHub user account, a WordPress.com user account, or the organization’s Single Sign-On (SSO) configuration. It is recommended to use the login method that the organization already uses to manage its users, so that access for the machine user can be audited and revoked in the same way as access for other users.

1. With the preferred login method: Create a user account for the machine user with one of the supported login methods. The account must be registered with an email address that the machine user’s owner can access.
   • GitHub: Create a GitHub user account for the machine user.
   • WordPress.com: Create a WordPress.com user account for the machine user.
   • SSO: Add the machine user’s email address to the organization’s identity provider (IdP). This step is typically completed by the person who manages the organization’s IdP.
2. In the VIP Dashboard: Invite the machine user to the relevant WPVIP organization. The invitation must be sent to the same email address that was used to create the machine user’s account in step 1. Assign an Org role (and, if applicable, an App role) that provides the machine user with sufficient permissions to perform the planned automated actions.
3. Sign out of the VIP Dashboard.
4. In the email account of the machine user, open the invitation email for the VIP Dashboard and select the link to accept the invitation. This action will load the login page for the VIP Dashboard in the user’s default browser.
5. Sign in with the login method that was used to create the machine user’s account in step 1:
   • Sign in to the VIP Dashboard with GitHub or Sign in to the VIP Dashboard with WordPress.com. Both methods also require at least one VIP Authentication method to be set up for the machine user. The login method selected the first time the machine user signs in must be used each time afterward.
   • Sign in to the VIP Dashboard with SSO. Signing in with SSO does not require VIP Authentication.
6. Select the user avatar from the upper right-hand corner of the VIP Dashboard, then select the option labeled “Settings” from the dropdown menu to access the machine user’s User ID and a Personal Access Token.
7. On the local machine or in the CI server: Create a file named ~/.config/configstore/vip-go-cli.json. The content of the file should look similar to this example, with {VIP-USER-ID} replaced by the User ID value and {VIP-USER-TOKEN} replaced with the Personal Access Token:

{
  "vip-go-cli-uuid": "{VIP-USER-ID}",
  "vip-go-cli": "{VIP-USER-TOKEN}"
}

Example: Setting up a machine user with GitHub

In this example, the machine user signs in to the VIP Dashboard with a GitHub user account. Only the GitHub-specific steps are shown; all other steps are the same as above.

• Step 1, in GitHub: Create a GitHub user account for the machine user. In step 2, send the VIP Dashboard invitation to the same email address associated with the machine user’s GitHub account.
• Step 5: Select the button labeled “Sign in with GitHub“. Follow the prompts to authenticate with the machine user’s GitHub credentials and set up an additional VIP Authentication method for the machine user.

Looping

When running more complex WP-CLI commands such as loops, each reference to wp must use its own remote execution pattern. Because of the way that shell utilities handle stdin, commands like xargs may not work with WP-CLI output as expected. In these cases, it might be easier to write the commands to a file and execute it.

❌ This will not work:

vip @example-app.develop -- wp post list --fields=ID --format=csv --posts_per_page=5 | xargs -I % 'vip @example-app.develop -- wp post update % --post_category=NewCategory'

✅ This will work:

$ vip @example-app.develop -- wp post list --fields=ID --format=csv --posts_per_page=5 | xargs -I % sh -c 'echo "vip @example-app.develop -- wp post update % --post_category=NewCategory" >> commands.sh '
$ chmod +x commands.sh
$ ./commands.sh 

Nested commands

Each reference to wp in the inner and outer commands of a nested command structure must use its own remote execution pattern. Because of this, correct formatting of each command is critical for both commands to run successfully, and as expected.

In the examples below, a nested command is structured to include two WP-CLI commands with the following functions:

1. wp post list to retrieve a list of post IDs
2. wp post delete to delete the retrieved post IDs

❌ This will not work:

The format of this example nested command will not work as intended because the inner command (inside the $()) is referencing a version of wp (WP-CLI) on the user’s local machine, not on a VIP Platform environment.

$ vip @example-app.develop -- wp post delete $(wp post list --post_type='page' --format=ids --posts_per_page=100)
-bash: xyz: command not found

Running the command in the above format might only return a message indicating  wp does not exist locally. However, if the command is run from within a local development environment, it could have a more destructive outcome. Post IDs from the local environment could be retrieved and passed to the delete command, then run against the remote VIP Platform environment.

❌ This will not work:

When formatting a nested command, position all parts of the outer command before the inner command. In this example, both nested commands target a specific network site on a multisite. The format of this example nested command will not work as intended because the --url parameter of the outer command is positioned after the inner command:

$ vip @example-app.develop -- wp post delete $(vip @example-app.develop -- wp post list --post_type='page' --format=ids --url=example.com --posts_per_page=100) --url=example.com

✅ This will work:

vip @example-app.develop -- wp post delete --url=example.com $(vip @example-app.develop -- wp post list --post_type='page' --format=ids --url=example.com --posts_per_page=100)

In addition, for production environments, the --yes flag must be included in both the inner and outer commands to bypass the confirmation prompts:

vip @example-app.production --yes -- wp post delete --url=example.com $(vip @example-app.production --yes -- wp post list --post_type='page' --format=ids --url=example.com --posts_per_page=100)

Referencing a file input

To reference an input file in a command, commit the file to a publicly accessible location within the application’s GitHub repository, like the themes or plugins directories. The path of the file can then be referenced with a path similar to this example:
/var/www/wp-content/themes/my-theme/<file>.

Skipping command confirmation

When a command against a production environment is attempted, a prompt will appear in the terminal to confirm the action. To skip this confirmation step, pass the --yes (or -y) option before the -- command separator.

vip @example-app.production --yes -- wp option get siteurl

Bypassing the command confirmation is useful when a command is part of a custom script.

For nested commands run on a production environment, the --yes option is required in both inner and outer commands.

vip @example-app.production --yes -- wp post delete $(vip @example-app.production --yes -- wp post list --post_type='page' --format=ids)

System proxy support

A system proxy variable may be set in a local machine’s profile, such as:

SOCKS_PROXY
HTTPS_PROXY
HTTP_PROXY
NO_PROXY

By default, VIP-CLI does not use the system proxies set in a local machine’s profile. Passing VIP-CLI commands with theVIP_USE_SYSTEM_PROXY variable set to 1 will override this default behavior and honor the local machine’s profile settings.

The VIP_USE_SYSTEM_PROXY system proxy variable can be set per command:

VIP_USE_SYSTEM_PROXY=1 vip [command]

Or set in the profile used most often in the local machine’s terminal application.
For example: 

export VIP_USE_SYSTEM_PROXY=1

Writing command output to a local file

All WP-CLI commands are executed on a remote web server. If an output file for those operations is created on the remote server, that file cannot be retrieved.

Instead, the output for the file operations can be redirected and written to a specific file on the user’s local machine. In this example, the redirection operator (>) is used to direct the output for the WP-CLI command wp option getsiteurl to the local file file.txt:

vip @example-app.develop -- wp option get siteurl >  /path/to/local/file.txt

In this example, the WP-CLI command wp export includes the --stdout option to output all XML from the command to standard output, then the redirection operator (>) writes the output to the local file output.xml:

vip @example-app.develop --yes -- wp export --stdout > /Users/username/Desktop/output.xml

For best results, it is recommended that WP-CLI commands write output to the console using helpers like WP_CLI::line() and WP_CLI::log(). Read more about methods for saving command output to a file.