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-clibrings 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.
# 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 --helpThe binary is three-ws-avatar. --version prints the package version; --help /
-h prints usage.
# 1. Grab a real rigged avatar to work with (or point --mesh at your own GLB)
curl -sLO https://three.ws/avatars/michelle.glb
# 2. Scaffold a manifest from your wallet + mesh (sha256 + size computed for you)
three-ws-avatar init \
--owner eip155:1:0x742d35Cc6634C0532925a3b844Bc454e4438f44e \
--name "Nicholas" \
--mesh ./michelle.glb \
--skeleton mixamo \
--out manifest.json
# → ok wrote /…/manifest.json (validated against @three-ws/avatar-schema before writing)
# plus a summary line for id, skeleton, and mesh (format · size · sha256)
# 3. Validate it
three-ws-avatar validate manifest.json
# → ok manifest.json is valid
# 4. Print embed snippets
three-ws-avatar preview manifest.json
# → resolver URL, <agent-3d> element + loader, and <iframe> snippet| 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 + an embeddable <agent-3d> snippet (with its loader) and an <iframe> snippet. |
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.
three-ws-avatar validate manifest.json # → ok manifest.json is valid
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).
sha=$(three-ws-avatar hash ./michelle.glb)
echo "$sha"
# 28d788538f7b22b8e00c1d715fffc380bb06a304613d522c20523d3d6ff79bc2--json emits { "path", "sha256", "bytes" } instead of the bare hex line.
three-ws-avatar preview manifest.jsonPrints three things:
- The resolver URL,
https://three.ws/a/{id} - An
<agent-3d>web-component snippet, together with the loader<script>that registers the element. Both lines are printed because<agent-3d>is an ordinary unknown element until that script runs, so the snippet is only complete with both. - A zero-install
<iframe>embed snippet
When mesh.uri is still a local file:// path, preview warns instead of printing a
snippet no browser can load. Pass --mesh-uri to init to set a public URL.
Use --viewer http://localhost:3000 to target a local dev viewer, or --json for
machine-readable output
({ id, resolverUrl, loader, element, iframe, meshUri, meshIsLocal, schemaVersion }).
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 ./michelle.glb)
[ "$expected" = "$actual" ] || { echo "mesh hash mismatch"; exit 1; }
# Gate every manifest change on schema validity.
three-ws-avatar validate manifest.json- Node
>=18. - Bundled dependency:
@three-ws/avatar-schema(used to validate every scaffolded and checked manifest).
@three-ws/avatar-schema- the manifest format this CLI scaffolds and validates.@three-ws/avataris the runtime SDK behind the<agent-3d>element thepreviewsnippets embed.
- 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
Part of three.ws, the open-source platform for 3D AI agents. This repository is exported from the monorepo, which is the source of truth: open issues here, and send larger changes there.
If three-ws-avatar-cli saves you time, star it on GitHub. Stars are how other developers and AI agents find the repositories worth trusting, and they cost you one click.
Know someone who would use it? Post on X · Share on Bluesky · Share on LinkedIn · Submit to Hacker News · Share on Reddit
Coding agents and LLM tooling can read this repo directly: AGENTS.md, llms.txt, llms-full.txt. Point an agent at https://github.com/nirholas/three-ws-avatar-cli and it has the context it needs.
- All repositories by nirholas: the full catalog, grouped by topic
- three.ws: the platform for 3D AI agents with Solana wallets, a skill marketplace and x402 payments
- Questions or ideas: open an issue or start a discussion