> ## Documentation Index
> Fetch the complete documentation index at: https://developer.upsun.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the Upsun CLI

> Run actions on your Upsun projects, select environments, execute remote commands, automate repetitive tasks, and enable tab autocompletion for the CLI.

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

List all available commands:

```bash theme={null}
upsun list
```

To get help on a specific command, use `help`:

```bash theme={null}
upsun help get
```

You get output similar to the following:

```bash theme={null}
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:

  ```bash theme={null}
  upsun environment:info --project=my-project --environment=staging
  ```

* With environment variables:

  ```bash theme={null}
  export PLATFORM_PROJECT=my-project;
  export PLATFORM_BRANCH=staging;
  upsun environment:info
  ```

In [multi-app](/docs/configure-apps/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:

```text theme={null}
[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:

```bash theme={null}
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](/docs/configure-apps/app-reference/single-runtime-image#dependencies) or a [hook](/docs/configure-apps/image-properties/hooks):

```bash theme={null}
upsun ssh -- COMMAND ARGUMENTS
```

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

```bash theme={null}
upsun ssh -- python my-script.py
```

Or to use [Drush](https://www.drush.org/latest/install/) to rebuild the cache on the `feature` environment,
run this command:

```bash theme={null}
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](https://github.com/upsun/cli/blob/main/legacy/README.md#customization).

### 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`:

```bash theme={null}
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:

<Tabs>
  <Tab title="Homebrew">
    Follow the [Homebrew documentation on shell completion](https://docs.brew.sh/Shell-Completion).
  </Tab>

  <Tab title="Manually">
    Add the following to your shell's startup (`.bashrc`, `.zshrc`, or the equivalent):

    ```bash theme={null}
    eval $(upsun completion)
    ```
  </Tab>
</Tabs>