# UCloud Sandbox CLI
<subtitle>Powerful command-line tool for locally managing sandbox lifecycle, building templates, and executing operational tasks.</subtitle>

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 logs in real-time, monitor metrics, and perform batch operations.

## Installation Guide

### Install Using NPM
Ensure that Node.js is installed on your system.

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

After installation, you can verify success with `ucloud-sandbox-cli --help`.

---

## Authentication and Configuration

### Environment Injection
The CLI prioritizes reading the API Key from environment variables.

```bash
export AGENTBOX_API_KEY=your_api_key
```

### Login Operations
You can also complete login through interactive commands.

```bash
# Execute login, CLI will guide you to open browser to get Key
ucloud-sandbox-cli auth login

# View current login identity
ucloud-sandbox-cli auth info

# Log out current account
ucloud-sandbox-cli auth logout
```

---

## Sandbox Runtime Management

### Create and Connect
Quickly create a sandbox and enter an interactive terminal.

```bash
# Create sandbox using built-in template
ucloud-sandbox-cli sandbox create [template]
# Short form: ucloud-sandbox-cli sbx cr [template]
```

**Built-in Templates**:

```bash
# Code interpreter - Pre-installed Python and data science libraries
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 just like operating a local Shell. Press `Ctrl+D` or type `exit` to disconnect (sandbox continues running).

### Connect to Existing Sandbox
Reconnect to an already running sandbox instance.

```bash
ucloud-sandbox-cli sandbox connect <sandbox-id>
# Short form: ucloud-sandbox-cli sbx cn <sandbox-id>
```

### List Query
View all active (running or paused) sandbox instances under your account.

```bash
ucloud-sandbox-cli sandbox list
# Short form: ucloud-sandbox-cli sandbox ls
```

*   **State Filter**: `--state running,paused`
*   **Metadata Filter**: `--metadata key=value`
*   **Output Format**: Supports `pretty` (default) and `json`.

### Force Kill
Immediately release sandbox resources.

```bash
# Kill specific IDs
ucloud-sandbox-cli sandbox kill <id1> <id2>

# Kill all active sandboxes
ucloud-sandbox-cli sandbox kill --all
```

### Monitoring and Logs
Real-time insights into sandbox runtime status.

```bash
# View real-time logs
ucloud-sandbox-cli sandbox logs <id>

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

---

## Template Build Management

### Initialize Template Project
Create a standardized template development directory.

```bash
ucloud-sandbox-cli template init --name my-custom-env --language python-sync
```

### Build and Publish
Execute build in the template directory and push it to the UCloud Sandbox platform.

```bash
# Publish template version
ucloud-sandbox-cli template publish <template-id>
```

---

## Typical Workflow Example

1.  **Prepare Environment**: `ucloud-sandbox-cli auth login`
2.  **Create Template**: `ucloud-sandbox-cli template init` -> Write `Dockerfile`
4.  **Business Integration**: Use `Sandbox.create(template='my-agent-env')` in SDK
5.  **Resource Cleanup**: `ucloud-sandbox-cli sandbox kill --all`