@seacloudai/seacloud-cli 0.0.16 → 0.0.17

package/README.md

@@ -31,7 +31,7 @@
 - **Proxy-based image generation**: Call sync image-generation models through a compatible proxy service, with optional asset URL output.
 - **Task tracking**: Poll task status and print result URLs or full JSON responses.
 - **SkillHub integration**: Search, install, and configure agent skills from SeaCloud SkillHub.
-- **Agent-friendly UX**: Supports `--dry-run`, JSON output, stable command shapes, and copy-pasteable examples.
+- **Agent-friendly UX**: Supports `--dry-run`, JSON output, output limits, actionable errors, stable command shapes, and copy-pasteable examples.
 
 ## Install
 
@@ -139,6 +139,17 @@ seacloud skills add some-skill
 seacloud skills config --show
 ```
 
+### Manage sandboxes
+
+```bash
+seacloud sandbox create base
+seacloud sandbox create base --no-connect --wait
+seacloud sandbox list --state running,paused --format json
+seacloud sandbox exec <sandbox_id> ls -la
+seacloud sandbox connect <sandbox_id>
+seacloud sandbox kill <sandbox_id>
+```
+
 ## Commands
 
 ### `seacloud auth`
@@ -200,6 +211,73 @@ seacloud images generate --prompt="a blue cat" --output json
 seacloud images generate --prompt="a blue cat" --output url
 ```
 
+### `seacloud sandbox`
+
+Core sandbox commands follow the E2B CLI shape:
+
+```bash
+seacloud sandbox create [template]
+seacloud sandbox create base --no-connect --wait
+seacloud sandbox list --state running,paused --metadata app=agent --limit 10 --next-token <token>
+seacloud sandbox exec <sandbox_id> "python --version"
+seacloud sandbox exec --background <sandbox_id> "sleep 60 && echo done"
+seacloud sandbox exec --cwd /workspace --user root --env NODE_ENV=production <sandbox_id> node app.js
+seacloud sandbox connect <sandbox_id> --shell bash
+seacloud sandbox kill <sandbox_id>
+seacloud sandbox kill --all --state running,paused
+seacloud sandbox metrics <sandbox_id>
+seacloud sandbox metrics <sandbox_id_1> <sandbox_id_2> --output json
+```
+
+SeaCloud sandbox API features exposed by the SDKs are also available:
+
+```bash
+seacloud sandbox create base --auto-resume --allow-internet-access=false --allow-out 1.1.1.1 --volume-mount cache:/cache
+seacloud sandbox network update <sandbox_id> --allow-public-traffic=true --deny-out 10.0.0.0/8
+seacloud sandbox logs <sandbox_id> --limit 100 --direction backward
+seacloud sandbox pause <sandbox_id>
+seacloud sandbox timeout <sandbox_id> --seconds 3600
+seacloud sandbox refresh <sandbox_id> --duration 300
+
+seacloud sandbox volume create cache
+seacloud sandbox volume list
+seacloud sandbox volume get <volume_id>
+seacloud sandbox volume delete <volume_id>
+
+seacloud sandbox events --type sandbox.lifecycle.created
+seacloud sandbox webhook create --name lifecycle --url https://example.com/webhook --secret whsec_... --event sandbox.lifecycle.created --max-attempts 5 --delay-seconds 1,5,30
+seacloud sandbox webhook update <webhook_id> --enabled=false
+seacloud sandbox webhook deliveries --status failed
+seacloud sandbox webhook replay <delivery_id>
+
+seacloud sandbox team list
+seacloud sandbox team metrics <team_id> --start 1710000000 --end 1710003600
+seacloud sandbox observability
+```
+
+`seacloud sandbox create <template>` follows E2B's interactive behavior when run in a terminal: it creates the sandbox, connects a shell, and kills the sandbox when the shell exits. Use `--no-connect` or `--output json` for automation.
+
+### `seacloud template`
+
+Template commands provide the E2B migration surface for local template projects and build operations:
+
+```bash
+seacloud template init --language typescript --name my-template
+seacloud template migrate --language python --name my-template
+seacloud template build my-template --dockerfile Dockerfile
+seacloud template build my-template --image python:3.13 --cpu-count 2 --memory-mb 2048 --tag v1
+seacloud template build my-template --from-template base --no-wait
+seacloud template list --format json
+seacloud template get my-template
+seacloud template builds my-template
+seacloud template status <template_id> <build_id>
+seacloud template logs <template_id> <build_id> --limit 100
+seacloud template tags assign my-template:v1 production stable
+seacloud template tags list my-template
+seacloud template tags remove my-template staging
+seacloud template delete my-template
+```
+
 ### `seacloud version`
 
 ```bash
@@ -209,14 +287,21 @@ seacloud version
 ## Output and Automation
 
 - Use `--output json` where supported for machine-readable responses.
+- Use `--format json` on sandbox/template commands for E2B-compatible output flag naming.
 - Use `--output url` on task commands to print only result URLs.
 - Set `SEACLOUD_FOLKOS_PROXY_URL` to the root of your proxy service when using `seacloud images generate` or sync image models through `seacloud run`.
-- Use global `--dry-run` to inspect execution without sending requests.
+- Set `SEACLOUD_SANDBOX_URL` or `SEACLOUD_BASE_URL` to the sandbox gateway API root. A gateway root such as `https://sandbox-gateway.cloud.seaart.ai` is normalized to `/api/v1`.
+- Sandbox and template commands read API keys from the normal SeaCloud config, `SEACLOUD_API_KEY`, or E2B-compatible aliases `E2B_API_KEY` / `E2B_ACCESS_TOKEN`.
+- Set `SEACLOUD_NAMESPACE_ID`, `SEACLOUD_USER_ID`, and `SEACLOUD_PROJECT_ID` when calling scoped sandbox APIs such as events, webhooks, volumes, teams, or metrics.
+- Use global `--dry-run` before write/delete/replay operations. Dry-run output shows the method, path, body/query, destructive status, and the next step.
+- Use `--limit`, `--next-token`, `--cursor`, or `--offset` on list/log/event commands to keep responses small.
+- Parameter errors include the invalid field, what is wrong, and a suggested command or flag to fix it.
 
 Example:
 
 ```bash
 seacloud --dry-run run seedance_2_0 --param prompt=test
+seacloud --dry-run sandbox webhook create --name lifecycle --url https://example.com/webhook --secret whsec_...
 ```
 
 ## Release

