Introduction

Wuji CLI is a command-line tool for Wuji devices, built for terminals, scripts, and AI Agents. Scan devices, probe connectivity, read and write parameters, subscribe to real-time data, calibrate tactile sensing, run health diagnostics, and upgrade firmware — all without leaving the terminal.

Command Overview

Command	Purpose
`wuji devices`	Scan and list devices (USB/UDP)
`wuji ping`	Probe device connectivity via full handshake, reporting SN, firmware version, and IP
`wuji resources`	List readable/writable parameters and subscribable topics of a device
`wuji get <path>`	Read a parameter
`wuji set <path> <value>`	Write a parameter
`wuji user`	Manage user profiles and calibration data import/export
`wuji calib hand-model`	Run guided hand model calibration
`wuji sub <topic>`	Subscribe to real-time data
`wuji calib tactile`	Run guided tactile calibration to train and install a contact model
`wuji doctor`	Run a device health self-check
`wuji logs`	View, filter, and export log support bundles
`wuji upgrade`	Check for and install firmware updates
`wuji update`	Update the CLI to the latest release
`wuji completions <shell>`	Generate a shell auto-completion script

Add --help after any command for detailed usage.

Design Principles

Stateless: Each command completes its own connect-operate-disconnect cycle. No connection persists between commands, so there's no separate "connect" step.
Read-only fallback when occupied: Device firmware allows only one direct session at a time. When a host application such as Wuji Studio occupies the device, the CLI falls back to read-only access, and set operations are rejected.
Scriptable exit codes: 0 means success, and nonzero means failure. ping returns 1 if any device fails, and doctor returns 1 if it finds a fault — ready for script assertions.

Output Modes

All commands print tables or tree reports by default. Add a global flag to switch to structured output:

Flag	Output	Use Case
`--json`	Pretty-printed JSON	Script parsing, AI Agent consumption
`--jsonl`	One compact JSON object per line	Stream capture, pipelines

Error Output

Under --json / --jsonl, command errors print to stderr as JSON with a fixed structure, and stdout carries data only. The JSON object holds message (the full error chain) and argv (the original argument array of the invocation):

{
  "error": {
    "argv": ["wuji", "get", "...", "--json"],
    "message": "..."
  }
}

Argument parsing errors print the same structure with exit code 2. In scripts, judge success by the exit code (0 for success, nonzero for failure) instead of parsing stdout:

wuji get <path> --json 2>&1 | jq .error.message   # merge stderr, then extract the error
wuji get <path> --json 2>/dev/null                # drop errors, keep stdout clean

wuji user and wuji calib hand-model render their own structured errors with a code field and per-scenario exit codes, printed to stdout rather than stderr — both differ from the generic error structure. See "Automation" on each command page.