認証

SenseCraft CLI はアクセスキーで認証します。1 つのキーで SenseCraft Data、 SenseCraft AI、CodeCraft Hub をカバーします。

方法	仕組み	選ぶ場面
1. ブラウザ認可 —— `auth init`	ブラウザでサインインしてアクセスを承認し、キーを選択または作成します	初回セットアップ（AI エージェントでのセットアップを含む）
2. アクセスキーのインポート —— `auth add`	アカウントセンターでキーを作成または探し、CLI にインポートします	特定のキーの再利用、スクリプト、CI

どちらの方法でも、CLI を実行するマシンにアクティブなアクセスキーのプロファイルが保存されます。以降のコマンドはそのプロファイルを再利用します。

始める前に：アカウントとサイト

CLI がアカウントを作成することはありません。認証には、対象とするサイト上の既存の Seeed アカウントが必要です：

Global（国際） —— sensecap.seeed.cc または sensecraft.seeed.cc で登録します。
China —— 中国国内のアカウントシステムです。

サイトはプロファイルごとに選択され、設定ファイルに保存されます。あるサイトで作成したキーは別のサイトでは使えません —— China プロファイルに Global のキーを使うのが、無効なキーエラーの典型的な原因です。

方法 1 —— ブラウザ認可

auth init を使うと、ブラウザ経由でサインインし、シークレットをコピーすることなくアクセスキーを選択または作成できます。

AI エージェントを使う場合

現在の CLI は、認可を複数のコマンドに分けて実行できます。各ステップは JSON を出力して終了するため、エージェントは対話型ターミナルがなくてもセットアップを進められます。ここで説明するスキルの手順を使うには、CLI 0.4.3 以降に更新してください。

現在のプロファイルを確認する —— sensecraft-cli auth info を実行します。認証情報がすでに設定されている場合は、想定されるサイトと組織を再利用します。
認可を開始する：
bash
```
sensecraft-cli auth init --site Global --no-wait
```
エージェントは返された device_code を保持し、verification_url をあなたに提示して、ブラウザでサインインして承認するのを待ちます。承認したらエージェントに伝えてください。ポーリングの前にリンクを提示する必要があります。
ブラウザ承認後に、利用可能なキーを読み取る：
bash
```
sensecraft-cli auth init --device-code <device_code>
```
アカウント、組織、利用可能なキー ID、ラベル、権限が返されます。アクセスキーのシークレットは出力されません。
選択したキーを保存する —— または、タスクに必要な権限を持つラベル付きのキーを作成します：
bash
```
sensecraft-cli auth init --device-code <device_code> --key-id <access_id>
```
代わりに新しいキーを作成する場合：
bash
```
sensecraft-cli auth init --device-code <device_code> --label <name> --access-level read-write
```
--access-level は read-write と only-read を受け付けます。未解決のアカウントや権限の選択肢については、エージェントがチャットで確認し、シークレットは CLI にローカルで保存させます。
保存されたプロファイルを確認する —— クラウドコマンドに進む前に sensecraft-cli auth info を実行します。

対話型ウィザード

対話型ターミナルで CLI を直接使う場合は、ウィザードを起動します：

sensecraft-cli auth init

ステップ	内容
1	サイトを選ぶ —— Global（国際）または China
2	デバイスコードを要求する —— CLI がユーザーセンターから取得します
3	ブラウザで承認する —— ワンタイムコードが埋め込まれたリンクと、コードそのものを別の行に出力します
4	待つ —— ポーリングし、承認されると自動で続行します
5	キーを選ぶ —— アカウント上のアクセスキーを一覧表示します。既存のものを選ぶか、ラベルと読み取り/書き込みレベルを指定して新規作成します。プロファイルはアクティブとして保存されます

ターミナルの表示は次のようになります：

[3/5] Complete authorization in the browser

Copy the link below into your browser and authorize with the primary account:

  https://account.seeed.cc/device?user_code=ABCD-2345

  Verification code: ABCD-2345

The CLI will continue automatically after you complete browser authorization.

接続要件

