安装

环境要求

项目	要求
Node.js	≥ 16（推荐 18 / 20 LTS）—— 只有 npm 安装器需要
平台	macOS Intel/Apple Silicon · Linux x64/arm64 · Windows x64/arm64
网络	npm registry，以及二进制下载地址（默认阿里云 OSS）
可选	Go 工具链，仅从源码构建时需要

npm 包只是一层薄封装：首次使用时，它会下载对应平台的预编译静态 Go 二进制， 并注册 sensecraft-cli 命令。二进制本身没有运行时依赖。

安装（推荐）

用 npx 运行安装器：

bash

npx @seeed-studio/sensecraft-cli install

它会：

1. 下载与你的平台和包版本匹配的二进制。
2. 把 sensecraft-cli 注册到全局 PATH。
3. 如果本机还没有凭据，且当前是可交互终端，会提示进入浏览器配置向导。想改用 账号中心创建的访问密钥，安装完成后执行 auth add（见 授权）。

验证：

bash

sensecraft-cli --version
sensecraft-cli --help

Windows

powershell

node -v
npx @seeed-studio/sensecraft-cli install
sensecraft-cli --version

• 命令会以 sensecraft-cli.cmd 的形式装在 npm prefix -g 指向的目录下。
• 如果新开的终端找不到它，就把该目录加到系统 PATH 里。
• 推荐用 PowerShell 5+ 或 Windows Terminal；Git Bash 一般也能用。
• 有些杀毒软件会把首次下载的 sensecraft-cli.exe 隔离——遇到这种情况， 把安装目录加入白名单再重装。

不安装直接运行

所有命令都能通过 npx 运行，代价是每次启动多一次小检查：

bash

npx @seeed-studio/sensecraft-cli device list

安装指定版本

bash

npm install -g @seeed-studio/sensecraft-cli@0.1.4

二进制下载地址的格式是 {RELEASE_BASE}/v{version}/sensecraft-cli-{os}-{arch}[.exe]，默认的 RELEASE_BASE 是 https://sensecraft-statics.oss-us-east-1.aliyuncs.com/static/bin/sensecraft-cli。

命令补全（可选）

CLI 自带 Cobra 补全脚本——可以 Tab 补全命令和参数：

bash

  # zsh (macOS: pick a directory on your $fpath)
sensecraft-cli completion zsh > "${fpath[1]}/_sensecraft-cli"

  # bash (Linux)
sensecraft-cli completion bash | sudo tee /etc/bash_completion.d/sensecraft-cli

  # fish
sensecraft-cli completion fish > ~/.config/fish/completions/sensecraft-cli.fish

重开一个 shell 才会加载。Windows：sensecraft-cli completion powershell 会打印脚本——把它加进 $PROFILE。

sensecraft-cli: command not found

先确认安装确实执行过（npx @seeed-studio/sensecraft-cli install），再检查 npm 全局 bin 目录是否在 PATH 里。安装器会告诉你它需要哪个目录——如果你的 PATH 里没有，它的输出末尾会给出这样的提示：

Plain Text

提示: 若无法直接运行 sensecraft-cli，请将以下目录加入 PATH:
  /Users/you/.npm-global/bin

（提示的意思是：若无法直接运行 sensecraft-cli，请将上面的目录加入 PATH。）

把目录加进 PATH，就是在 shell 的 profile 文件里写一行 export，让每个新开的 终端都带上它。

macOS / Linux —— 以 zsh 为例；如果你的 shell 是 bash，改用 ~/.bashrc （echo $SHELL 可以看出来）：

bash

npm prefix -g
  # common values:
  #   macOS (Homebrew Node): /opt/homebrew  → bin dir /opt/homebrew/bin
  #   Linux: ~/.npm-global  → bin dir ~/.npm-global/bin

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc   # or ~/.bashrc
source ~/.zshrc

npm prefix -g 打印 npm 的全局目录，命令就装在它的 bin 子目录里——也就是 上面提示里显示的那个目录。

Windows（PowerShell） —— 为当前用户设置，然后重开一个终端：

powershell

[Environment]::SetEnvironmentVariable("Path", $env:Path + ";" + (npm prefix -g) + "\bin", "User")

然后打开一个新终端——PATH 的修改只对之后启动的 shell 生效——再跑一次 sensecraft-cli --version。

升级

bash

npm install -g @seeed-studio/sensecraft-cli@latest

安装器会把下载到的二进制里的版本标记（vendor/.version）与 npm 包版本比对： 一致就复用缓存的二进制，不一致就下载匹配的那一个。用 sensecraft-cli --version 确认。

如果版本死活不更新，把包和 npm 缓存一起清掉再重装：

bash

npm uninstall -g @seeed-studio/sensecraft-cli
npm cache clean --force
npx @seeed-studio/sensecraft-cli@<target-version> install
sensecraft-cli --version

卸载

bash

npm uninstall -g @seeed-studio/sensecraft-cli

包里 vendor/ 目录下的二进制会一并删除。凭据存在包的外面——如果你在这台 机器上不再用 CLI，需要单独删除：

bash

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

删除配置会清掉本机保存的访问密钥和令牌——存了哪些东西、怎么删除单个配置，见 授权。

离线、内网与自建镜像

使用本地构建的 dist/

先构建所有平台的二进制，再让安装器指向它们：

bash

./script/build.sh                       # in a clone of the source repo
export SENSECRAFT_CLI_LOCAL_DIST="$PWD/dist"
npx @seeed-studio/sensecraft-cli install

指向镜像

bash

export SENSECRAFT_CLI_RELEASE_BASE="https://your-mirror.example.com/sensecraft-cli"
npx @seeed-studio/sensecraft-cli install

镜像必须复刻发布目录的结构：

Plain Text

…/sensecraft-cli/v0.1.4/sensecraft-cli-darwin-arm64
…/sensecraft-cli/v0.1.4/sensecraft-cli-linux-amd64
…

完全跳过下载

bash

export SENSECRAFT_CLI_SKIP_DOWNLOAD=1

如果 vendor/ 里还没有与当前版本匹配的二进制，安装会直接失败——在 CI 里用它 来确保完全不访问网络。

校验和

如果这个版本公布了 SHA256：

bash

export SENSECRAFT_CLI_SHA256="<hex digest>"

下载的字节对不上时，安装会失败。

代理

安装器遵循 Node/系统标准的代理环境变量：

bash

export HTTPS_PROXY=http://proxy.example.com:8080
export HTTP_PROXY=http://proxy.example.com:8080

从源码构建

bash

git clone https://github.com/Seeed-Solution/sensecraft-cli.git
cd sensecraft-cli

go build -o sensecraft-cli .
./sensecraft-cli --version

  # all 6 platform binaries, into dist/
./script/build.sh

有一个行为差异需要知道：自己构建的二进制默认从当前目录读配置，而通过 npm 安装的 CLI 读的是 ~/.config/sensecraft-cli/——怎么用 SENSECRAFT_CLI_PATH 把两者统一，见配置。

验证安装

沙箱命令会返回示例 JSON，不访问网络——但它们仍然要求已经存在配置，所以先造 一份模拟配置（写入假配置，不需要账号）：

bash

sensecraft-cli auth init --sandbox   # accept the defaults, ~20 seconds
sensecraft-cli device list --sandbox
sensecraft-cli group list --sandbox
sensecraft-cli model constants --sandbox
sensecraft-cli app list --mine --sandbox

（某个命令如果没有沙箱模式，它只会报错——这是正常现象。）