Installation

Voraussetzungen

Punkt	Anforderung
Node.js	≥ 16 (18 / 20 LTS empfohlen) — nur für den npm-Installer nötig
Plattform	macOS Intel/Apple Silicon · Linux x64/arm64 · Windows x64/arm64
Netzwerk	npm-Registry sowie der Download-Host für das Binary (standardmäßig Aliyun OSS)
Optional	Go-Toolchain, nur beim Bauen aus dem Quellcode

Das npm-Paket ist ein schlanker Wrapper: Bei der ersten Verwendung lädt es ein vorkompiliertes, statisches Go-Binary für Ihre Plattform herunter und registriert den Befehl sensecraft-cli. Das Binary selbst hat keine Laufzeitabhängigkeiten.

Installation (empfohlen)

Führen Sie den Installer mit npx aus:

bash

npx @seeed-studio/sensecraft-cli install

Damit wird:

1. Das Binary passend zu Ihrer Plattform und der Paketversion heruntergeladen.
2. sensecraft-cli global in Ihrem PATH registriert.
3. Wenn noch keine Zugangsdaten existieren und Sie in einem interaktiven Terminal arbeiten, wird der Assistent für die Einrichtung im Browser angeboten. Wenn Sie stattdessen einen im Account-Center angelegten Zugangsschlüssel verwenden möchten, führen Sie nach der Installation auth add aus (siehe Authentifizierung).

Prüfen Sie:

bash

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

Windows

powershell

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

• Der Befehl wird als sensecraft-cli.cmd unter npm prefix -g installiert.
• Wenn ein neues Terminal ihn nicht findet, fügen Sie dieses Verzeichnis dem systemweiten PATH hinzu.
• Empfohlen sind PowerShell 5+ oder Windows Terminal; Git Bash funktioniert meist ebenfalls.
• Manche Antivirenprogramme stellen das zuerst heruntergeladene sensecraft-cli.exe in Quarantäne — setzen Sie das Installationsverzeichnis auf die Positivliste und installieren Sie in diesem Fall erneut.

Ohne Installation ausführen

Jeder Befehl funktioniert über npx, um den Preis einer kleinen Startprüfung bei jedem Aufruf:

bash

npx @seeed-studio/sensecraft-cli device list

Bestimmte Version installieren

bash

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

Binary-Downloads werden als {RELEASE_BASE}/v{version}/sensecraft-cli-{os}-{arch}[.exe] adressiert, mit der Standard-Release-Basis https://sensecraft-statics.oss-us-east-1.aliyuncs.com/static/bin/sensecraft-cli.

Shell-Completion (optional)

Die CLI bringt Cobra-Completions mit — Befehle und Flags per Tab vervollständigen:

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

Öffnen Sie eine neue Shell, um die Completion zu laden. Windows: sensecraft-cli completion powershell gibt das Skript aus — fügen Sie es Ihrer $PROFILE hinzu.

sensecraft-cli: command not found

Prüfen Sie, ob die Installation gelaufen ist (npx @seeed-studio/sensecraft-cli install), und sehen Sie dann nach, ob das globale npm-Bin-Verzeichnis in Ihrem PATH liegt. Der Installer nennt Ihnen das Verzeichnis, das er braucht — fehlt es in Ihrem PATH, endet seine Ausgabe mit diesem Hinweis:

Plain Text

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

(„Wenn Sie sensecraft-cli nicht direkt ausführen können, nehmen Sie das folgende Verzeichnis in den PATH auf.“)

Ein Verzeichnis zum PATH hinzuzufügen bedeutet, eine export-Zeile in die Profildatei Ihrer Shell zu schreiben, sodass jedes neue Terminal sie von Anfang an mitbringt.

macOS / Linux — gezeigt wird zsh; verwenden Sie stattdessen ~/.bashrc, wenn Ihre Shell bash ist (echo $SHELL sagt es Ihnen):

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 gibt das globale Verzeichnis von npm aus, und der Befehl liegt in dessen Unterverzeichnis bin — dasselbe Verzeichnis, das der Hinweis anzeigt.

Windows (PowerShell) — legen Sie es für Ihren Benutzer fest und öffnen Sie dann ein neues Terminal:

powershell

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

Öffnen Sie danach ein neues Terminal — PATH-Änderungen gelten nur für Shells, die später gestartet wurden — und führen Sie sensecraft-cli --version erneut aus.

Aktualisieren

bash

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

Der Installer vergleicht den Versionsstempel des heruntergeladenen Binaries (vendor/.version) mit der npm-Paketversion: Stimmen beide überein, verwendet er das zwischengespeicherte Binary erneut, andernfalls lädt er das passende. Bestätigen Sie mit sensecraft-cli --version.

Wenn die Version sich nicht ändern will, leeren Sie Paket und npm-Cache und installieren Sie neu:

bash

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

Deinstallieren

bash

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

Das Binary unter dem Verzeichnis vendor/ des Pakets wird mit entfernt. Zugangsdaten liegen außerhalb des Pakets — entfernen Sie sie separat, wenn Sie die CLI auf dieser Maschine nicht mehr brauchen:

bash

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

Das Entfernen der Konfiguration löscht die lokal gespeicherten Zugangsschlüssel und Tokens — siehe Authentifizierung dafür, was gespeichert wird und wie Sie einzelne Profile entfernen.

Offline, Intranet und eigene Mirrors

Ein lokal gebautes dist/ verwenden

Bauen Sie die Binaries aller Plattformen und verweisen Sie den Installer dann darauf:

bash

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

Einen Mirror verwenden

bash

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

Der Mirror muss das Release-Layout abbilden:

Plain Text

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

Download vollständig überspringen

bash

export SENSECRAFT_CLI_SKIP_DOWNLOAD=1

Die Installation schlägt fehl, wenn vendor/ nicht bereits ein Binary enthält, das zur aktuellen Version passt — nützlich in CI, um jeden Netzwerkzugriff auszuschließen.

Prüfsumme verifizieren

Wenn für das Release ein SHA256 veröffentlicht ist:

bash

export SENSECRAFT_CLI_SHA256="<hex digest>"

Die Installation schlägt fehl, wenn die heruntergeladenen Bytes nicht übereinstimmen.

Proxys

Der Installer berücksichtigt die üblichen Proxy-Variablen von Node bzw. des Systems:

bash

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

Aus dem Quellcode bauen

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

Ein Unterschied im Verhalten ist wichtig: Ein selbst gebautes Binary liest seine Konfiguration standardmäßig aus dem aktuellen Verzeichnis, während die per npm installierte CLI ~/.config/sensecraft-cli/ liest — siehe Konfiguration dafür, wie Sie beide mit SENSECRAFT_CLI_PATH vereinheitlichen.

Installation überprüfen

Sandbox-Befehle liefern Beispiel-JSON zurück, ohne auf das Netzwerk zuzugreifen — sie brauchen aber trotzdem ein vorhandenes Profil, legen Sie also zuerst ein simuliertes an (schreibt eine Fake-Konfiguration, kein Konto nötig):

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

(Hat ein Befehl keinen Sandbox-Modus, meldet er einfach einen Fehler — das ist zu erwarten.)