How do I use the Upsun CLI?

Overview

The Upsun command line interface will be your primary tool (along with the management console UI) for interacting with your projects and environments. Everything that can be done over the API can be done through the CLI once you install it.

To install, check the Upsun documentation for the latest instructions. Then authenticate the CLI with your account by running the command: upsun login

To view a full list of available commands, run: upsun list

Helpful Commands

Below are some of the most common and useful commands you'll use when managing your Upsun projects. Replace PROJECT_ID and ENVIRONMENT_ID with your specific project and branch details.

• Grab an application's configuration: upsun app:config-get -p PROJECT_ID

• Create a backup of an environment: upsun backup:create -p PROJECT_ID -e ENVIRONMENT_ID

• Dump an environment's database: upsun db:dump -p PROJECT_ID -e ENVIRONMENT_ID

• Start a SQL session with a database container: upsun db:sql -p PROJECT_ID -e ENVIRONMENT_ID

• Add a domain to a project: upsun domain:add -p PROJECT_ID

• Activate an environment post-push: upsun environment:activate -p PROJECT_ID -e ENVIRONMENT_ID

• Read an environment's logs: upsun environment:logs -p PROJECT_ID -e ENVIRONMENT_ID

• Redeploy an environment: upsun environment:redeploy -p PROJECT_ID -e ENVIRONMENT_ID

• Synchronize data from the parent environment: upsun environment:synchronize data -p PROJECT_ID -e ENVIRONMENT_ID

• Synchronize both code AND data from the parent environment: upsun environment:synchronize code data -p PROJECT_ID -e ENVIRONMENT_ID

• Add an environment-level variable: upsun variable:create -l environment --name=FOO --value=BAR -p PROJECT_ID -e ENVIRONMENT_ID

• Add a project-level variable: upsun variable:create -l project --name=FOO --value=BAR -p PROJECT_ID

Direct API Access

There are many more useful commands you can use to interact with and troubleshoot environments and projects on Upsun. One of the most powerful is project:curl, which gives you access to broader API requests available via our API documentation.

For example, activating an environment using this command would look like: upsun project:curl -p PROJECT_ID /environments/ENVIRONMENT_ID/activate

It’s generally recommended to use the standard Upsun CLI commands directly, but project:curl is incredibly useful when you need a raw JSON response or need to access a specific API endpoint not yet wrapped in a dedicated command.