package/README.zh.md

@@ -31,7 +31,7 @@
 - **代理生图**：通过兼容的代理服务调用同步生图模型，并可选择输出资产 URL。
 - **任务追踪**：轮询任务状态，输出结果 URL 或完整 JSON。
 - **SkillHub 集成**：搜索、安装和配置 SeaCloud SkillHub 技能。
-- **Agent 友好**：支持 `--dry-run`、JSON 输出、稳定命令结构和可直接复制的示例。
+- **Agent 友好**：支持 `--dry-run`、JSON 输出、输出限量、可操作错误、稳定命令结构和可直接复制的示例。
 
 ## 安装
 
@@ -139,6 +139,17 @@ seacloud skills add some-skill
 seacloud skills config --show
 ```
 
+### 管理沙箱
+
+```bash
+seacloud sandbox create base
+seacloud sandbox create base --no-connect --wait
+seacloud sandbox list --state running,paused --format json
+seacloud sandbox exec <sandbox_id> ls -la
+seacloud sandbox connect <sandbox_id>
+seacloud sandbox kill <sandbox_id>
+```
+
 ## 命令概览
 
 ### `seacloud auth`
@@ -200,6 +211,73 @@ seacloud images generate --prompt="一只蓝色猫" --output json
 seacloud images generate --prompt="一只蓝色猫" --output url
 ```
 
