Use the Upsun CLI

The Upsun CLI lets you manage projects, run remote commands, and automate tasks directly from your terminal. List all available commands:

upsun list

To get help on a specific command, use help:

upsun help get

You get output similar to the following:

Command: project:get
Aliases: get
Description: Clone a project locally

Usage:
 upsun get [-e|--environment ENVIRONMENT] [--depth DEPTH] [--build] [-p|--project PROJECT] [--host HOST] [-i|--identity-file IDENTITY-FILE] [--] [<project>] [<directory>]

Arguments:
  project                            The project ID
  directory                          The directory to clone to. Defaults to the project title

Select the right project and environment

If you run a command that requires a specific project and environment from an empty or unassociated directory, the CLI prompts you to select them. If your working directory is inside a local checkout of your project, the CLI detects your project and environment automatically. Specify the project and environment in either of two ways:

As arguments for the command:

upsun environment:info --project=my-project --environment=staging

With environment variables:

export PLATFORM_PROJECT=my-project;
export PLATFORM_BRANCH=staging;
upsun environment:info

In multi-app projects, this also applies to selecting the app (use the PLATFORM_APPLICATION_NAME environment variable).

RootNotFoundException

If you clone a project with Git directly instead of upsun get, the CLI might not be able to identify the project. Running a CLI command from inside that directory can produce this error:

[RootNotFoundException] Project root not found. This can only be run from inside a project directory.

This error means the CLI cannot determine the project. To fix it, run:

upsun project:set-remote --project PROJECT_ID

Replace PROJECT_ID with the ID of your project. Find your project ID in the Console, or run upsun projects to list all accessible projects.

Choose between the CLI and Git commands

CLI commands in the environment namespace overlap with Git commands but offer more options. For example, upsun push supports --activate (to activate an environment before pushing) and --no-wait (to continue working without waiting for the push to complete). CLI commands don’t require a configured Git remote — a project ID is sufficient. For example, upsun merge only merges code between remote environments. Your local codebase is not affected, and you don’t need the code checked out locally.

Run commands on your container

To run Upsun CLI commands against your container, you can use any command added in dependencies or a hook:

upsun ssh -- COMMAND ARGUMENTS

For example, to run a specific Python script named my-script.py on your current environment, run the following command:

upsun ssh -- python my-script.py

Or to use Drush to rebuild the cache on the feature environment, run this command:

upsun ssh -e feature -- drush -y cache-rebuild

Customize the CLI

Customize CLI behavior using a configuration file (~/.upsun-cli/config.yaml) or environment variables. For details, see the customization instructions on GitHub.

Automate repetitive tasks

Use the CLI in scripts to automate repetitive tasks like syncing files locally. To bypass confirmation prompts, set UPSUN_CLI_NO_INTERACTION=1. For example, to sync all mount points for your app myapp:

export PLATFORM_PROJECT=my-project;
export PLATFORM_BRANCH=main;
export UPSUN_CLI_NO_INTERACTION=1;
upsun mount:download --all --app myapp --target local-backup

Autocomplete commands

The CLI provides tab autocompletion for commands, options, and some values (your projects, valid regions). To enable autocompletion, follow these steps:

Homebrew
Manually

Follow the Homebrew documentation on shell completion.

Add the following to your shell’s startup (.bashrc, .zshrc, or the equivalent):

eval $(upsun completion)

Getting started

Reference

Select the right project and environment

RootNotFoundException

Choose between the CLI and Git commands

Run commands on your container

Customize the CLI

Automate repetitive tasks

Autocomplete commands

​Select the right project and environment

​RootNotFoundException

​Choose between the CLI and Git commands

​Run commands on your container

​Customize the CLI

​Automate repetitive tasks

​Autocomplete commands

Select the right project and environment

RootNotFoundException

Choose between the CLI and Git commands

Run commands on your container

Customize the CLI

Automate repetitive tasks

Autocomplete commands