> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wuji.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

> What Wuji CLI is, its command overview, and design principles

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 another host application 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):

```json theme={null}
{
  "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:

```bash theme={null}
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`](/en/docs/wuji-cli/user) and [`wuji calib hand-model`](/en/docs/wuji-cli/hand-model-calibration) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.