Installation

Prérequis

Élément	Exigence
Node.js	≥ 16 (18 / 20 LTS recommandé) — nécessaire uniquement pour l’installateur npm
Plateforme	macOS Intel/Apple Silicon · Linux x64/arm64 · Windows x64/arm64
Réseau	le registre npm, plus l’hôte de téléchargement du binaire (Aliyun OSS par défaut)
Facultatif	la chaîne d’outils Go, uniquement pour compiler depuis les sources

Le paquet npm n’est qu’une enveloppe : il télécharge un binaire Go statique précompilé pour votre plateforme à la première utilisation et enregistre la commande sensecraft-cli. Le binaire lui-même n’a aucune dépendance d’exécution.

Installation (recommandée)

Lancez l’installateur avec npx :

bash

npx @seeed-studio/sensecraft-cli install

Cela va :

1. Télécharger le binaire correspondant à votre plateforme et à la version du paquet.
2. Enregistrer sensecraft-cli globalement dans votre PATH.
3. Si aucun identifiant n’existe encore et que vous êtes dans un terminal interactif, proposer l’assistant de configuration dans le navigateur. Pour utiliser plutôt une clé d’accès créée dans le centre de comptes, lancez auth add après l’installation (voir Authentification).

Vérifiez :

bash

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

Windows

powershell

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

• La commande est installée sous le nom sensecraft-cli.cmd dans npm prefix -g.
• Si un nouveau terminal ne la trouve pas, ajoutez ce répertoire au PATH système.
• PowerShell 5+ ou Windows Terminal est recommandé ; Git Bash fonctionne généralement aussi.
• Certains antivirus mettent en quarantaine le sensecraft-cli.exe téléchargé la première fois — autorisez le répertoire d’installation et réinstallez le cas échéant.

Exécuter sans installation

Chaque commande fonctionne via npx, au prix d’une petite vérification au démarrage à chaque fois :

bash

npx @seeed-studio/sensecraft-cli device list

Installer une version précise

bash

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

Les téléchargements de binaires sont adressés sous la forme {RELEASE_BASE}/v{version}/sensecraft-cli-{os}-{arch}[.exe], la base de publication par défaut étant https://sensecraft-statics.oss-us-east-1.aliyuncs.com/static/bin/sensecraft-cli.

Complétion du shell (facultatif)

Le CLI embarque les complétions Cobra — complétion par tabulation des commandes et des options :

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

Ouvrez un nouveau shell pour la charger. Windows : sensecraft-cli completion powershell affiche le script — ajoutez-le à votre $PROFILE.

sensecraft-cli: command not found

Vérifiez que l’installation a bien eu lieu (npx @seeed-studio/sensecraft-cli install), puis regardez si le répertoire bin global de npm figure dans votre PATH. L’installateur indique le répertoire dont il a besoin — quand votre PATH ne le contient pas, sa sortie se termine par cette indication :

Plain Text

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

(« Si vous ne pouvez pas lancer sensecraft-cli directement, ajoutez le répertoire suivant au PATH. »)

Ajouter un répertoire au PATH, c’est placer une ligne export dans le fichier de profil de votre shell, pour que chaque nouveau terminal en dispose.

macOS / Linux — zsh est montré ; utilisez ~/.bashrc à la place si votre shell est bash (echo $SHELL vous le dira) :

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 affiche le répertoire global de npm, et la commande se trouve dans son sous-répertoire bin — celui-là même que montre l’indication.

Windows (PowerShell) — définissez-le pour votre utilisateur, puis ouvrez un nouveau terminal :

powershell

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

Ouvrez ensuite un terminal nouveau — les modifications du PATH ne s’appliquent qu’aux shells démarrés après — et relancez sensecraft-cli --version.

Mise à niveau

bash

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

L’installateur compare l’estampille de version du binaire téléchargé (vendor/.version) à la version du paquet npm : si elles correspondent, il réutilise le binaire en cache, sinon il télécharge celui qui correspond. Confirmez avec sensecraft-cli --version.

Si la version refuse de changer, videz à la fois le paquet et le cache npm, puis réinstallez :

bash

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

Désinstallation

bash

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

Le binaire présent dans le répertoire vendor/ du paquet est supprimé avec lui. Les identifiants vivent en dehors du paquet — supprimez-les séparément si vous avez terminé avec le CLI sur cette machine :

bash

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

Supprimer la configuration efface les clés d’accès et les jetons stockés localement — voir Authentification pour ce qui est stocké et comment supprimer des profils individuels.

Hors ligne, intranet et miroirs personnalisés

Utiliser un dist/ compilé localement

Compilez les binaires de toutes les plateformes, puis pointez l’installateur dessus :

bash

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

Pointer vers un miroir

bash

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

Le miroir doit reproduire l’arborescence de publication :

Plain Text

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

Ignorer complètement le téléchargement

bash

export SENSECRAFT_CLI_SKIP_DOWNLOAD=1

L’installation échoue si vendor/ ne contient pas déjà un binaire correspondant à la version courante — utile en CI pour garantir l’absence d’accès réseau.

Vérifier une somme de contrôle

Si un SHA256 est publié pour la version :

bash

export SENSECRAFT_CLI_SHA256="<hex digest>"

L’installation échoue quand les octets téléchargés ne correspondent pas.

Proxys

L’installateur respecte les variables proxy standard de Node et du système :

bash

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

Compiler depuis les sources

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

Une différence de comportement à connaître : un binaire que vous avez compilé vous-même lit sa configuration dans le répertoire courant par défaut, tandis que le CLI installé via npm lit ~/.config/sensecraft-cli/ — voir Configuration pour les unifier avec SENSECRAFT_CLI_PATH.

Vérifier l’installation

Les commandes en mode bac à sable renvoient un exemple de JSON sans toucher au réseau — mais elles ont tout de même besoin qu’un profil existe, alors initialisez d’abord un profil simulé (écrit une fausse configuration, aucun compte nécessaire) :

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

(Si une commande n’a pas de mode bac à sable, elle signale simplement une erreur — c’est normal.)