授权

SenseCraft CLI 用访问密钥授权。一把密钥同时覆盖 SenseCraft Data、 SenseCraft AI 和 CodeCraft Hub。

两种授权方式任选其一，然后查看当前生效的配置：

方式	工作原理	适用场景
1. 浏览器授权 —— `auth init`	在浏览器里登录并批准访问，然后选择或新建一把密钥	首次配置，包括交给 AI 智能体配置
2. 导入访问密钥 —— `auth add`	在账号中心创建或找到密钥，再导入 CLI	复用某个已有密钥、脚本或 CI

两种方式都会在运行 CLI 的机器上保存一份生效的访问密钥配置，后续命令都复用它。

开始之前：账号与站点

CLI 不创建账号。要完成授权，你需要在目标站点上已有 Seeed 账号：

Global（国际） —— 在 sensecap.seeed.cc 或 sensecraft.seeed.cc 注册。
China（国内） —— 国内账号体系。

站点按配置逐份选择，并保存在配置文件里。在一个站点上创建的密钥在另一个站点不可用——拿 Global 的密钥配 China 的配置，就是密钥无效报错最常见的成因。

方式一：浏览器授权

用 auth init 通过浏览器登录，选择或新建访问密钥，全程不需要复制密钥本身。

使用 AI 智能体

当前版本的 CLI 支持把授权拆成几条命令。每一步都打印 JSON 后退出，所以智能体在没有可交互终端的情况下也能完成配置。本文描述的技能流程需要 CLI 0.4.3 及以上。

检查当前配置：执行 sensecraft-cli auth info。如果已经配置过凭据，沿用原来的站点和组织。
发起授权：
bash
```
sensecraft-cli auth init --site Global --no-wait
```
智能体保存返回的 device_code，把 verification_url 展示给你，然后等你在浏览器里登录并批准访问。批准后告诉智能体；它应当先把链接给你，再去轮询。
读取可用的密钥（浏览器批准之后）：
bash
```
sensecraft-cli auth init --device-code <device_code>
```
它会返回账号、组织，以及可用的密钥 ID、备注和权限。访问密钥本身不会打印出来。
保存选中的密钥，或者按任务需要的权限新建一把带备注的密钥：
bash
```
sensecraft-cli auth init --device-code <device_code> --key-id <access_id>
```
如果要新建密钥：
bash
```
sensecraft-cli auth init --device-code <device_code> --label <name> --access-level read-write
```
--access-level 接受 read-write 和 only-read。账号或权限上还有没定下来的选择，智能体会在对话里问你；密钥由 CLI 保存在本地。
检查已保存的配置：在继续执行云端命令前，先跑一次 sensecraft-cli auth info。

交互式向导

在可交互终端里直接用 CLI 时，启动向导：

sensecraft-cli auth init

步骤	会发生什么
1	选站点 —— Global（国际）或 China（国内）
2	申请设备码 —— CLI 从用户中心获取
3	在浏览器里批准 —— 它打印的链接里已经带了一次性验证码，验证码另外单独占一行
4	等待 —— 它自行轮询，你批准后自动继续
5	选密钥 —— 它列出你账号下的访问密钥；选一个，或新建一个并填写备注、选择只读/读写权限；配置会保存为生效状态

终端里大致是这样：

[3/5] Complete authorization in the browser

Copy the link below into your browser and authorize with the primary account:

  https://account.seeed.cc/device?user_code=ABCD-2345

  Verification code: ABCD-2345

The CLI will continue automatically after you complete browser authorization.

连接须知

链接可以跨设备。 在任何有浏览器的设备上打开都行；剩下的 CLI 步骤仍在发起授权的那台机器上完成。
只有向导需要可交互终端。 智能体用 --no-wait，然后用 --device-code。选了交互流程，就别让向导中途退出。
两种浏览器流程都能新建密钥。 不一定非得再去一趟账号中心；密钥导入见方式二。
验证码会过期（几分钟，时长由账号服务决定）。动作太慢的话 CLI 会以 context deadline exceeded 退出，什么也不保存——重新运行一次拿新验证码。
--sandbox 会在不发网络请求的情况下模拟整个流程，但仍可能写入一份模拟配置——介意的话，把 SENSECRAFT_CONFIG_FILE 指向一个临时文件。

方式二：导入访问密钥

用 auth add 导入一把指定的访问密钥。这种方式从账号中心开始，保存前会先通过 OpenAPI 校验密钥。

1. 创建或找到访问密钥

访问密钥在 Seeed 账号中心的访问密钥页面创建和管理。打开你所选站点的页面：

站点	页面
Global（国际）	account.seeed.cc/account/access-keys
China（国内）	account.seeed.cn/account/access-keys

SenseCraft 账号中心的访问密钥页面，突出显示创建密钥按钮

所选站点的访问密钥页面（演示数据）。点击创建密钥。

用主账号登录——子账号无法查看或管理访问密钥，页面只会显示权限提示，不会显示列表。可以直接用已有密钥，也可以新建一把：

点击创建密钥。
填一个以后能认出来的备注（可选，最多 64 个字符，例如 laptop-cli）。
选择权限：
- 只读 —— 列设备、读遥测、搜索应用和模型。做监控和只读的智能体流程够用了。
- 读写 —— 包含只读的全部能力，另外还能创建、更新、发布、删除、上传、部署和绑定。
在新密钥那一行复制两个值：
- 访问 ID —— 公开标识，CLI 里叫 Key ID（--key-id）。
- 访问密钥 —— 密钥（--access-key）。点眼睛图标显示后再复制。

