インストール

動作要件

項目	要件
Node.js	16 以上（18 / 20 LTS を推奨）—— npm インストーラーを使う場合のみ必要
プラットフォーム	macOS Intel/Apple Silicon · Linux x64/arm64 · Windows x64/arm64
ネットワーク	npm レジストリ、およびバイナリのダウンロード先（既定は Aliyun 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

• コマンドは npm prefix -g の下に sensecraft-cli.cmd としてインストールされます。
• 新しいターミナルでコマンドが見つからない場合は、そのディレクトリをシステムの 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] という形式で、既定の リリースベースは https://sensecraft-statics.oss-us-east-1.aliyuncs.com/static/bin/sensecraft-cli です。

シェル補完（任意）

CLI には Cobra の補完が同梱されています —— コマンドとフラグをタブ補完できます：

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

新しいシェルを開くと読み込まれます。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 にディレクトリを追加するとは、シェルのプロファイルファイルに export 行を 1 行入れることです。そうすれば、新しいターミナルはすべてその設定で起動します。

macOS / Linux —— zsh の例です。シェルが 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 の変更は、その後に起動したシェルにのみ 適用されます）、もう一度 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

知っておくべき動作の違いが 1 つあります。自分でビルドしたバイナリは既定で カレントディレクトリの設定を読みますが、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

（サンドボックスモードがないコマンドは単にエラーを返します —— これは想定どおりの 動作です。）