wuji-cli-base

Before running commands

Sync these skills to the installed CLI version:

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

Command	Purpose
wuji devices	Scan and list devices (USB/UDP)
wuji ping	Handshake probe; reports SN/firmware/IP (probes all devices by default)
wuji resources	List 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-model	Hand model calibration (see the wuji-cli-calib skill)
wuji calib tactile	Tactile contact-model calibration (see the wuji-cli-calib skill)
wuji doctor	Device health self-check (see the wuji-cli-doctor skill)
wuji upgrade	Firmware update check and upgrade (see the wuji-cli-upgrade skill)
wuji user	Manage SDK users and export/import calibration data (see the wuji-cli-user skill)
wuji update	Update 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:

--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)

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

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:

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

Symptom	Meaning 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=Y	Multiple devices share one address, or the scan entry is stale; rerun wuji devices to verify
virtual parameter 'X' currently has no value	The virtual param has no default and the stateless CLI doesn't persist writes; expected behavior
'X' does not support set. Supported operations: get	The 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 change	Network 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:

$ 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

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

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:

Status	Meaning
up-to-date	Installed Skills are at or above the CLI's companion version
update-required	Installed Skills are older, or their version isn't readable. Skills sync automatically after a successful binary upgrade, or run wuji update --skills
not-installed	No 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.

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 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