创建访问密钥弹窗，包含备注和权限字段

给密钥填一个备注，再选择只读或读写。

密钥行中的访问 ID 和访问密钥

复制访问 ID；点开显示访问密钥后再复制。

创建弹窗里的权限默认是读写；流程只读数据时请选只读。只读密钥可以正常完成授权，但所有写命令都会报权限错误——那是密钥的权限级别问题，不是 CLI 的 bug。

密钥在这一页随时可以重新显示（点开再复制），所以要像密码一样对待，别当成只显示一次的东西。用编辑可以改备注或权限；需要让它停止工作时点禁用。这个页面没有删除按钮——禁用就是吊销开关，启用可以恢复。

2. 导入密钥

把密钥导入 CLI：

sensecraft-cli auth add \
  --key-id <Access ID> \
  --access-key <Access Key> \
  --site Global

--site 接受 Global（默认）和 China。选签发该密钥的站点： account.seeed.cc → --site Global，account.seeed.cn → --site China。校验时会调用该站点的 OpenAPI，所以另一个站点签发的密钥必然失败。

在交互式终端里，缺的值会提示你输入，而不是直接报错。只有当密钥值也是提示输入的情况下，才会追问站点——如果 --key-id 和 --access-key 都传了，只是没写 --site，CLI 会默认用 Global。站点有影响时就显式写上 --site。

Key ID: K1234567890
Access Key: <paste the Access Key>
Select the SenseCAP site to connect to
  1) Global (International)
  2) China (China site)
Enter number [1]:

输入的内容会回显在屏幕上，请在私密的终端里操作。用 --access-key 传参的形式还会留在 shell 历史和进程列表里，所以别把密钥粘到共享日志、截图或与智能体的对话记录中。

3. 确认导入

CLI 会用 view_organization 调用校验密钥，解析出你的组织 ID，保存配置并设为生效：

Verifying Access Key against OpenAPI ...
✓ Access Key verified
  Site: Global
  Organization ID: 12345
  Key ID: K1234567890

✓ Access config saved and set as active
  Config file: ~/.config/sensecraft-cli/sensecraft.json

auth add 只导入已有的密钥——它从不创建、轮换或删除密钥。校验失败时，配置文件里什么也不会写入。

auth info —— 查看凭据

两种方式都完成后，用下面的命令查看当前生效的配置：

sensecraft-cli auth info

以人类可读的形式（不是 JSON）打印正在使用的配置文件路径，以及站点、组织 ID、生效的访问 ID（显示为 Key ID）和创建时间。密钥本身从不打印。还没配置任何东西时，它会打印 No profiles configured yet. 并提示运行 auth init。这条命令只读本地配置，不会发 API 请求去校验保存的密钥。

不确定某条命令会打到哪个环境时，就先跑一下它——另见配置。

多份配置与切换

配置文件里可以同时保存多份访问密钥配置（文件结构见配置）。由其中一个指针决定哪份生效：

use_api —— 生效的访问 ID

每次成功的 auth add / auth init 都会写入自己的配置并设为生效。要切回之前那份配置，就对那把密钥/那个站点再跑一次 auth add（它会重新校验并重新激活已有的配置），或者直接改配置文件里的 use_api。这里故意没有“第一条生效” 这种兜底——指针没设是错误，不是靠猜。

删除凭据

没有 auth remove 命令——删除凭据是本地文件操作，需要你主动去做。

让密钥失效

打开访问密钥页面点禁用。在重新启用之前，用它发的 API 调用都会失败。禁用是可逆的，密钥仍留在列表里。要让这把凭据在所有用到它的地方都失效，就该走这一步——删掉本地配置只是让那台机器忘掉它。

清除全部（彻底退出登录）

删掉配置目录（位置取决于你的安装方式，见配置）：

rm -rf ~/.config/sensecraft-cli
  # Windows: Remove-Item -Recurse "$env:APPDATA\sensecraft-cli"

这会清掉该机器上保存的所有访问密钥、令牌和配置指针。

删除单个配置

打开 sensecraft.json，从 app_config_list 里删掉对应条目。如果删的是当前生效的那份，还要把 use_api 指向剩下的某个条目，或者清空它再重新跑 auth add / auth init。文件权限保持 0600——CLI 就是以这个权限原子写入的。

安全提示

配置文件以 0600 权限写入，方式是「临时文件 + 改名」的原子操作，所以写一半也不会损坏。密钥以明文存在这个文件里——要保护的是文件，不只是密钥。
别把 sensecraft.json 提交进仓库；如果为了 CI 在仓库里存了一份副本，请把密钥权限收窄到流水线真正需要的范围（能只读就只读）。
只读权限的密钥会让所有写命令报权限错误——这是密钥的权限级别，不是 CLI 的 bug。
AI 配置时，智能体执行 auth init --no-wait，等你在浏览器批准。别把密码、令牌和原始访问密钥留在对话和智能体日志里；见确认与安全。

版本说明

公开的 @seeed-studio/sensecraft-cli 版本对单把访问密钥同时支持 auth init （推荐）和 auth add，站点可选 Global 和 China。访问密钥不会过期，也不会刷新，所以没有 auth refresh 命令，也没有 --kind 参数。记住 China 站点仅支持 SenseCraft Data。