Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.
JavaScript 3d-generationai-agentsanimationavatardigital-humangenerative-aiglbgltfimage-to-3dllmmcpmcp-servermodel-context-protocolsolanatext-to-3dthreejsweb-componentswebglwebxrx402
#!/usr/bin/env node
// three-ws-assets: find a ready-made 3D asset on three.ws and put it in your
// project, with the code that renders it.
//
// Everything this CLI reads is free and public. There is no login, no API key,
// and no payment: the catalog it searches is the platform's published CC0 prop
// library, ready-made character library, and motion-clip library.
import { add } from './commands/add.js';
import { search } from './commands/search.js';
import { show } from './commands/show.js';
import { style, symbols, failure, hint } from './style.js';
const COMMANDS = {
search: {
run: search,
summary: 'Search the three.ws asset catalog',
usage: `${style.bold('three-ws-assets search')} ${style.dim('<terms…> [options]')}
Search every ready-made asset three.ws publishes: CC0 props, rigged
characters, and retargetable motion clips. Every word has to match, so a
two-word query stays precise; if nothing matches all of them you get the
partial matches with a warning rather than an empty list.
${style.bold('options')}
--kind <k> object | character | animation
--category <c> Exact category from a previous result
--tag <t> Exact tag from a previous result
--limit <n> 1..50 (default: 12)
--offset <n> Page offset (see "more:" in the output)
--json Raw JSON on stdout
--api <origin> Catalog origin (default: https://three.ws)
${style.dim('example')}
three-ws-assets search wooden chair --kind object`,
},
show: {
run: show,
summary: 'Print one item and the code that renders it',
usage: `${style.bold('three-ws-assets show')} ${style.dim('<id> [options]')}
Print an item's facts plus paste-ready source. Without --framework you get
the one that fits the item (model-viewer for a prop, agent-3d for a rigged
character, three for a motion clip) and the names of the others.
${style.bold('options')}
--framework <f> agent-3d | model-viewer | three | react
--json Raw JSON, including every framework's snippet
--api <origin> Catalog origin (default: https://three.ws)
${style.dim('example')}
three-ws-assets show object:painted_wooden_chair_01 --framework three`,
},
add: {
run: add,
summary: 'Download an asset into your project and print its snippet',
usage: `${style.bold('three-ws-assets add')} ${style.dim('<id> [options]')}
Download the GLB (or clip JSON) into your project and print the snippet
rewritten to point at the local copy. Files land in ${style.cyan('public/three-ws/')} when
the project has a public directory, otherwise ${style.cyan('three-ws-assets/')}.
A re-run that would write identical bytes reports the file as already up to
date. A file whose contents changed since it was added is never overwritten
without ${style.cyan('--force')}.
${style.bold('options')}
--dir <path> Where to write (default: public/three-ws)
--framework <f> agent-3d | model-viewer | three | react
--thumb Download the thumbnail too
--force Overwrite a file whose contents differ
--json Raw JSON: written paths, the local url, the snippet
--api <origin> Catalog origin (default: https://three.ws)
${style.dim('example')}
three-ws-assets add object:painted_wooden_chair_01 --thumb`,
},
};
function topHelp() {
const rows = Object.entries(COMMANDS)
.map(([name, c]) => ` ${style.cyan(name.padEnd(8))} ${c.summary}`)
.join('\n');
return `
${style.bold('three-ws-assets')} ${style.dim('<command> [options]')}
Ready-made 3D props, rigged characters, and motion clips from three.ws.
Free and public: no account, no API key, no payment.
${style.bold('commands')}
${rows}
${style.bold('global')}
--help, -h Show help (use ${style.cyan('<command> --help')} for command details)
--version, -V Print the CLI version
--no-color Disable colored output
--api <origin> Catalog origin, or set ${style.cyan('THREE_WS_API')}
${style.dim('quick start')}
${style.dim('three-ws-assets search wooden chair --kind object')}
${style.dim('three-ws-assets add object:painted_wooden_chair_01')}
${style.dim(`${symbols.arrow} docs: https://three.ws/docs/mcp ${symbols.bullet} issues: https://github.com/nirholas/three.ws/issues`)}
`;
}
export function parseArgs(argv) {
const args = { _: [], flags: {} };
for (let i = 0; i < argv.length; i++) {
const tok = argv[i];
if (tok === '--no-color') {
args.flags['no-color'] = true;
} else if (tok.startsWith('--')) {
const key = tok.slice(2);
const next = argv[i + 1];
if (next === undefined || next.startsWith('-')) {
args.flags[key] = true;
} else {
args.flags[key] = next;
i++;
}
} else if (tok.startsWith('-') && tok.length > 1) {
args.flags[tok.slice(1)] = true;
} else {
args._.push(tok);
}
}
return args;
}
/** Closest command name within edit distance 2, for "did you mean" hints. */
function suggestCommand(input) {
let best = null;
let bestDist = Infinity;
for (const name of Object.keys(COMMANDS)) {
const d = levenshtein(input, name);
if (d < bestDist) {
bestDist = d;
best = name;
}
}
return bestDist <= 2 ? best : null;
}
function levenshtein(a, b) {
const m = a.length;
const n = b.length;
const row = Array.from({ length: n + 1 }, (_, i) => i);
for (let i = 1; i <= m; i++) {
let prev = row[0];
row[0] = i;
for (let j = 1; j <= n; j++) {
const tmp = row[j];
row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
prev = tmp;
}
}
return row[n];
}
async function readVersion() {
const { readFileSync } = await import('node:fs');
const { fileURLToPath } = await import('node:url');
const { dirname, resolve } = await import('node:path');
const here = dirname(fileURLToPath(import.meta.url));
return JSON.parse(readFileSync(resolve(here, '../package.json'), 'utf8')).version;
}
export async function main(argv) {
const args = parseArgs(argv);
if (args.flags.version || args.flags.V) {
process.stdout.write(`${await readVersion()}\n`);
return 0;
}
const [command, ...rest] = args._;
const wantsHelp = args.flags.help || args.flags.h;
if (!command) {
process.stdout.write(topHelp());
return wantsHelp ? 0 : 1;
}
const entry = COMMANDS[command];
if (!entry) {
failure(`unknown command: ${style.bold(command)}`);
const guess = suggestCommand(command);
if (guess) hint(`did you mean "${guess}"?`);
hint('run "three-ws-assets --help" to see all commands');
return 1;
}
if (wantsHelp) {
process.stdout.write(`${entry.usage}\n`);
return 0;
}
return entry.run({ positional: rest, flags: args.flags });
}
/** Turn low-level Node errors into a one-line, human message. */
function describeError(err) {
switch (err?.code) {
case 'ENOENT':
return `file not found: ${err.path ?? err.message}`;
case 'EACCES':
return `permission denied: ${err.path ?? err.message}`;
case 'EISDIR':
return `expected a file but got a directory: ${err.path ?? err.message}`;
default:
return err?.message ?? String(err);
}
}
const isDirectInvocation = (() => {
if (typeof process === 'undefined' || !process.argv[1]) return false;
const entry = process.argv[1];
return entry.endsWith('cli.js') || entry.endsWith('three-ws-assets');
})();
if (isDirectInvocation) {
main(process.argv.slice(2))
.then((code) => process.exit(code ?? 0))
.catch((err) => {
failure(describeError(err));
process.exit(1);
});
}