wuji-technology/wuji-cli

wuji-cli-base

Interact with Wuji devices (data gloves / dexterous hands) via the wuji CLI: scan for devices (devices), probe connectivity with a handshake (ping), read and write device parameters (get/set), and subscribe to real-time data such as EMF, tactile, and IMU (s…

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/wuji-technology/wuji-cli --skill wuji-cli-base

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Before running commands

Sync these skills to the installed CLI version:

bash
wuji update --skills

When the local skills already match the CLI version, the command installs nothing, but it still reports stale Skills directories and moves them out of ~/.agents/skills when you pass --yes or confirm the prompt (see the Stale Skill Directories section below). It exits non-zero only when the sync fails to converge.

Mental Model

  • Stateless: each command runs connect → operate → disconnect on its own. No connection persists between commands, so there's no separate "connect" step.
  • Single occupancy: device firmware allows only one direct session at a time. When a host app (such as Wuji Studio) holds the device, the CLI automatically falls back to read-only access through the Zenoh bridge (set writes are rejected in this mode).
  • Exit codes: 0 = success; non-zero = failure (ping failing on any device or doctor reporting a Fail both exit 1), directly usable in scripts.

Command Overview

CommandPurpose
wuji devicesScan and list devices (USB/UDP)
wuji pingHandshake probe; reports SN/firmware/IP (probes all devices by default)
wuji resourcesList readable/writable params and subscribable topics
wuji get <path>Read a parameter (auto-decoded to JSON per schema)
wuji set <path> <value>Write a parameter (value is JSON; 0x prefix means raw hex bytes)
wuji sub <topic>Subscribe to real-time data (--count N exits after N frames)
wuji viz --sn <SN>Visualize live Wuji Hand 2 data (see the wuji-cli-viz skill)
wuji calib hand-modelHand model calibration (see the wuji-cli-calib skill)
wuji calib tactileTactile contact-model calibration (see the wuji-cli-calib skill)
wuji doctorDevice health self-check (see the wuji-cli-doctor skill)
wuji upgradeFirmware update check and upgrade (see the wuji-cli-upgrade skill)
wuji userManage SDK users and export/import calibration data (see the wuji-cli-user skill)
wuji updateUpdate the CLI and its Agent Skills (--check checks only, --skills syncs Skills only)
wuji completions <shell>Generate shell completion scripts

Add --help after any command to see its detailed help.

Selecting a Device

Most commands accept one of three mutually exclusive selectors:

bash
--sn WG1KXXXXXXXXXXX            # By serial number (recommended, most precise)
--address 192.168.1.100:50001    # By network address (ip:port); for USB devices, use --sn
--handedness left                # By handedness left/right (two-handed setups)

Without a device selector: ping / doctor handle all devices; get / set / sub / resources require a specific device and error out with candidate SNs listed.

Typical Workflow

bash
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

Common Resources at a Glance

wuji resources --sn <SN> --json is the authoritative list; these are the high-frequency items:

  • Common params (get/set): hand_side, firmware_version, serial_number, ip_address, data_port — capabilities vary by device, and the GET/SET columns in wuji resources --sn <SN> are authoritative
  • Common topics (sub): tactile (tactile matrix), emf_poses (EMF poses), imu_data/palm (IMU), tip_poses (fingertip poses), hand_joint_angles (joint angles), hand_skeleton, tf

Recording Data to Files

--jsonl prints one frame per line, so a pipe is all you need for lightweight recording:

bash
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

Common Errors and Handling

SymptomMeaning and handling
found N devices: ...No device specified and multiple are on the bus; use --sn as prompted
Session already exists (0x0013)Another process holds a direct session; with --sn or no target, the CLI falls back to Zenoh read-only automatically
connected to wrong device: requested sn=X, got sn=YMultiple devices share one address, or the scan entry is stale; rerun wuji devices to verify
virtual parameter 'X' currently has no valueThe virtual param has no default and the stateless CLI doesn't persist writes; expected behavior
'X' does not support set. Supported operations: getThe resource doesn't support that operation, so the CLI sends nothing to the device and exits with code 1. Check the resource's GET, SET, or SUB column in wuji resources --sn <SN>. With --json or --jsonl, the error also carries kind: "unsupported_operation", path, operation, device, and capabilities
set rejected (direct_only)Currently read-only through the Zenoh bridge; retry after the direct session holder releases the device
set succeeds but wuji devices shows no changeNetwork params such as ip_address/data_port take effect after a device reboot

Most commands support --json, which gives agents more detailed, structured output.

Without --json, output is human-friendly, for example:

bash
$ 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"
    }
  ]
}

