--> -->

Obtaining a token 

The Platform.sh CLI can also be used from CI services or other automation tools, and supports an API Token authentication option for that purpose.

An API token can be created through the management console. Go to the “User” page from your account drop-down, then select the “Account Settings” tab, then “API Tokens”.

Click the “Create an API Token” link.

API Token list

Enter a name to easily identify your token in the future, in case of multiple tokens (“CLI automated” is one example).

API Token name field

Once done, the newly created token will be displayed at the top of the page, and can be copied to the clipboard using the Copy button. After this, you will not be able to view the API token again.

After creating an API token

Now set that token in an environment variable named PLATFORMSH_CLI_TOKEN on the system where the CLI will run. Consult the documentation for your CI system to see how to do that.

Machine users 

For security reasons we recommend creating a dedicated machine user to run automation tasks such as taking backups, renewing SSL certificates or triggering source operations. We also strongly recommend creating a unique machine user for each project to be automated.

Like human users, every machine user account needs its own unique email address.

The machine user can be given a very restrictive set of permissions limited to just its needed tasks. Backups, for instance, require Admin access but no SSH key, while checking out code from a CI server to run tests on it would require an SSH key but only Reader access.

It will also show up in logs and activity streams as a separate entry from human users.

Consult the Users documentation for more information about the differences between access levels.

Install the CLI on a Platform.sh environment 

A common use case for an API token is to allow the Platform.sh CLI to be run on an app container, often via a cron hook. An API token is necessary for authentication, but the CLI will be able to auto-detect the current project and environment.

First, create a machine user (see above) that you invite to your project. Then, log in as that machine user to obtain an API token. Set this token as the top-level environment variable env:PLATFORMSH_CLI_TOKEN either through the management console or via the CLI, like so:

platform variable:create -e master --level environment --name env:PLATFORMSH_CLI_TOKEN --sensitive true --value 'your API token'

Second, add a build hook to your .platform.app.yaml file to download the CLI as part of the build process.

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). Because the API token is available, the CLI will now be able to run authenticated commands, acting as the user who created the token.

You can now call the CLI from within the shell on the app container, or via a cron hook. Note that if you want a cron to run only on the production environment you will need to wrap it in an if-check on the $PLATFORM_BRANCH variable, like so:

crons:
    backup:
        spec: '0 5 * * *'
        cmd: |
            if [ "$PLATFORM_BRANCH" = master ]; then
                platform backup:create --yes --no-wait
            fi