Installation

Requirements

Item	Requirement
Node.js	≥ 16 (18 / 20 LTS recommended) — only needed for the npm installer
Platform	macOS Intel/Apple Silicon · Linux x64/arm64 · Windows x64/arm64
Network	npm registry, plus the binary download host (Aliyun OSS by default)
Optional	Go toolchain, only when building from source

The npm package is a thin wrapper: it downloads a pre-built, static Go binary for your platform on first use and registers the sensecraft-cli command. The binary itself has no runtime dependencies.

Install (recommended)

Run the installer with npx:

bash

npx @seeed-studio/sensecraft-cli install

This will:

1. Download the binary matching your platform and the package version.
2. Register sensecraft-cli globally on your PATH.
3. If no credentials exist yet and you are in an interactive terminal, offer the browser setup wizard. To use an Access Key created in the account center instead, run auth add after installing (see Authentication).

Verify:

bash

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

Windows

powershell

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

• The command is installed as sensecraft-cli.cmd under npm prefix -g.
• If a new terminal can’t find it, add that directory to the system PATH.
• PowerShell 5+ or Windows Terminal is recommended; Git Bash usually works too.
• Some antivirus tools quarantine the first-downloaded sensecraft-cli.exe — allow-list the install directory and reinstall if that happens.

Run without installing

Every command works through npx, at the cost of a small startup check each time:

bash

npx @seeed-studio/sensecraft-cli device list

Install a specific version

bash

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

Binary downloads are addressed as {RELEASE_BASE}/v{version}/sensecraft-cli-{os}-{arch}[.exe], with the default release base https://sensecraft-statics.oss-us-east-1.aliyuncs.com/static/bin/sensecraft-cli.

Shell completion (optional)

The CLI ships Cobra completions — tab-complete commands and flags:

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

Open a new shell to load it. Windows: sensecraft-cli completion powershell prints the script — add it to your $PROFILE.

sensecraft-cli: command not found

Confirm the install ran (npx @seeed-studio/sensecraft-cli install), then check whether the npm global bin directory is on your PATH. The installer tells you which directory it needs — when your PATH is missing it, its output ends with this hint:

Plain Text

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

(“If you cannot run sensecraft-cli directly, add the following directory to PATH.”)

Adding a directory to PATH means putting one export line in your shell’s profile file, so every new terminal starts with it.

macOS / Linux — zsh shown; use ~/.bashrc instead if your shell is bash (echo $SHELL says which):

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 prints npm’s global directory and the command lives in its bin subdirectory — the same directory the hint shows.

Windows (PowerShell) — set it for your user, then open a new terminal:

powershell

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

Then open a new terminal — PATH changes only apply to shells started afterwards — and run sensecraft-cli --version again.

Upgrade

bash

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

The installer compares the version stamp of the downloaded binary (vendor/.version) with the npm package version: if they match it reuses the cached binary, otherwise it downloads the matching one. Confirm with sensecraft-cli --version.

If the version refuses to change, clear both the package and the npm cache and reinstall:

bash

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

Uninstall

bash

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

The binary under the package’s vendor/ directory is removed with it. Credentials live outside the package — remove them separately if you are done with the CLI on that machine:

bash

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

Removing the config deletes the locally stored Access Keys and tokens — see Authentication for what is stored and how to remove individual profiles.

Offline, intranet and custom mirrors

Use a locally built dist/

Build all platform binaries, then point the installer at them:

bash

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

Point at a mirror

bash

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

The mirror must reproduce the release layout:

Plain Text

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

Skip the download entirely

bash

export SENSECRAFT_CLI_SKIP_DOWNLOAD=1

Installation fails if vendor/ does not already contain a binary matching the current version — useful in CI to guarantee no network access.

Verify a checksum

If a SHA256 is published for the release:

bash

export SENSECRAFT_CLI_SHA256="<hex digest>"

The install fails when the downloaded bytes don’t match.

Proxies

The installer honors the standard Node/system proxy variables:

bash

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

Build from source

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

One behavioral difference to know: a binary you built yourself reads its config from the current directory by default, while the npm-installed CLI reads ~/.config/sensecraft-cli/ — see Configuration for how to unify them with SENSECRAFT_CLI_PATH.

Verify the installation

Sandbox commands return sample JSON without touching the network — but they still need a profile to exist, so bootstrap a simulated one first (writes a fake config, no account needed):

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

(If a command has no sandbox mode it simply reports an error — that’s expected.)