+### `seacloud sandbox`
+
+核心沙箱命令对齐 E2B CLI 的命令形态：
+
+```bash
+seacloud sandbox create [template]
+seacloud sandbox create base --no-connect --wait
+seacloud sandbox list --state running,paused --metadata app=agent --limit 10 --next-token <token>
+seacloud sandbox exec <sandbox_id> "python --version"
+seacloud sandbox exec --background <sandbox_id> "sleep 60 && echo done"
+seacloud sandbox exec --cwd /workspace --user root --env NODE_ENV=production <sandbox_id> node app.js
+seacloud sandbox connect <sandbox_id> --shell bash
+seacloud sandbox kill <sandbox_id>
+seacloud sandbox kill --all --state running,paused
+seacloud sandbox metrics <sandbox_id>
+seacloud sandbox metrics <sandbox_id_1> <sandbox_id_2> --output json
+```
+
+三端 SDK 已支持的 SeaCloud 沙箱能力也已暴露到 CLI：
+
+```bash
+seacloud sandbox create base --auto-resume --allow-internet-access=false --allow-out 1.1.1.1 --volume-mount cache:/cache
+seacloud sandbox network update <sandbox_id> --allow-public-traffic=true --deny-out 10.0.0.0/8
+seacloud sandbox logs <sandbox_id> --limit 100 --direction backward
+seacloud sandbox pause <sandbox_id>
+seacloud sandbox timeout <sandbox_id> --seconds 3600
+seacloud sandbox refresh <sandbox_id> --duration 300
+
+seacloud sandbox volume create cache
+seacloud sandbox volume list
+seacloud sandbox volume get <volume_id>
+seacloud sandbox volume delete <volume_id>
+
+seacloud sandbox events --type sandbox.lifecycle.created
+seacloud sandbox webhook create --name lifecycle --url https://example.com/webhook --secret whsec_... --event sandbox.lifecycle.created --max-attempts 5 --delay-seconds 1,5,30
+seacloud sandbox webhook update <webhook_id> --enabled=false
+seacloud sandbox webhook deliveries --status failed
+seacloud sandbox webhook replay <delivery_id>
+
+seacloud sandbox team list
+seacloud sandbox team metrics <team_id> --start 1710000000 --end 1710003600
+seacloud sandbox observability
+```
+
+`seacloud sandbox create <template>` 在交互终端中会按 E2B 习惯工作：创建沙箱、连接 shell、退出 shell 后删除沙箱。脚本化创建请使用 `--no-connect` 或 `--output json`。
+
+### `seacloud template`
+
+模板命令提供 E2B 迁移所需的本地模板项目和构建操作：
+
+```bash
+seacloud template init --language typescript --name my-template
+seacloud template migrate --language python --name my-template
+seacloud template build my-template --dockerfile Dockerfile
+seacloud template build my-template --image python:3.13 --cpu-count 2 --memory-mb 2048 --tag v1
+seacloud template build my-template --from-template base --no-wait
+seacloud template list --format json
+seacloud template get my-template
+seacloud template builds my-template
+seacloud template status <template_id> <build_id>
+seacloud template logs <template_id> <build_id> --limit 100
+seacloud template tags assign my-template:v1 production stable
+seacloud template tags list my-template
+seacloud template tags remove my-template staging
+seacloud template delete my-template
+```
+
 ### `seacloud version`
 
 ```bash
@@ -209,14 +287,21 @@ seacloud version
 ## 自动化与输出
 
 - 在支持的命令上使用 `--output json` 获取机器可读输出。
+- sandbox/template 命令也支持 `--format json`，用于兼容 E2B 的输出参数命名。
 - 在任务命令上使用 `--output url` 只打印结果 URL。
 - 使用 `seacloud images generate` 或通过 `seacloud run` 调用同步生图模型时，请把 `SEACLOUD_FOLKOS_PROXY_URL` 设置为你的代理服务根地址。
-- 使用全局 `--dry-run` 在不发请求的前提下检查执行内容。
+- 使用 `SEACLOUD_SANDBOX_URL` 或 `SEACLOUD_BASE_URL` 配置沙箱网关 API 根地址；如果填的是 `https://sandbox-gateway.cloud.seaart.ai` 这种网关根地址，CLI 会自动补 `/api/v1`。
+- sandbox/template 命令会从 SeaCloud 本地配置、`SEACLOUD_API_KEY`，或 E2B 兼容别名 `E2B_API_KEY` / `E2B_ACCESS_TOKEN` 读取 API key。
+- 调用 events、webhooks、volumes、teams、metrics 等带作用域的沙箱 API 时，可设置 `SEACLOUD_NAMESPACE_ID`、`SEACLOUD_USER_ID`、`SEACLOUD_PROJECT_ID`。
+- 写入、删除、重放这类操作前先使用全局 `--dry-run`。dry-run 输出会展示 method、path、body/query、是否破坏性操作和下一步提示。
+- list/log/event 类命令使用 `--limit`、`--next-token`、`--cursor` 或 `--offset` 控制输出量。
+- 参数错误会包含哪个字段出错、错在哪里，以及建议执行的修复命令或参数。
 
 示例：
 
 ```bash
 seacloud --dry-run run seedance_2_0 --param prompt=test
+seacloud --dry-run sandbox webhook create --name lifecycle --url https://example.com/webhook --secret whsec_...
 ```
 
 ## 发布说明

package/npm-bundles/SHA256SUMS

@@ -1,5 +1,5 @@
-e29352a3140bf792c92961bb5ec4313a10d5ea8f2466e72530bdb67191065b70  seacloud_0.0.16_darwin_amd64.tar.gz
-3b2eedb91e996d440795c91641e0b0f54317973931571456ec91cc0db6d8de70  seacloud_0.0.16_darwin_arm64.tar.gz
-4fec616eb90c23115dbd3e8de32307bbb85c379cb425a1661c9b552d03acbbb0  seacloud_0.0.16_linux_amd64.tar.gz
-3147fea1c5bb64e7387d5f9d7e00fe8ec7637d32c2230e1a46399e3f447d5b72  seacloud_0.0.16_linux_arm64.tar.gz
-bbf6b18cb3ac52d9df6acaf421cc8e3885e202cb17ad0d36c3024b1b8432b718  seacloud_0.0.16_windows_amd64.zip
+fb833dbbd5b0c91f54c1b5a794e98868a4756188f08637a09b772dca5745169f  seacloud_0.0.17_darwin_amd64.tar.gz
+e703913f834c7ab5921b3cd6fe71db6270b4bef65b8f8001f0e5795fa032379f  seacloud_0.0.17_darwin_arm64.tar.gz
+79d4be934d7fcbd174e91f5e4664924dc62de99db8b84ffaebf5295d6297a20b  seacloud_0.0.17_linux_amd64.tar.gz
+7b4d2b986a60d31961a5ced0fb535f74ec0ca64af42d10a29ad35c26d202ad7d  seacloud_0.0.17_linux_arm64.tar.gz
+50b2c2296e70510680d8a74cbe0916ddde2e9fedafd2bea4c0a042c9cb823eed  seacloud_0.0.17_windows_amd64.zip

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seacloudai/seacloud-cli",
-  "version": "0.0.16",
+  "version": "0.0.17",
   "description": "npm installer wrapper for the SeaCloud CLI binary",
   "license": "MIT",
   "publishConfig": {