wuji-cli-base

コマンドを実行する前に

インストール済みの CLI バージョンにスキルを同期します。

wuji update --skills

ローカルのスキルがすでに CLI バージョンと一致している場合、コマンドは何もインストールしません。ただし、古くなったスキルディレクトリは引き続き報告され、--yes を指定するかプロンプトで確認すると ~/.agents/skills の外に移動されます（以下の「古くなったスキルディレクトリ」セクションを参照）。同期を完了できなかった場合にのみ、ゼロ以外の終了コードが返されます。

基本的な考え方

• ステートレス：各コマンドは、それぞれ単独で接続 → 操作 → 切断を実行します。コマンド間で接続が維持されることはないため、個別の「接続」手順はありません。
• 同時接続は 1 つのみ：デバイスのファームウェアでは、一度に直接接続できるセッションは 1 つだけです。ホストアプリ（Wuji Studio など）がデバイスを使用している場合、CLI は自動的に Zenoh ブリッジ経由の読み取り専用アクセスに切り替わります（このモードでは書き込みが拒否されます）。
• 終了コード：0 = 成功、ゼロ以外 = 失敗（いずれかのデバイスへの ping が失敗するか、doctor が Fail を報告すると、どちらも終了コード 1 になります）。スクリプトでそのまま使用できます。

コマンド一覧

コマンド	目的
wuji devices	デバイスをスキャンして一覧表示します（USB/UDP）
wuji ping	ハンドシェイクを確認し、SN/ファームウェア/IP を報告します（デフォルトですべてのデバイスを確認します）
wuji resources	読み取り／書き込み可能なパラメーターと購読可能なトピックを一覧表示します
wuji get <path>	パラメーターを読み取ります（スキーマに従って自動的に JSON にデコードします）
wuji set <path> <value>	パラメーターを書き込みます（値は JSON です。0x プレフィックスは生の 16 進数バイトを表します）
wuji sub <topic>	リアルタイムデータを購読します（--count N を指定すると、N フレーム受信後に終了します）
wuji viz --sn <SN>	Wuji Hand 2 のライブデータを可視化します（wuji-cli-viz スキルを参照）
wuji calib hand-model	ハンドモデルをキャリブレーションします（wuji-cli-calib スキルを参照）
wuji calib tactile	触覚接触モデルをキャリブレーションします（wuji-cli-calib スキルを参照）
wuji doctor	デバイスの健全性をセルフチェックします（wuji-cli-doctor スキルを参照）
wuji upgrade	ファームウェアの更新を確認し、アップグレードします（wuji-cli-upgrade スキルを参照）
wuji user	SDK ユーザーを管理し、キャリブレーションデータをエクスポート／インポートします（wuji-cli-user スキルを参照）
wuji update	CLI とその Agent Skills を更新します（--check は確認のみ、--skills は Skills のみを同期します）
wuji completions <shell>	シェル補完スクリプトを生成します

コマンドの詳細なヘルプを表示するには、任意のコマンドの後に --help を追加します。

デバイスの選択

ほとんどのコマンドでは、相互に排他的な次の 3 つのセレクターのいずれかを使用できます。

--sn WG1KXXXXXXXXXXX            # By serial number (recommended, most precise)
--address 192.168.1.100:50000    # By address: ip:port for UDP, /dev/ttyACM0 for USB
--handedness left                # By handedness left/right (two-handed setups)

デバイスセレクターを指定しない場合、ping／doctor はすべてのデバイスを対象とします。get／set／sub／resources では特定のデバイスが必要で、指定しないと候補の SN を表示してエラーになります。

一般的なワークフロー

wuji devices --json                            # 1. What devices are there
wuji ping --json                               # 2. Can they all connect (confirm SN/firmware/IP)
wuji resources --sn <SN> --json                # 3. What params / topics are available
wuji get data_port --sn <SN> --json            # 4. Read a parameter
wuji set data_port 50001 --sn <SN>             # 5. Write a parameter (JSON value)
wuji sub tactile --sn <SN> --count 10 --jsonl  # 6. Capture 10 tactile frames

よく使うリソース一覧

wuji resources --sn <SN> --json が正式な一覧です。以下は、使用頻度の高い項目です。

• 一般的なパラメーター（取得／設定）：hand_side、firmware_version、serial_number、ip_address、data_port — 対応する機能はデバイスによって異なります。GET/SET 列は wuji resources --sn <SN> を正式な情報源としてください。
• 一般的なトピック（購読）：tactile（触覚マトリックス）、emf_poses（EMF ポーズ）、imu_data/palm（IMU）、tip_poses（指先のポーズ）、hand_joint_angles（関節角度）、hand_skeleton、tf

データをファイルに記録する

--jsonl は 1 行につき 1 フレームを出力するため、簡易的な記録にはパイプを使うだけで十分です。

wuji sub tactile --count 500 --jsonl > data/tactile.jsonl             # Silent recording
wuji sub emf_poses --count 500 --jsonl | tee data/emf.jsonl | jq      # Record and watch

一般的なエラーと対処方法

