Upsun User Documentation

Authenticate the CLI using an API token

Try Upsun for 15 days
After that, enjoy the same, game-changing Upsun features for less with the First Project Incentive!ยน A monthly $19 perk!
ยนTerms and conditions apply
Activate your 15-day trial

You need to set up an API token to authenticate the Upsun CLI for any of the following tasks:

  • Running automated tasks on a CI system
  • Running automated tasks directly on app container, for example in a cron job

Before you begin Anchor to this heading

You might need the Upsun CLI to perform certain tasks. For example, you need the CLI to do the following:

1. Create a machine user Anchor to this heading

To safely run automated tasks, first create machine users. Each machine user has its own Upsun account associated with a unique email address. You can grant them restrictive access permissions to handle specific automated tasks. For security purposes, create a machine user for each type of task you want to automate.

To create a machine user, follow these steps:

  1. Run the following command using your machine user’s email address.

    upsun user:add  EMAIL_ADDRESS --role viewer --role development:contributor

    This sets your machine user as a viewer on your project and a contributor on development environments, with no access to other environment types. Note that you can further adjust user roles depending on your needs and each environment type.

  2. In the email invitation, click Create account.

  3. To create a Upsun account for the machine user, click Sign up and follow the instructions.

  1. Go to your project and click Settings.
  2. In the Project Settings menu, click Access.
  3. Click Add.
  4. Enter your machine user’s email address.
  5. For each environment type, assign a role to your machine user and click Save.

2. Create an API token Anchor to this heading

  1. Log in to the Console as your machine user.
  2. Open the user menu (your name or profile picture).
  3. Click My profile.
  4. Go to the API tokens tab and click Create API token.
  5. Enter a name for your API token and click Create API token.
  6. To copy the API token to your clipboard, click Copy. Note that after you close the API tokens tab, you can’t display the API token again.
  7. Store the API token somewhere secure on your computer.

Optional: check the validity of your API token Anchor to this heading

To check that your API token is valid, run the following command:

upsun auth:api-token-login

When prompted, enter your API token. You get output similar to this:

The API token is valid.
You are logged in.

For security reasons, rotate your API tokens regularly. When an API token is compromised, revoke it immediately.

3. Authenticate the CLI using your API token Anchor to this heading

After you create your API token, you can use it to do the following:

  • Allow a CI system to run automated tasks using the Upsun CLI.
  • Run automated tasks on an app container using the Upsun CLI, for example in a cron job.

Note that when running CLI commands in these cases, some operations might take time to complete. To avoid waiting for an operation to complete before moving on to the next one, use the --no-wait flag.

Authenticate in a CI system Anchor to this heading

You can allow your CI system to run automated tasks using the Upsun CLI. To do so, create an environment variable named UPSUN_CLI_TOKEN with your API token as its value. For more information, see your CI system’s official documentation.

To run SSH-based commands that aren’t specific to the Upsun CLI, see how to load the proper SSH certificate.

Authenticate in an environment Anchor to this heading

You can run automated tasks on an app container using the Upsun CLI. To do so, set your API token as a top-level environment variable.

Run the following command:

upsun variable:create \
   -e ENVIRONMENT_NAME \
   --level environment \
   --prefix 'env' \
   --name UPSUN_CLI_TOKEN \
   --sensitive true \
   --value 'API_TOKEN' \
   --inheritable false \
   --visible-build true \
   --no-interaction
  1. Open the environment where you want to add the variable.
  2. Click Settings.
  3. Click Variables.
  4. Click + Add variable.
  5. In the Variable name field, enter env:UPSUN_CLI_TOKEN.
  6. In the Value field, enter your API token.
  7. Make sure the Available at runtime and Sensitive variable options are selected.
  8. Click Add variable.

Then add a build hook to your app configuration to install the CLI as part of the build process.

.upsun/config.yaml
hooks:
    build: |
        set -e
        echo "Installing Upsun CLI"
        curl -fsSL https://raw.githubusercontent.com/platformsh/cli/main/installer.sh | bash

        echo "Testing Upsun CLI"
        upsun        

You can now call the CLI from within the shell on the app container or in a cron job.

To run SSH-based commands that aren’t specific to the Upsun CLI, see how to load the proper SSH certificate.

You can set up a cron job on a specific type of environment. For example, to run the update source operation on your production environment, use the following cron job:

crons:
    update:
       spec: '0 0 * * *'
        commands:
            start: |
                if [ "$PLATFORM_ENVIRONMENT_TYPE" = production ]; then
                   upsun backup:create --yes --no-wait
                   upsun source-operation:run update --no-wait --yes
                fi                

Use the CLI SSH certificate for non-CLI commands Anchor to this heading

When you set a UPSUN_CLI_TOKEN environment variable, the CLI authentication isn’t complete until your run a CLI command or load the CLI SSH certificate.

For example, after setting a UPSUN_CLI_TOKEN environment variable, you might need to run ssh, git, rsync, or scp commands before you run any CLI commands.

In this case, to ensure all your commands work, load the CLI SSH certificate first. To do so, run the following command:

upsun ssh-cert:load --no-interaction

Is this page helpful?