CLI commands
Everything is driven through the single avatar binary (crate avatar-cli, clap v4
subcommands). The groups below mirror the layers: FBX/armature on the 3D side, lint/stats on the project
side, generation and surgical editing on the Unity-YAML side, migration and PhysBone tuning for whole
avatars, packaging + rendering for preview, and osc for the live runtime. Run any command with
--help for flags. Every read and generate command also takes --json; writes are
dry-run-safe and never overwrite without --force.
Conventions shared by every command.
--json switches the report to
machine-readable output (avatar schema <name> prints its JSON Schema); writers default to
stdout or a dry run, take -o FILE to write, and refuse to overwrite without --force;
--dry-run plans without touching disk. Error text is an anyhow context chain
— read it bottom-up.
cargo run -p avatar-cli -- --help # every subcommand
cargo run -p avatar-cli -- lint --help # flags for one command
cargo install --path crates/cli # put `avatar` on PATHOne-shot snapshot
avatar describe path/to/model.fbx --json
avatar describe path/to/UnityProject --json| Command | What it does |
|---|---|
avatar describe <path> [--json] | One call: FBX structure + armature + geometry rank for an FBX, or project lint + per-avatar rank for a Unity project. The agent-friendly entry point. |
avatar schema [name|all] | Print the JSON Schema of a --json report type, so the output shape is a contract, not a guess. |
FBX & armature
avatar fbx inspect model.fbx
avatar armature check model.fbx
avatar armature fix model.fbx -o fixed.fbx --blender-script fix.py| Command | What it does |
|---|---|
avatar fbx inspect <model.fbx> | Node hierarchy, skeleton roots, bone count, scale/orientation, units; flags unapplied transforms, wrong axis/units, extra root, unskinned mesh, missing T-pose. |
avatar fbx reslot <model.fbx> … | Move a region of polygons onto another material slot (a glowing hair patch onto the plain black slot), selecting by bone proximity / height / texture brightness; --uv-mask emits the footprint for a texture-side fix instead. |
avatar fbx blendshapes <model.fbx> | List blendshape channels and the material slot each one's target vertices render with — which material an emote overlay shape actually uses. |
avatar armature check <model.fbx> | Map detected bones → Unity Humanoid; report missing/mis-mapped. Exits 0 when humanoid-ready. |
avatar armature fix <model.fbx> [-o fixed.fbx] | Print the repair plan (dry run by default); with -o, write a repaired FBX with canonical bone renames applied. --blender-script fix.py emits a headless-Blender script covering the geometry-level repairs too. |
Details: docs/reference/armature-repair.md. Or try the in-browser Avatar inspector.
Lint & stats
avatar lint path/to/UnityProject --deny-warnings
avatar stats path/to/UnityProject --json| Command | What it does |
|---|---|
avatar lint <UnityProject> | SDK3 compliance report (VRC001–VRC062: params, menus, descriptor refs, visemes incl. the source-FBX cross-check, animator + clip contents, PhysBones, Quest/hygiene); exits non-zero on errors. |
avatar lint <UnityProject> --deny-warnings | Also fail on warnings — gate CI directly. |
avatar stats <model.fbx> | Performance rank from geometry (triangles/meshes/material slots/bones). |
avatar stats <UnityProject> | Performance rank from per-avatar components (PhysBones/colliders/contacts/particles/constraints, texture VRAM for PC + Android). |
Rule codes: docs/reference/sdk3-lint-rules.md. Metrics: docs/reference/performance-stats.md.
Generate & edit Unity assets
avatar toggle --name Hat --toggle Armature/Head/Hat -o HatBundle/
avatar asset set Parameters.asset --path m_Name --value Params2 -o Parameters.asset --force| Command | What it does |
|---|---|
avatar anim-gen clip --name Smile --blendshape Body:Smile:100 -o Smile.anim | Emit a Unity .anim clip (blendshape-weight / GameObject-active curves). |
avatar anim-gen blendtree … | Emit a 1D analog-gesture blend tree (blends GestureLeft/RightWeight over child clips). |
avatar anim-gen controller … | Emit a complete, Unity-importable FX AnimatorController — the full asset, not a splice-in fragment. |
avatar anim-gen params / menu … | Emit VRCExpressionParameters / VRCExpressionsMenu assets from the command line. |
avatar anim-gen puppet … | Graft a radial-puppet dial into an existing avatar: splice a gated blend-tree layer into its FX controller and append the float param + menu control, by span-splice. |
avatar toggle --name Hat --toggle Armature/Head/Hat -o HatBundle/ | The composite: a full ten-file toggle bundle — On/Off clips, two-state FX controller, params, menu, and guid-pinning .metas. |
avatar asset set <file> --path m_Name --value X | Surgically edit an existing Unity asset (scalars, reference re-targets, structural edits) by span-splicing raw text — fileIDs/refs/formatting preserved. |
Deterministic fileIDs make generated assets diffable. Details: docs/reference/anim-gen.md, docs/reference/unity-yaml-edit.md.
Migrate & PhysBone tuning
avatar migrate sdk3 proj -o out/ --name MyAvatar --drop-cloth --eyes Eye_L,Eye_R
avatar physbone list out/Assets/MyAvatar_SDK3/MyAvatar.prefab| Command | What it does |
|---|---|
avatar migrate sdk3 <project> -o out/ --name N … | SDK2 → SDK3: descriptor/PipelineManager retyped in place, DynamicBone → PhysBone by the SDK's own rules, Cloth → PhysBone skirt, gesture overrides → an FX layer, rig-derived eye look, and a VCC-openable project tree around the rewritten prefab. |
avatar physbone list <prefab> | Every VRCPhysBone: root, chains (bones, length), colliders, tuning. |
avatar physbone set|split|stretch|flare|nudge … | Retune in place: values + per-chain curves, split chains onto their own components, lengthen a skirt/tail, re-angle chains toward vertical, shift hinge rings. |
Details: docs/reference/migrate.md, docs/reference/physbone.md.
Packages & preview
avatar unitypackage extract avatar.unitypackage -o proj
avatar render --avatar avatar.fbx --world world/Assets/Scene.unity -o in-world.png| Command | What it does |
|---|---|
avatar unitypackage info|list|extract <pkg> | Summarize a .unitypackage (detected SDK, avatar vs world), list assets, or extract into a Unity Assets/ tree. |
avatar unitypackage testbed <avatar> <world> | Co-import cross-check: GUID/path conflicts between an avatar package and a world package. |
avatar render --avatar a.fbx [-o out.png] | Offscreen GPU render (wgpu, headless): avatar rest pose, a world scene, or the avatar dropped at the world's spawn. --pose <prefab> / --stretch preview PhysBone edits. |
avatar view --avatar a.fbx --world Scene.unity | Interactive winit window: orbit / zoom / walk. |
Details: docs/reference/unitypackage.md, docs/reference/render.md.
OSC runtime
avatar osc send VRCEmote 3
avatar osc capture --seconds 60 -o events.jsonl
avatar osc replay events.jsonl --controller FX.controller --timeline| Command | What it does |
|---|---|
avatar osc send <param> <value> | Set an avatar parameter on a running VRChat (e.g. osc send VRCEmote 3). |
avatar osc input … | Drive /input/* axes & buttons (with reset-to-zero). |
avatar osc monitor | Listen for the avatar parameters VRChat broadcasts and print each update. |
avatar osc capture -o log | Record the parameter stream and reduce it to a gesture/weight cross-tab — ground truth for "what does my controller deliver?". Also a standalone Windows-cross-compilable avatar-gesture-capture bin, OSCQuery-advertised. |
avatar osc replay <events.jsonl> --controller <FX.controller> [--layer N] [--timeline] | Simulate a .controller against a captured log offline: the state timeline the FX actually went through. |
avatar osc change <blueprint-id> | Request VRChat switch avatars. |
avatar osc query <config.json> | Parse an avatar's OSCQuery config offline: parameter names, OSC type tags, access. |
avatar osc gestures --seconds 10 | Run the analog-gesture daemon (headless demo sweep; --hz/--period tunable). |
Details: docs/reference/osc-runtime.md.
Agent surface
avatar mcp serve
avatar schema all| Command | What it does |
|---|---|
avatar mcp serve | Run the stdio MCP server: the read/diagnose tools plus text-returning generation tools, discoverable by any MCP host. Non-writing by design — disk writes stay on the CLI. |
Details: docs/reference/mcp.md.