avatar-cli

@three-ws/avatar-cli

Terminal-native tooling for on-chain avatars: scaffold, validate, hash, and preview avatar manifests.

Install · Quick start · Commands · CI usage · three.ws

---

@three-ws/avatar-cli brings the three.ws on-chain avatar workflow to your shell and CI. It scaffolds spec-compliant manifests from a wallet and a mesh file, validates existing manifests, computes content-addressing hashes, and prints embeddable preview snippets. Every command runs offline against @three-ws/avatar-schema — no service to sign up for, no browser required.

Install

# run a single command without installing
npx @three-ws/avatar-cli --help

# or install globally
npm install -g @three-ws/avatar-cli
three-ws-avatar --help

The binary is three-ws-avatar. --version prints the package version; --help / -h prints usage.

Quick start

# 1. Scaffold a manifest from your wallet + mesh (sha256 + size computed for you)
three-ws-avatar init \
  --owner eip155:1:0x742d35Cc6634C0532925a3b844Bc454e4438f44e \
  --name "Nicholas" \
  --mesh ./avatar.glb \
  --out manifest.json
# → wrote /…/manifest.json   (validated against @three-ws/avatar-schema before writing)

# 2. Validate it
three-ws-avatar validate manifest.json
# → ok: manifest.json

# 3. Print embed snippets
three-ws-avatar preview manifest.json
# → resolver URL, <three-ws-avatar> element, and <iframe> snippet

Commands

Command	What it does
init	Scaffold a new avatar manifest from a wallet and mesh file.
validate <path>	Validate an existing manifest against the schema (exit 1 if invalid).
hash <path>	Compute the SHA-256 of any file, lowercase hex.
preview <path>	Print resolver URL + embeddable <three-ws-avatar> and <iframe> snippets.

init — scaffold a manifest

three-ws-avatar init \
  --owner <caip10|0xaddr> \
  --name <string> \
  --mesh <path> \
  [--skeleton avaturn|mixamo|rpm|vrm-humanoid|custom] \
  [--mesh-uri <https://… or ipfs://…>] \
  [--id <override>] \
  [--out manifest.json]

Flag	Required	Notes
--owner	yes	Full CAIP-10 (eip155:1:0x…) or a shorthand 0x… address (assumed eip155:1).
--name	yes	Avatar display name.
--mesh	yes	Path to a .glb / .gltf / .vrm file. SHA-256, byte size, and format are computed/inferred automatically.
--skeleton	no	One of avaturn (default) / mixamo / rpm / vrm-humanoid / custom.
--mesh-uri	no	Public URI to reference instead of the local file:// path (use your IPFS/S3 URL).
--id	no	Override the id; otherwise derived from the owner's CAIP-10, or from --name if it's an ENS-style *.eth / *.ws / *.sol name.
--out	no	Write to a file (default: print JSON to stdout).

The manifest is validated against @three-ws/avatar-schema before output — if you get JSON back, it's spec-compliant by definition.

validate — check a manifest

three-ws-avatar validate manifest.json          # → ok: manifest.json
three-ws-avatar validate manifest.json --json    # → {"valid":true,"path":"manifest.json"}

Exit code 0 if valid, 1 otherwise. On failure, each error prints its JSON instance path and message (or a structured errors array with --json).

hash — SHA-256 a file

sha=$(three-ws-avatar hash ./avatar.glb)
echo "$sha"
# 3a7bd3e2360a3d29eea436fcfb7e44c735d117c42d1c1835420b6b9942dd4f1b

--json emits { "path", "sha256", "bytes" } instead of the bare hex line.

preview — embed snippets

three-ws-avatar preview manifest.json

Prints three things:

1. The resolver URL — https://three.ws/a/{id}
2. A <three-ws-avatar> web-component snippet (requires @three-ws/avatar on the page)
3. A zero-install <iframe> embed snippet

Use --viewer http://localhost:3000 to target a local dev viewer, or --json for machine-readable output ({ id, resolverUrl, element, iframe, schemaVersion }).

CI usage

Avatars are content, and content belongs in a build pipeline:

# Fail the build if the mesh bytes drifted from what the manifest attests to.
expected=$(node -p "require('./manifest.json').mesh.sha256")
actual=$(three-ws-avatar hash ./avatar.glb)
[ "$expected" = "$actual" ] || { echo "mesh hash mismatch"; exit 1; }

# Gate every manifest change on schema validity.
three-ws-avatar validate manifest.json

Requirements

• Node >=18.
• Bundled dependency: @three-ws/avatar-schema (used to validate every scaffolded and checked manifest).

Related packages

• @three-ws/avatar-schema — the manifest format this CLI scaffolds and validates.
• @three-ws/avatar — the runtime SDK and <three-ws-avatar> / <agent-3d> elements the preview snippets embed.

Links

• Homepage: https://three.ws
• Changelog: https://three.ws/changelog
• Issues: https://github.com/nirholas/three.ws/issues
• License: Apache-2.0 — see LICENSE

---

_{Part of the three.ws SDK suite — 3D AI agents, on-chain identity, and agent payments.
Website · Changelog · GitHub}