リンクは持ち運べます。 ブラウザのある任意のデバイスで開けます。残りの CLI ステップは、認可を開始したマシンで実行してください。
対話型ターミナルが必要なのはウィザードだけです。 エージェントは --no-wait、続いて --device-code を使います。対話型フローを選んだ場合は、ウィザードを動かしたままにしてください。
どちらのブラウザフローでもキーを作成できます。 アカウントセンターへの別途アクセスは任意です。方法 2はキーのインポートを扱います。
コードには有効期限があります（数分です。有効期間はアカウントサービス側で決まります）。操作が遅いと、CLI は context deadline exceeded で終了し、何も保存しません —— 新しいコードを取得するには再実行してください。
--sandbox はネットワークリクエストなしでフロー全体をシミュレートしますが、それでもシミュレートされた設定を書き込むことがあります —— それが問題になる場合は SENSECRAFT_CONFIG_FILE を一時ファイルに向けてください。

方法 2 —— アクセスキーをインポートする

auth add を使って、特定のアクセスキーをインポートします。この方法はアカウントセンターから始まり、保存する前に OpenAPI 経由でキーを検証します。

1. アクセスキーを作成または見つける

アクセスキーは Seeed アカウントセンターのアクセスキーで作成・管理します。お使いのサイトのページを開きます：

サイト	ページ
Global (International)	account.seeed.cc/account/access-keys
China	account.seeed.cn/account/access-keys

Seeed アカウントセンターのアクセスキーページ（キーを作成ボタンを強調）

選択したサイトのアクセスキーページ（デモデータ）。キーを作成を選びます。

主アカウントでサインインしてください —— サブアカウントはアクセスキーを表示・管理できません。その場合、ページには一覧の代わりに権限の警告が表示されます。既存のキーを使うか、新しく作成します：

キーを作成を選びます。
あとで見分けられるラベルを付けます（任意、64 文字まで。例：laptop-cli）。
権限を選択します：
- 読み取り —— デバイスの一覧表示、テレメトリの読み取り、アプリとモデルの検索。監視や読み取り専用のエージェントワークフローには十分です。
- 読み書き —— 読み取りでできることすべてに加えて、作成・更新・公開・削除・アップロード・デプロイ・バインドが可能です。
新しいキーの行から両方の値をコピーします：
- アクセス ID —— 公開識別子。CLI では Key ID（--key-id）と呼びます。
- アクセスキー —— シークレット（--access-key）。目のアイコンで表示してからコピーします。

ラベルと権限フィールドがあるアクセスキーを作成ダイアログ

キーにラベルを付け、読み取りまたは読み書きを選びます。

キー行に表示されたアクセス ID とアクセスキー

まず アクセス ID をコピーし、アクセスキーを表示してからコピーします。

キー作成ダイアログの権限は既定で読み書きです。読み取りだけを行うワークフローでは読み取りを選んでください。読み取り権限のキーは認証自体は成功しますが、書き込みコマンドはすべて権限エラーで失敗します —— これはキーの権限レベルによるもので、CLI の不具合ではありません。

シークレットはこのページでいつでも再表示・コピーできるため、一度きりの表示ではなくパスワードとして扱ってください。編集でラベルや権限を変更でき、キーを無効にしたいときは無効化を使います。このページに削除ボタンはありません。無効化が失効のスイッチで、有効化で元に戻せます。

2. キーをインポートする

キーを CLI にインポートします：

sensecraft-cli auth add \
  --key-id <Access ID> \
  --access-key <Access Key> \
  --site Global

--site は Global（既定）と China を受け付けます。キーを発行したサイトを選んでください：account.seeed.cc → --site Global、account.seeed.cn → --site China。検証はそのサイトの OpenAPI を呼び出すため、別のサイトのキーでは失敗します。

対話型ターミナルでは、不足している値はエラーではなくプロンプトで尋ねられます。サイトのプロンプトは、キーの値もプロンプトで尋ねられた場合にのみ表示されます —— --key-id と --access-key の両方を指定して --site を省略すると、CLI は Global を暗黙に使います。重要な場合は --site を明示的に指定してください。

Key ID: K1234567890
Access Key: <paste the Access Key>
Select the SenseCAP site to connect to
  1) Global (International)
  2) China (China site)
Enter number [1]:

プロンプトは入力内容をそのまま表示します。プライベートなターミナルで実行してください。--access-key フラグの形式はシェル履歴やプロセス一覧にも残るため、共有のログ、スクリーンショット、エージェントの会話ログにキーを貼り付けないでください。

