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. triggering Data Sync on a schedule; running WP-CLI commands across all environments). To do this, the authentication prompt can be bypassed by creating a config file.

When setting up automation for VIP-CLI commands, it is recommended to create a bot/machine user and generate a token for that machine user account.

1. Generate a new token in the User settings panel of the VIP Dashboard (select “Generate Token“).
2. Create a file named ~/.config/configstore/vip-go-cli.json.
3. Add the following code to vip-go-cli.json, replacing VIP-USER-TOKEN with the token retrieved from the VIP Dashboard.

{
  "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.