---
title: "Sine Cloud 命令行"
description: "通过设备授权登录，发现 Agents、Box、Powers 与 Gateway 资源，调用全部已发布操作，并用第一方 sinecloud CLI 恢复结果未知的写请求。"
image: "https://docs.sinecloud.dev/opengraph.png"
---

> 完整文档索引： https://docs.sinecloud.dev/zh-CN/llms.txt

# Sine Cloud 命令行

`sinecloud` 是面向同一套客户 API 的第一方命令行客户端。它通过设备授权创建组织 API 密钥，不需要把密钥粘进终端；命令由已发布 OpenAPI 规范生成。

## 安装与登录

公开分发渠道发布前，CLI 仍以仓库内 Node 包运行：

```bash
pnpm cli:build
node apps/cli/dist/cli.mjs auth login
```

`auth login` 会打印批准地址和短代码。在浏览器批准后选择组织，CLI 会把最小 scope 的密钥保存到 `$XDG_CONFIG_HOME/sinecloud/config.json`（目录 `0700`、文件 `0600`）。会话令牌只在登录过程中使用，不落盘。

## 发现资源

```bash
sinecloud agents list --json                 # 当前密钥可见的 Agents 实例
sinecloud box list --json                    # 组织或项目内的 Box 资源
sinecloud powers catalog list --json
sinecloud gateway models list --json
```

把返回的 ID 用于对应操作的生成命令：

```bash
sinecloud agents capabilities list --instance INSTANCE_ID --json
sinecloud agents sessions list --instance INSTANCE_ID --json
sinecloud box workspace files list --box-id BOX_ID --path /workspace --json
sinecloud box executions create --box-id BOX_ID \
  --body '{"executionId":"<uuid>","command":"pwd","cwd":"/workspace","timeoutMs":10000}' --wait --yes
```

## Powers 报价与 BYOK

```bash
sinecloud powers endpoints quote --endpoint-id ENDPOINT_ID --json > quote.json
sinecloud powers runs create --quote quote.json \
  --body '{"endpointId":"ENDPOINT_ID","input":{}}' --yes
```

`--quote` 同时固定 Endpoint 版本与报价版本。价格变化时服务端返回 `409 priceChanged` 且未派发；重新读取报价后发起新运行。省略 `--connection-id` 使用平台执行；自有连接走组织 BYOK。

BYOK 凭据只从标准输入读取，不进入命令行参数：

```bash
printf '%s' '{"apiKey":"…"}' | sinecloud powers connections replace \
  --connection-id CONNECTION_ID \
  --body '{"providerId":"…","authProfileId":"…","authType":"api_key"}' \
  --credentials-stdin --yes
```

## 恢复、限制与退出码

变更类请求在派发前把身份写入本地；结果未知时退出 `9` 并提示 `--resume <id>`，重新提交完全相同的请求体即可复用原身份。不要用新标识重试非幂等请求。

本地预检上限：Agents 256 KiB、Powers 64 KiB、Box 命令 1 MiB、Box 文件写 16 MiB、Gateway 1 MiB。付费操作在 TTY 询问，非 TTY 必须 `--yes`。

| 码 | 含义 |
| --- | --- |
| 0 | 成功 |
| 2 | 用法错误 |
| 3 | 认证失败 |
| 4 | 权限、scope 或项目不足 |
| 5 | 未找到 |
| 6 | 冲突或价格/版本变化 |
| 7 | 限流 |
| 8 | 未准入 |
| 9 | 结果未知，用 `--resume` 恢复 |
| 10 | 只读失败或上游不可用 |

来源: https://docs.sinecloud.dev/zh-CN/cli/index.mdx