3. インポートを確認する

CLI は view_organization 呼び出しでキーを検証し、組織 ID を解決してプロファイルを保存し、アクティブにします：

Verifying Access Key against OpenAPI ...
✓ Access Key verified
  Site: Global
  Organization ID: 12345
  Key ID: K1234567890

✓ Access config saved and set as active
  Config file: ~/.config/sensecraft-cli/sensecraft.json

auth add は既存のキーをインポートするだけで、キーの作成・ローテーション・削除は決して行いません。検証に失敗した場合、設定ファイルには何も書き込まれません。

auth info —— 認証情報を確認する

どちらの方法でも、次のコマンドでアクティブなプロファイルを確認できます：

sensecraft-cli auth info

使用中の設定ファイルのパスに加えて、サイト、組織 ID、アクティブなアクセス ID （Key ID として表示）、作成時刻を人間が読める形式（JSON ではない）で出力します。シークレットは決して出力されません。まだ何も設定されていない場合は No profiles configured yet. と表示し、auth init を提案します。このコマンドはローカルの設定を読むだけで、保存されたキーを検証するための API リクエストは行いません。

コマンドがどの環境に対して実行されるかわからないときは、いつでもこれを実行してください —— 設定も参照してください。

複数のプロファイルと切り替え

設定ファイルには複数のアクセスキープロファイルを保存できます（ファイルのスキーマは設定を参照）。どれがアクティブかを決めるポインタは 1 つです：

use_api —— アクティブなアクセス ID

auth add / auth init が成功するたびに、そのプロファイルを書き込み、 アクティブに設定します。以前のプロファイルに戻すには、そのキー／サイトに対して再度 auth add を実行するか（既存のプロファイルを再検証して再有効化します）、設定ファイルの use_api を直接編集します。「最初のエントリが優先される」というフォールバックは意図的にありません —— ポインタが未設定なのはエラーであり、推測ではありません。

認証情報の削除

auth remove コマンドはありません —— 認証情報の削除は、意図的に行うローカルファイルの操作です。

キーを使えなくする

アクセスキーページを開き、そのキーを 無効化します。再度有効化するまで、そのキーを使う API 呼び出しは失敗します。無効化は元に戻せ、キーは一覧に残ります。認証情報を利用先のすべてで無効にしたい場合はこの手順です —— ローカルのプロファイルを削除しても、そのマシンで忘れられるだけです。

すべて削除する（完全にログアウト）

設定ディレクトリを削除します（場所はインストール方法によって異なります。設定を参照）：

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

そのマシンに保存されているすべてのアクセスキー、トークン、プロファイルのポインタが消えます。

プロファイルを 1 つ削除する

sensecraft.json を開き、app_config_list からそのエントリを削除します。削除したのが現在アクティブなプロファイルだった場合は、use_api を残っているエントリに向けるか、値をクリアして auth add / auth init を再実行してください。ファイルのパーミッションは 0600 に保ってください —— CLI はそのパーミッションでアトミックに書き込みます。

セキュリティ上の注意

設定ファイルは、一時ファイルとリネームによるアトミックな書き込みで、0600 のパーミッションで作成されます。そのため、書き込みが途中で終わってもファイルが壊れることはありません。シークレットはそのファイルに平文で保存されます —— キーだけでなく、ファイル自体を保護してください。
sensecraft.json は決してコミットしないでください。CI 用にリポジトリへコピーを置く場合は、キーの権限をパイプラインが実際に必要とする範囲に絞ってください（可能なら読み取り専用）。
読み取り権限のキーでは、書き込みコマンドはすべて権限エラーで失敗します —— これはキーの権限レベルによるもので、CLI の不具合ではありません。
AI でのセットアップでは、エージェントが auth init --no-wait を開始し、あなたのブラウザ承認を待ちます。パスワード、トークン、生のアクセスキーはチャットやエージェントのログに残さないでください。詳しくは確認と安全性を参照してください。

バージョンに関する注意

公開されている @seeed-studio/sensecraft-cli ビルドは、Global サイトと China サイトで、単一のアクセスキーに対する auth init（推奨）と auth add の両方をサポートします。アクセスキーは有効期限がなく、更新もされないため、auth refresh コマンドや --kind フラグはありません。China サイトが SenseCraft Data のみであることを忘れないでください。