Skip to main content

Setting up credentials

The WPCS CLI enables users to communicate with the WPCS API. This means that you will have to provide API credentials so the API can authenticate you. After following the steps to retrieve API credentials for your product, you can set up the CLI.

The CLI makes use of environment variables to configure the API calls. Specifically, it uses three variables: the API key, the API secret and the API region. These variables can be supplied in multiple ways.

Supplying the API key and secret​

The CLI reads out the environment variables WPCS_API_KEY and WPCS_DEFAULT_API_KEY for the API key. The WPCS_API_KEY environment variable has a higher priority than WPCS_DEFAULT_API_KEY. This means that if you have both set, the CLI will use the value defined for WPCS_API_KEY.

The API secret is alike. The CLI reads out WPCS_API_SECRET or WPCS_DEFAULT_API_SECRET, with the same prioritization. If you have set WPCS_API_SECRET, any value for WPCS_DEFAULT_API_SECRET will be ignored.

It is not possible to pass the API key or secret to the CLI via flags. It is generally considered insecure to pass sensitive data through the terminal. As most terminals keep records of executed commands, your sensitive API credentials are then suddenly logged without encryption. Therefore, it is only possible to configure the API key and secret via environment variables.

This method is mostly very useful when using the WPCS CLI in a CI/CD pipeline.

Supplying the region​

The region of your product is also required to use the WPCS API. Of course, the region of your product is not sensitive data, so you can pass it via the --region flag. However, it is also possible to use the WPCS_REGION or WPCS_DEFAULT_REGION environment variables. The same prioritization applies as above, the 'default' is only used if WPCS_REGION is not defined.

Environment files​

The CLI can read environment files in several ways: the current working directory, the default location or a supplied path.

Environment variable file contents​

However you choose to let the WPCS CLI find your environment variables file, the contents of the file should always be similar to this:

WPCS_DEFAULT_REGION=eu1
WPCS_DEFAULT_API_KEY=your-api-key
WPCS_DEFAULT_API_SECRET=your-api-secret

Current working directory​

The first and probably the method to use on a laptop or machine used for local development is to put an environment variables file in the current working directory. Create a file called .wpcs-cli.env in, for example, the root directory of the WordPress installation you are working on. Make sure the file has all the required API credentials. When it is set up, you can run WPCS CLI commands from the root of your WordPress installation and it will connect you to the WPCS API using those credentials. This is especially useful if you are working on multiple Products in WPCS and need different local WordPress installations to connect to different WPCS Products.

Default location​

The default location is the credentials file placed in the user's home directoy, under $HOME/.wpcs/credentials.cli.env for POSIX systems. For Windows, the user's USERPROFILE is used: $USERPROFILE/.wpcs/credentials.cli.env. Do make sure to name the environment variable file exactly credentials.cli.env and place it in the .wpcs folder.

Supplying a path​

The other option is to supply an environment variables file via a flag. You can add the --env-file flag to any command to use an environment file in a custom location. For example: npx @wpcs.io/cli tenants list --env-file ./configurations/.my-custom-config.env.