Device type and firmware version are not shown here: discovery is a broadcast scan without a handshake. Use wuji ping to get them.

Keeping the CLI and Skills Up to Date

bash
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 always exits 0 when the check itself succeeds. Gate on the update_available JSON field instead of the exit code. A background check also runs at most once every 24 hours and prints a notice on stderr — it never blocks commands or touches stdout. Set WUJI_NO_UPDATE_CHECK=1 to disable it.

Checking the Exact Version

bash
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"}

The --long output is stable line-oriented text for scripts: each line is key: value, in the order commit, version, target, profile. The commit is the 40-character sha the binary was built from, or unknown for builds outside a Git checkout.

Agent Skills

wuji update and wuji update --skills keep the Wuji CLI Skills in ~/.agents/skills at or above the version that ships with your CLI. The report's skills.status field has three states:

StatusMeaning
up-to-dateInstalled Skills are at or above the CLI's companion version
update-requiredInstalled Skills are older, or their version isn't readable. Skills sync automatically after a successful binary upgrade, or run wuji update --skills
not-installedNo Wuji CLI Skills found. wuji update reports this state, and wuji update --skills installs them

wuji update --skills syncs Skills without touching the binary, so you don't need a CLI upgrade to get Skills at the CLI's version or above. It exits 1 when Skills remain below that version after the sync, or when their version stays unreadable.

Stale Skill Directories

A Skill that was renamed or retired keeps its directory on disk after a sync, because the installer only writes files. After a sync the CLI lists those directories, warns on stderr, and asks before moving them out of ~/.agents/skills. Moved directories stay in a temp directory, and the report lists each one with its new path and "action": "moved". Nothing gets deleted.

In JSON output those directories appear under stale_skills — the field is omitted when there are none. Each entry has name, action (moved, kept, or failed), and, when it applies, version, path, and error.

Pass --yes to skip the question, as wuji update --yes or wuji update --skills --yes. A run without a terminal reports the stale directories and leaves them in place unless you also pass --yes. With --yes the directories move out whether or not a terminal is present, so an automated run that passes the flag modifies ~/.agents/skills.

bash
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 never moves directories.

Install Shell Completions (Optional)

bash
# bash example; for zsh or PowerShell, 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
from this repository

More skills

All skills
wuji-technology
Community

wuji-cli-calib

Guide safe Wuji Glove calibration with the wuji CLI. Use when the user asks to run or monitor wuji calib hand-model or wuji calib tactile, interpret calibration progress or errors, cancel an active calibration, inspect the resulting hand model, or choose between hand model and tactile calibration. Route each mode without applying the hand model's user-and-hand rules to tactile's device-specific model.

1h installs
1
GitHub stars
5
Updated
Nov 10
wuji-technology
Community

wuji-cli-upgrade

Upgrade Wuji device firmware with wuji upgrade: check which devices have updates (--check), upgrade one or all devices to the latest release, install a specific version (--to), flash a local firmware package (--file), browse the firmware catalog (--list), and roll the device back to its backup firmware (rollback). Use when the user wants to upgrade, downgrade, roll back, or re-flash device firmware, or asks whether firmware updates are available.

1h installs
1
GitHub stars
5
Updated
Nov 10
wuji-technology
Community

wuji-cli-user

Create, switch, list, show, rename, or delete wuji SDK user profiles, and export/import calibration bundles (hand model + tactile model) between machines, all via the wuji user CLI. These are named calibration profiles under ~/.wuji — NOT operating-system accounts — so use this skill (never edit code or touch OS users) for any request to delete a user, switch/change the current user, rename a user, create or list users, resolve the 'default user cannot calibrate' block, or move/inspect calibrati

1h installs
1
GitHub stars
5
Updated
Nov 10
wuji-technology
Community

wuji-cli-viz

Visualize live Wuji Hand 2 or Wuji Glove data with the official Rerun Web Viewer using wuji viz. Use when a user wants to inspect hand pose, per-taxel forces, per-finger resultant force, force history, live visualization faults, interactive device selection, or Hand 2 runtime tactile zeroing.

1h installs
1
GitHub stars
5
Updated
Nov 10