症状	意味と対処方法
found N devices: ...	デバイスが指定されておらず、バス上に複数のデバイスがあります。表示されたとおりに --sn を使用してください
Session already exists (0x0013)	別のプロセスがダイレクトセッションを保持しています。--sn を指定した場合、または対象を指定しない場合、CLI は自動的に Zenoh の読み取り専用モードに切り替わります
connected to wrong device: requested sn=X, got sn=Y	複数のデバイスが同じアドレスを共有しているか、スキャン結果が古くなっています。wuji devices を再実行して確認してください
virtual parameter 'X' currently has no value	仮想パラメーターにデフォルト値がなく、ステートレス CLI は書き込みを保持しません。これは想定された動作です
'X' does not support set. Supported operations: get	リソースはその操作をサポートしていないため、CLI はデバイスに何も送信せず、コード 1 で終了します。wuji resources --sn <SN> のリソースの GET、SET、または SUB 列を確認してください。--json または --jsonl を指定すると、エラーには kind: "unsupported_operation"、path、operation、device、capabilities も含まれます
set rejected (direct_only)	現在、Zenoh ブリッジ経由では読み取り専用です。ダイレクトセッションを保持しているプロセスがデバイスを解放した後に再試行してください
set succeeds but wuji devices shows no change	ip_address／data_port などのネットワークパラメーターは、デバイスの再起動後に反映されます

ほとんどのコマンドは --json に対応しており、エージェント向けに、より詳細で構造化された出力を返します。

--json を指定しない場合、次のように人が読みやすい形式で出力されます。

$ wuji devices
found 1 device(s)
┌──────────────────┬───────────┬──────────┬─────────────────────┬─────────────────────┐
│ SN               ┆ Transport ┆ USB Port ┆ IP                  ┆ Address             │
╞══════════════════╪═══════════╪══════════╪═════════════════════╪═════════════════════╡
│ WG1KXXXXXXXXXXX  ┆ Udp       ┆ -        ┆ 192.168.1.100:50001 ┆ 192.168.1.100:50001 │
└──────────────────┴───────────┴──────────┴─────────────────────┴─────────────────────┘
💡 run `wuji ping` to get device type and firmware version

$ wuji devices --json
{
  "devices": [
    {
      "sn": "WG1KXXXXXXXXXXX",
      "transport": "Udp",
      "usb_port": null,
      "ip": "192.168.1.100:50001",
      "address": "192.168.1.100:50001"
    }
  ]
}

デバイスの種類とファームウェアのバージョンはここには表示されません。ディスカバリーはハンドシェイクを行わないブロードキャストスキャンだからです。これらを取得するには wuji ping を使用してください。

CLI とスキルを最新の状態に保つ

wuji update --check --json   # {"current": ..., "latest": ..., "update_available": true/false}
wuji update                  # Download, verify, and replace the binary in place
wuji update --skills         # Sync Agent Skills to this CLI's companion version only

update --check は、チェック自体が成功すると常に終了コード 0 を返します。終了コードではなく、JSON の update_available フィールドで判定してください。バックグラウンドチェックも 24 時間に 1 回まで実行され、stderr に通知を表示します。コマンドをブロックしたり、stdout に出力したりすることはありません。無効にするには WUJI_NO_UPDATE_CHECK=1 を設定してください。

正確なバージョンの確認

wuji --version          # Two lines: short commit and version
wuji --version --long   # Four lines: full commit, version, build target, profile
wuji --version --json   # {"version", "commit" (full sha or "unknown"), "target", "profile"}

--long の出力は、スクリプト向けの安定した行指向テキストです。各行は key: value 形式で、commit、version、target、profile の順に出力されます。commit はバイナリのビルド元となった 40 文字の sha です。Git チェックアウト外でビルドされた場合は unknown になります。

エージェントスキル

wuji update と wuji update --skills は、~/.agents/skills にある Wuji CLI スキルを、CLI に同梱されているバージョン以上に保ちます。レポートの skills.status フィールドには 3 つの状態があります。

Status	意味
up-to-date	インストール済みスキルのバージョンが、CLI に付属するバージョン以上です
update-required	インストール済みスキルのバージョンが古いか、バージョンを読み取れません。バイナリのアップグレードが成功するとスキルは自動的に同期されます。または wuji update --skills を実行してください
not-installed	Wuji CLI スキルが見つかりません。wuji update はこの状態を報告し、wuji update --skills はスキルをインストールします

wuji update --skills はバイナリに触れずにスキルを同期するため、CLI のバージョン以上のスキルを取得するために CLI をアップグレードする必要はありません。同期後もスキルがそのバージョンに満たない場合、またはバージョンを引き続き読み取れない場合は、終了コード 1 で終了します。

古いスキルディレクトリ

名前が変更または廃止されたスキルのディレクトリは、同期後もディスク上に残ります。インストーラーはファイルを書き込むだけだからです。同期後、CLI はそれらのディレクトリを一覧表示し、標準エラー出力に警告を表示して、~/.agents/skills から移動する前に確認を求めます。移動したディレクトリは一時ディレクトリに残り、レポートには新しいパスと "action": "moved" がそれぞれ表示されます。何も削除されません。

JSON 出力では、それらのディレクトリは stale_skills の下に表示されます。該当するものがない場合、このフィールドは省略されます。各エントリには name、action（moved、kept、failed のいずれか）が含まれ、該当する場合は version、path、error も含まれます。

wuji update --yes や wuji update --skills --yes のように、--yes を指定すると確認を省略できます。ターミナルがない状態で実行すると、古いディレクトリが報告され、--yes も指定しない限り、そのまま残されます。--yes を指定すると、ターミナルの有無にかかわらずディレクトリが移動されるため、このフラグを指定して自動実行すると ~/.agents/skills が変更されます。

wuji update --skills --json   # Report stale directories without moving them (no --yes)
wuji update --skills --yes    # Move them out without asking, with or without a terminal

wuji update --check はディレクトリを移動しません。

シェル補完をインストールする（任意）

# bash example; for other shells (zsh/fish/powershell/elvish), see wuji completions --help
mkdir -p ~/.local/share/bash-completion/completions
wuji completions bash > ~/.local/share/bash-completion/completions/wuji
exec bash   # Takes effect in the current session