wuji-cli-logs

Mental Model

• Logs are local text files written by Wuji SDK, Studio, stderr capture, and the CLI itself, stored under ~/.wuji/logs/. The CLI discovers and processes these files, and writes its own operation records as cli_*.jsonl.
• Text sources: sdk_*.log, studio_*.log, stderr_*.log, and cli_<date>.jsonl — the CLI's own record of the commands it runs (command line, exit code, duration, error). wuji sub and wuji completions write no operation records. Device communication dumps (device_*.bin) are excluded by default and gated behind --with-dump. wuji logs export bundles sdk, studio, stderr, and cli by default; pass --source to narrow the set. A wuji doctor run also records its report in the operation log, so a default bundle carries the checkup results. The operation log is redacted on export like every other text log; the local file itself stays as written, so it can be read directly while diagnosing.
• Export produces a single ZIP containing the selected log files, a host snapshot (host_snapshot.json), doctor diagnosis results (doctor_diagnosis.json — the same envelope as wuji doctor --json, with host-environment checks and per-device results all under checks), device snapshots + flash history (devices/<sn>_<ts>_device.json / _flash.jsonl, when devices are found), matching hand model calibration recordings, and a manifest (manifest.json). The snapshot and diagnosis are included even when no log files are found.
• Calibration recordings are automatic: runs from ~/.wuji/calibration/recordings/ that intersect the same inclusive local-date range are copied under calibration-recordings/<run_id>/. Partial or legacy runs with no ended_at are filtered as a single point at their local started_at date.
• Recording manifest compatibility: new hand-model runs use schema_version: 2 and calibration_type: "hand_model"; export also accepts legacy schema 1 / "ik" runs and preserves every source manifest unchanged.
• Redaction is layered: credentials (JWT, Bearer Token, API Key, Token, License, Password, AWS Key) are always redacted; private data (username, user paths, hostname, SSID, IPv4, MAC) is redacted by default and can be disabled via --no-redact (internal builds only). Calibration .mcap files contain raw motion data and are never redacted.
• Exit codes: 0 = success; 1 = any failure, including device diagnosis, log export, calibration recording, or device snapshot/flash collection failures. Recoverable items remain listed in the bundle manifest.

Subcommands

Subcommand	Purpose
wuji logs path	Print the log directory path
wuji logs list	List available log files with size and date
wuji logs export	Export logs, calibration recordings, snapshot, and diagnosis into a ZIP bundle
wuji logs dump	Collect a device-side diagnostic snapshot + flash history (Wuji Hand 2)

Common Usage

# Locate the log directory
wuji logs path

# List recent log files
wuji logs list
wuji logs list --days 7
wuji logs list --source sdk,studio --days 3
wuji logs list --source cli --days 1        # CLI operation records

# Export a default bundle (last 1 day: sdk / studio / stderr / cli logs and matching calibration runs)
wuji logs export
wuji logs export --days 7
wuji logs export --source sdk --days 3
wuji logs export --source cli --days 1      # only the CLI operation records

# Include device communication dumps
wuji logs export --with-dump

# Write the ZIP to a specific path
wuji logs export -o /tmp/support-bundle.zip

# Collect a device-side diagnostic snapshot + flash history (Wuji Hand 2)
wuji logs dump                          # scan all devices
wuji logs dump --sn <SN>                # single device
wuji logs dump --sn <SN> -o /tmp/dump   # write to a directory

# JSON / JSONL output for scripting
wuji logs export --json
wuji logs export --jsonl
wuji logs list --json
wuji logs list --jsonl
wuji logs path --json
wuji logs dump --json
wuji logs dump --jsonl

Default ZIP Naming

Without -o, the ZIP is written to the current directory as:

wuji-logs-{env_id}-{timestamp}.zip

env_id is the first 6 characters of the SHA-256 of the machine ID. timestamp is YYYYMMDD-HHMMSS.

Redaction Overview

Layer	What is redacted	Can be disabled?
🔴 Credentials	JWT, Bearer Token, API Key, Token, License, Password, AWS Key	Never
🟡 Private text data	Username, user paths, hostname, SSID, IPv4, MAC	Via --no-redact (internal builds only)
🟢 Preserved metadata	Device SN, firmware version, timestamps, error stacks	Always preserved
⚠️ Calibration motion	Nothing. .mcap files contain raw hand-motion data	Not applicable

Redaction applies to text log files inside the ZIP. Binary dumps (device_*.bin) are not redacted. The host host_snapshot.json redacts hostname, machine ID, and MAC address. doctor_diagnosis.json and device-side data actively collected from the device (devices/*_device.json, devices/*_flash.jsonl) are not redacted and are included as-is — the diagnosis covers software versions, OS, network interface counts, device discovery, and per-device checks (no hostname / machine ID / MAC), and device data is not host private data. Calibration .mcap files also contain raw motion data and are not redacted — review the bundle before sharing.

Typical Workflow

# 1. Check what logs are available
wuji logs list --days 3

# 2. Export a support bundle with today's logs
wuji logs export -o ~/Desktop/support.zip

# 3. Inspect the bundle contents
unzip -l ~/Desktop/support.zip
# Expected structure:
#   manifest.json
#   host_snapshot.json
#   doctor_diagnosis.json
#   logs/YYYY-MM-DD/sdk_*.log
#   logs/YYYY-MM-DD/studio_*.log
#   logs/YYYY-MM-DD/stderr_*.log
#   logs/YYYY-MM-DD/cli_*.jsonl     (CLI operation records, included by default)
#   devices/<sn>_<ts>_device.json   (device diagnostic snapshot, when devices found)
#   devices/<sn>_<ts>_flash.jsonl   (device flash history, when devices found)
#   calibration-recordings/<run_id>/manifest.json
#   calibration-recordings/<run_id>/full.mcap
#   calibration-recordings/<run_id>/steps/*.mcap  (completed steps only)

Common Errors

Symptom	Meaning and handling
failed to scan log directory	Log directory does not exist or is inaccessible. The CLI still produces a bundle with snapshot and diagnosis.
failed to create zip bundle	Output path is not writable or disk is full. Check permissions and free space.
Bundle exceeds 300 MB	A warning is printed. Use --days to narrow the date range or exclude dumps.
skipped (no device found) in diagnosis	No Wuji devices were detected. The export continues with available data.

Add --help after any wuji logs subcommand to see detailed help and all available options.