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.

1. In GitHub: Create a GitHub user account for the machine user.
2. In the VIP Dashboard: Invite the machine user to the relevant WPVIP organization. Be sure to send the invitation to the same email address associated with the machine user’s GitHub account. 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. 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.
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}"
}

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.develop --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.develop --yes -- wp post delete $(vip @example-app.develop --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 file

All WP-CLI commands are run on a remote web server. File operations initiated by a command will occur on the remote server, with no way to retrieve the file.

It is recommended to write the output to the console first using helpers like WP_CLI::line() and WP_CLI::log(), then redirect the output to a specific file:

vip @example-app.develop --yes -- wp option get siteurl > output.txt

See more detailed guidance on saving command output to a file.