Instalación

Requisitos

Elemento	Requisito
Node.js	≥ 16 (se recomienda 18 / 20 LTS) — solo hace falta para el instalador de npm
Plataforma	macOS Intel/Apple Silicon · Linux x64/arm64 · Windows x64/arm64
Red	registro de npm, más el host de descarga del binario (Aliyun OSS por defecto)
Opcional	cadena de herramientas de Go, solo al compilar desde el código fuente

El paquete de npm es un envoltorio fino: en el primer uso descarga un binario Go estático ya compilado para tu plataforma y registra la orden sensecraft-cli. El binario en sí no tiene dependencias en tiempo de ejecución.

Instalación (recomendada)

Ejecuta el instalador con npx:

bash

npx @seeed-studio/sensecraft-cli install

Esto hará lo siguiente:

1. Descargar el binario que corresponde a tu plataforma y a la versión del paquete.
2. Registrar sensecraft-cli de forma global en tu PATH.
3. Si aún no hay credenciales y estás en una terminal interactiva, ofrecerte el asistente de configuración en el navegador. Para usar en su lugar una clave de acceso creada en el centro de cuentas, ejecuta auth add después de instalar (consulta Autenticación).

Comprueba:

bash

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

Windows

powershell

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

• La orden se instala como sensecraft-cli.cmd dentro de npm prefix -g.
• Si una terminal nueva no la encuentra, añade ese directorio al PATH del sistema.
• Se recomienda PowerShell 5+ o Windows Terminal; Git Bash también suele funcionar.
• Algunos antivirus ponen en cuarentena el sensecraft-cli.exe descargado la primera vez — si ocurre, añade el directorio de instalación a la lista de excepciones y reinstala.

Ejecutar sin instalar

Todas las órdenes funcionan a través de npx, a cambio de una pequeña comprobación de arranque cada vez:

bash

npx @seeed-studio/sensecraft-cli device list

Instalar una versión concreta

bash

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

Las descargas del binario se resuelven como {RELEASE_BASE}/v{version}/sensecraft-cli-{os}-{arch}[.exe], con la base de publicación por defecto https://sensecraft-statics.oss-us-east-1.aliyuncs.com/static/bin/sensecraft-cli.

Autocompletado del shell (opcional)

La CLI incluye los autocompletados de Cobra — completa órdenes y flags con el tabulador:

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

Abre un shell nuevo para cargarlo. En Windows, sensecraft-cli completion powershell imprime el script — añádelo a tu $PROFILE.

sensecraft-cli: command not found

Confirma que la instalación se ejecutó (npx @seeed-studio/sensecraft-cli install) y comprueba después si el directorio bin global de npm está en tu PATH. El instalador te dice qué directorio necesita — cuando falta en tu PATH, su salida termina con esta pista:

Plain Text

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

(«Si no puedes ejecutar sensecraft-cli directamente, añade el siguiente directorio a PATH.»)

Añadir un directorio al PATH significa poner una línea export en el archivo de perfil de tu shell, para que cada terminal nueva arranque ya con él.

macOS / Linux — se muestra zsh; usa ~/.bashrc en su lugar si tu shell es bash (echo $SHELL te lo dice):

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 imprime el directorio global de npm y la orden vive en su subdirectorio bin — el mismo directorio que muestra la pista.

Windows (PowerShell) — configúralo para tu usuario y abre después una terminal nueva:

powershell

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

Después abre una terminal nueva — los cambios de PATH solo se aplican a los shells que arrancan más tarde — y ejecuta sensecraft-cli --version otra vez.

Actualizar

bash

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

El instalador compara la marca de versión del binario descargado (vendor/.version) con la versión del paquete de npm: si coinciden, reutiliza el binario en caché; si no, descarga el que corresponde. Confírmalo con sensecraft-cli --version.

Si la versión se niega a cambiar, borra tanto el paquete como la caché de npm y reinstala:

bash

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

Desinstalar

bash

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

El binario que hay dentro del directorio vendor/ del paquete se elimina con él. Las credenciales viven fuera del paquete — elimínalas aparte si ya no vas a usar la CLI en esa máquina:

bash

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

Borrar la configuración elimina las claves de acceso y los tokens guardados en local — consulta Autenticación para saber qué se guarda y cómo eliminar perfiles concretos.

Sin conexión, intranet y espejos personalizados

Usar un dist/ compilado en local

Compila los binarios de todas las plataformas y apunta el instalador a ellos:

bash

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

Apuntar a un espejo

bash

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

El espejo debe reproducir la estructura de publicación:

Plain Text

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

Omitir la descarga por completo

bash

export SENSECRAFT_CLI_SKIP_DOWNLOAD=1

La instalación falla si vendor/ no contiene ya un binario que corresponda a la versión actual — útil en CI para garantizar que no hay acceso a la red.

Verificar una suma de comprobación

Si se publica un SHA256 para la versión:

bash

export SENSECRAFT_CLI_SHA256="<hex digest>"

La instalación falla cuando los bytes descargados no coinciden.

Proxies

El instalador respeta las variables de proxy estándar de Node y del sistema:

bash

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

Compilar desde el código fuente

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

Una diferencia de comportamiento que conviene conocer: un binario compilado por ti lee su configuración del directorio actual por defecto, mientras que la CLI instalada con npm lee ~/.config/sensecraft-cli/ — consulta Configuración para unificarlos con SENSECRAFT_CLI_PATH.

Verificar la instalación

Las órdenes de sandbox devuelven JSON de ejemplo sin tocar la red — pero necesitan que exista un perfil, así que crea primero uno simulado (escribe una configuración falsa, no hace falta cuenta):

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 una orden no tiene modo sandbox, simplemente da error — es lo esperado.)