# UCloud Sandbox CLI

Powerful command line tool for locally managing the sandbox life cycle, building templates, and performing operation and maintenance tasks.

UCloud Sandbox CLI is one of the most commonly used tools by developers. It not only helps you quickly initialize and build sandbox templates, but also allows you to view sandbox monitoring indicators in real time and perform batch operations.

## Installation Guide

### Uninstall the old npm-based CLI (optional)

In `v1.0` and previous versions, our CLI was built and distributed based on npm. In subsequent versions, we changed to manually executing the installation script.

If you have installed `ucloud-sandbox-cli` of `v1.0.x`, please use the following command to uninstall it first:

```bash
npm uninstall -g @ucloud-sdks/ucloud-sandbox-cli
```

If you have never installed `ucloud-sandbox-cli` before, or have not installed it using npm, you can skip this step.

### Install CLI

Install the CLI using the following command:

```bash
curl -sS https://raw.githubusercontent.com/ucloud/ucloud-sandbox-cli/main/install.sh | sh
```

The installation script will ask you to confirm the installation path (default is `/usr/local/bin`), directly enter and press Enter to confirm the installation, or you can also enter the installation path manually. Note: Please make sure the installation path is under your `$PATH` so that you can use the command line directly.

## Identity authentication and configuration

### Environment injection

The CLI will first read the API Key and region in the environment variables.

```bash
export UCLOUD_SANDBOX_API_KEY=your_api_key
export UCLOUD_SANDBOX_REGION=region
```

The API key can be obtained from [Key Management] (https://astraflow.ucloud.cn/modelverse/api-keys) on the Star Map platform.

For available regions, please refer to: [Switch Region](https://astraflow.ucloud.cn/docs/agent-sandbox/product/region).

### Persistent authentication

Configure persistent authentication:

```bash
# This command will ask you to enter the API key and select the default region
ucloud-sandbox-cli login
```

Delete persistent certificates:

```bash
ucloud-sandbox-cli logout
```

> When persistent authentication is in effect, you can still use environment variables to replace the API key and region.

### Switch region

Quickly select and switch regions:

```bash
# The currently available regions will be listed for you to choose from.
ucloud-sandbox-cli region
```

## Sandbox operation management

### Create and connect

Quickly create a sandbox and enter an interactive terminal:

```bash
# Create a sandbox using built-in templates
ucloud-sandbox-cli sandbox create [template]
# Abbreviation: ucloud-sandbox-cli sbx cr [template]
```

**Built-in templates:**

```bash
# Code Interpreter - comes with Python and data science libraries pre-installed
ucloud-sandbox-cli sandbox create code-interpreter-v1

# Desktop environment - supports graphical applications and browsers
ucloud-sandbox-cli sandbox create desktop

#Basic environment - lightweight Linux environment
ucloud-sandbox-cli sandbox create base
```

> After successful creation, the CLI will automatically connect to the terminal and you can execute commands like a local shell. Press `Ctrl+D` or enter `exit` to exit the connection (the sandbox continues to run).

### Connect to an existing sandbox

Reconnect to the running sandbox instance:

```bash
ucloud-sandbox-cli sandbox connect <sandbox-id>
# Abbreviation: ucloud-sandbox-cli sbx connect <sandbox-id>
```

### List query

View all active (running or suspended) sandbox instances under your name:

```bash
ucloud-sandbox-cli sandbox list
# Abbreviation: ucloud-sandbox-cli sandbox ls
```

### Forced shutdown (Kill)

Release sandbox resources immediately:

```bash
# Shut down specific ID
ucloud-sandbox-cli sandbox kill <sandbox-id>

# Shut down all active sandboxes
ucloud-sandbox-cli sandbox kill --all
```

### Monitoring

Real-time insight into the running status of the sandbox:

```bash
# View resource usage indicators (CPU/RAM/Disk)
ucloud-sandbox-cli sandbox metrics <sandbox-id>

# Continuously view indicators
ucloud-sandbox-cli sandbox metrics <sandbox-id> -w
```

## Template construction management

### Initialize template project

Create a standardized template development directory:

```bash
ucloud-sandbox-cli tpl init my-custom-env --cpu <cpu> --memory <memory>
cd my-custom-env
```

### Build template

In the `my-custom-env` above, you can see the `template.dockerfile` file. You need to edit this file and enter the `RUN` command to define the commands needed to build the template.

Build template:

```bash
ucloud-sandbox-cli tpl build my-custom-env
```

### Publish template

By default, templates can only be accessed by your current project. If you want others to be able to use the template, you need to make it public:

```bash
ucloud-sandbox-cli tpl publish <template-id>
```

Unpublicize:

```bash
ucloud-sandbox-cli tpl publish --unpublish <template-id>
```

## Typical workflow example

1. Prepare the environment: `ucloud-sandbox-cli login`
2. Create template: `ucloud-sandbox-cli template init` -> Write `Dockerfile`
3. Business access: use `Sandbox.create(template='my-agent-env')` in SDK
4. Resource recovery: `ucloud-sandbox-cli sandbox kill --all`