How to use the Platform.sh CLI from the web container

Goal

Have the Platform.SH CLI installed and authenticated in the web container.

Assumptions

  • Access to a project hosted on Platform.sh
  • Your project account has administrator rights
  • Knowledge on using the project web interface or Platform.sh CLI

Problems

Using the Platform.sh CLI directly from the web (application) container can be required to automate certain tasks, like renewing the SSL certificate or triggering a backup based on a cron schedule.

Due to the non-interactive deployment flow, using a regular username and password authentication is not possible. We will use token-based authentication to have the CLI installed and configured on each deployment.

Steps

1. Create an API token

Log into the accounts page and navigate to Account settings > API tokens page, available here. Click on Create API token. You will be prompted to enter your account password, then asked for the token name - enter a name to easily identify your token in the future, in case of multiple tokens (CLI_automated is one example).

Once done, the newly created token will be displayed at the top of the page and can be viewed later using the View link next to the token to retrieve the <token string>.

2. Add the token as an environment variable in the project

Once the API token is added as an environment variable in the project, it will be automatically detected and used by the CLI tool. After the installation is done, you should see the PLATFORMSH_CLI_TOKEN variable when running env.

  • Option 1: Using the web interface

    Open the project web interface and navigate to the environment in which you want to use the CLI, then click on Configure environment and go to the Variables tab. Add a variable named env:PLATFORMSH_CLI_TOKEN and set its value to the previously created token.

  • Option 2: Using the CLI

    If you have the CLI tool installed and configured, you can add the variable from the command line:

    platform variable:create -e <environment name> --level environment --name env:PLATFORMSH_CLI_TOKEN --sensitive true --value <token string>
    

    Replace the <environment name> and <token string> with the correct values for your use case.

3. Install the CLI tool in the application container

Once the variable has been added to the environment, it is required to download and install the CLI tool in a build hook.

Modify .platform.app.yaml in the project to include:

hooks:
    build: |
        curl -sS https://platform.sh/cli/installer | php

This will download the CLI to a known directory, .platformsh/bin , which will be added to the PATH at runtime (via the .environment file). Redeploy your environment and log into the application container with SSH, then run platform. You should see the welcome prompt and a list of your current projects.

Conclusion

Having the CLI tool set up in an environment opens up further automation possibilities - renewing the SSL certificate, triggering backups, etc.