@helix3/helix-cli 0.1.13-helix3.53 → 0.1.13-helix3.54

package/README.md

@@ -4,6 +4,12 @@
 backend. It shares bundle validation with the server via `@hypersoniclabs/helix-manifest`, so "validate passed but
 publish failed" can't happen for contract reasons.
 
+## Architecture boundary
+
+All creator feature and operational logic, validation, file mutation, network behavior, and tests
+live here. MCP packages may expose transport schemas, resources, instructions, and thin delegation
+to these commands, but must not reimplement this logic.
+
 ## Install
 
 ```bash
@@ -35,8 +41,14 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 | `helix init <dir>` | Scaffold a minimal Three.js world (`helix.json` + `index.html` + `main.js`). |
 | `helix install [--update]` | Resolve a world's `systems`/`abilities` pins (a v0.2 **or v0.3** manifest) → materialize the modules, the `three` import map, and `helix.runtime.ts`. |
 | `helix validate [dir]` | Validate a bundle locally — the exact rules the server enforces. |
-| `helix publish [dir]` | Validate → resolve/create the world → upload files → finalize → print the play URL. |
+| `helix publish [dir] [--thumbnail <file>]` | Validate → resolve/create the world → upload files → finalize → set the cover image → print the play URL. |
 | `helix list` | List your worlds. |
+| `helix item list-slots [--json]` | Print the Character-Creator vocabulary a wearable declares: the cosmetic slot tags, and the genders. |
+| `helix item publish <mesh.glb> --title <t> [--kind <k>] [--slot <tag>] [--gender <g>] [--price-lix <n> \| --personal] [--thumbnail <f>] [--dry-run]` | Publish a universal item (wearable / avatar / home item) from one `.glb`; the server verifies the mesh inline. |
+| `helix preview-video <slug> <youtube-url>` | Set or clear a published world's YouTube preview. |
+| `helix thumbnail set <slug> <file>` | Upload a thumbnail or preview image through the CLI-owned media path. |
+| `helix assets materials\|material\|search\|get\|install` | Discover platform materials and Vault assets, then install immutable assets with provenance receipts. |
+| `helix assets generate\|resume\|generate-image\|generate-audio\|generate-environment` | Run Dreamer asset generation and resume existing jobs. |
 | `helix doctor [--project <dir>]` | Print the environment + whether the @helix toolchain (CLI/MCP/SDK/manifest) is current. |
 
 ## Publish flow
@@ -51,8 +63,35 @@ The token is stored in `~/.helix/credentials.json` (mode `600`). It's sent as
 5. `POST /api/v1/instant-worlds/:id/builds/:buildId/finalize` → byte-exact verify, activate, publish.
 6. `GET /api/v1/instant-worlds/:slug` → the play URL.
 
-The programmatic surface (`publishWorld`, `checkBundle`, `whoAmI`, …) is exported from the package
-main, so an MCP server can drive the exact same code paths an agent would.
+The programmatic surface (`publishWorld`, `checkBundle`, `whoAmI`, …) is exported for other CLI
+modules. Agent integrations should instruct or delegate to the `helix` commands above rather than
+reimplementing operational behavior in a transport package.
+
+## Item publish flow
+
+`helix item publish` is a different shape from a world publish: one mesh, one round trip, an
+inline verdict — which is what an editor (Helix Studio) needs when an artist clicks Publish.
+
+1. Local validation, before anything leaves the machine: the `--kind`, the Character-Creator
+   `--slot` and `--gender` (**both required** for a wearable, exact-match), the title/slug/tag
+   limits, and the GLB container magic. `--dry-run` stops here and prints exactly what would be
+   sent.
+2. `POST /api/v1/universal-items/upload` — `multipart/form-data` with a `mesh` file part, an
+   optional `thumbnail` file part, and the metadata as ONE JSON string in `payload`.
+3. The server verifies the mesh **inline** (triangles, texture edges, materials, and — for a
+   wearable — whether it is a skinned garment or a rigid socketed accessory) and returns the
+   created item together with the verification verdict and warnings.
+
+The slot table in `src/item.ts` MIRRORS `helix-backend-api → src/universal-items/cc-wearable-slot.ts`,
+and the gender list mirrors `src/universal-items/cc-gender.ts` the same way. They are a local fast
+path so a typo costs no upload; the server remains the authority and its 400 lists every valid
+value. Adding a slot or a gender means editing both, in the same PR wave.
+
+`--gender` takes `male`, `female`, or `male,female`, and is **required** for `--kind wearable`.
+There is no `both`/`unisex`/`all`: Unreal's cosmetics enum has exactly Male and Female, so a garment
+that fits every body names both — one HELIX row with `{male, female}` is the web equivalent of
+Unreal's two entries sharing one mesh. The field goes on the wire as `genders`; `ccGenders` is the
+database column and the backend rejects it by name rather than dropping it in silence.
 
 ## Develop
 

package/dist/api.d.ts

@@ -18,6 +18,7 @@ export declare class HelixApi {
     setToken(token: string): void;
     request<T>(method: string, path: string, body?: unknown): Promise<T>;
     requestItem<T>(method: string, path: string, body?: unknown): Promise<T>;
+    postMultipart<T>(path: string, form: FormData): Promise<T>;
     static forCredentials(creds: CliCredentials): HelixApi;
 }
 export declare function uploadToTicket(url: string, body: Buffer, contentType: string, cacheControl?: string): Promise<void>;

package/dist/api.js

@@ -59,6 +59,26 @@ class HelixApi {
         const envelope = await this.request(method, path, body);
         return envelope.item;
     }
+    // multipart/form-data POST — for the endpoints that take file parts alongside
+    // JSON (universal-item uploads). Deliberately does NOT set content-type: the
+    // boundary is generated by the runtime and a hand-written header loses it,
+    // which the server sees as a malformed body. Uses Node's built-in FormData /
+    // Blob (globals since Node 18, same undici that already backs `fetch` above),
+    // so multipart needs no dependency.
+    async postMultipart(path, form) {
+        const res = await fetch(`${this.baseUrl}${path}`, {
+            method: 'POST',
+            headers: this.token ? { authorization: `Bearer ${this.token}` } : {},
+            body: form,
+        });
+        if (!res.ok) {
+            const problem = (await res.json().catch(() => ({})));
+            throw new ApiError(res.status, problem);
+        }
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
     static forCredentials(creds) {
         return new HelixApi(creds.apiUrl, creds.token);
     }

package/dist/api.js.map

@@ -1 +1 @@
-{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -230,19 +230,53 @@ program
     .command('publish')
     .description('Publish a world to HELIX Instant')
     .argument('[directory]', 'bundle directory', '.')
-    .action(async (directory) => {
+    .option('--thumbnail <file>', 'cover image (png, jpg/jpeg, webp, avif, or gif); otherwise uses thumbnail.<ext> at the bundle root')
+    .action(async (directory, opts) => {
     const creds = requireAuth();
     const mismatch = (0, config_1.credsEnvMismatchWarning)(creds.apiUrl);
     if (mismatch)
         fail(`✖ Refusing to publish:\n${mismatch}`);
     try {
-        const result = await (0, lib_1.publishWorld)((0, node_path_1.resolve)(directory), creds, (msg) => console.log(msg));
+        const result = await (0, lib_1.publishWorld)((0, node_path_1.resolve)(directory), creds, (msg) => console.log(msg), { thumbnail: opts.thumbnail ? (0, node_path_1.resolve)(opts.thumbnail) : undefined });
         console.log(`✔ Published "${result.title}" build ${result.buildNumber}`);
         if (result.playUrl)
             console.log(`  play: ${result.playUrl}`);
         console.log(`  api:  ${result.worldUrl}`);
-        if (!result.hasCustomThumbnail) {
-            console.log(`  • no custom thumbnail yet — run "helix screenshot" in this world's dir, then "helix thumbnail set ${result.slug} <file>"`);
+        if (result.thumbnailSource !== 'generated') {
+            console.log(`  cover: ${result.thumbnailSource}`);
+        }
+        if (result.thumbnailWarning)
+            console.warn(`  • ${result.thumbnailWarning}`);
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError
+            ? err.render()
+            : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+program
+    .command('preview-video')
+    .description("Set (or clear) a world's preview video from a YouTube link")
+    .argument('<slug>', 'world slug (as in `helix publish` / list-my-worlds)')
+    .argument('[url]', 'YouTube link — watch?v=, youtu.be, /embed/, /shorts/ or a bare video id. Omit with --clear.')
+    .option('--clear', "remove the world's preview video")
+    .action(async (slug, url, opts) => {
+    const creds = requireAuth();
+    // Video is referenced, never uploaded: the preview slot takes images only,
+    // and YouTube does the transcoding/streaming/moderation.
+    if (!opts.clear && !url)
+        fail('✖ Pass a YouTube link, or --clear to remove the video.');
+    try {
+        const result = opts.clear
+            ? await (0, lib_1.clearWorldPreviewVideo)(slug, creds)
+            : await (0, lib_1.setWorldPreviewVideo)(slug, url, creds);
+        if (result.previewYoutubeId) {
+            console.log(`✔ Preview video set for "${result.title}"`);
+            console.log(`  video: ${result.previewYoutubeId}`);
+            console.log(`  embed: ${result.previewYoutubeUrl}`);
+        }
+        else {
+            console.log(`✔ Preview video cleared for "${result.title}"`);
         }
     }
     catch (err) {
@@ -270,6 +304,369 @@ program
             : `✖ ${err instanceof Error ? err.message : String(err)}`);
     }
 });
+// --- helix item ------------------------------------------------------------
+// Universal items (wearables, avatars, home items) uploaded straight from a DCC
+// export — the surface Helix Studio drives. Publishing an item is not
+// publishing a world: one mesh, one multipart round trip, an inline verdict.
+const item = program
+    .command('item')
+    .description('Universal items — publish a wearable / avatar / home item from a .glb');
+// One command prints the whole Character-Creator vocabulary a wearable must
+// declare — the 34 slot tags AND the two genders. There is no `list-genders`:
+// a dedicated command for a closed two-value list is a command to discover, to
+// document and to keep in sync, for information that fits on one line under the
+// list it is always read with. `--gender`'s own help carries the same values.
+item
+    .command('list-slots')
+    .description('Print the Character-Creator vocabulary a wearable declares: the cosmetic slot tags, and the genders')
+    .option('--json', 'machine-readable output')
+    .action((opts) => {
+    if (opts.json) {
+        console.log(JSON.stringify({ slots: lib_1.CC_WEARABLE_SLOT_GROUPS, genders: lib_1.CC_GENDERS }, null, 2));
+        return;
+    }
+    console.log('Character-Creator cosmetic slots — pass one to `helix item publish --slot`.');
+    console.log('Tags match EXACTLY, including case.\n');
+    console.log((0, lib_1.renderCcSlotTable)());
+    console.log('\nGenders — pass to `helix item publish --gender`, REQUIRED for a wearable.');
+    console.log(`  ${(0, lib_1.renderCcGenderList)()}`);
+});
+function parseItemKind(value) {
+    if (!(0, lib_1.isUploadableItemKind)(value)) {
+        fail(`✖ --kind must be one of ${lib_1.UPLOADABLE_ITEM_KINDS.join(', ')}, got '${value}'`);
+    }
+    return value;
+}
+function parsePriceLix(value) {
+    const price = Number(value);
+    if (!Number.isFinite(price))
+        fail(`✖ --price-lix must be a number, got '${value}'`);
+    return price;
+}
+item
+    .command('publish')
+    .description('Publish a universal item from a local .glb — the server verifies the mesh inline and returns the verdict in the same round trip')
+    .argument('<mesh>', 'the item mesh (binary glTF, .glb)')
+    .requiredOption('--title <title>', 'display title')
+    .option('--kind <kind>', `item kind: ${lib_1.UPLOADABLE_ITEM_KINDS.join(' | ')}`, 'wearable')
+    .option('--slot <tag>', 'Character-Creator cosmetic slot, REQUIRED for a wearable (see: helix item list-slots)')
+    // Comma form, not a repeated flag and not a `both` alias. The repo already
+    // spells "a list" as one comma-separated value (--tags a,b,c / --views a,b /
+    // --lod-tris a,b,c) and has no repeatable option anywhere, and the backend's
+    // own multipart field takes the identical "male,female" string — so this adds
+    // no vocabulary and no mechanism. A `both` alias was rejected: it would be a
+    // token the API does not have, and the server's errors name `male`/`female`.
+    .option('--gender <male|female|male,female>', 'Character-Creator gender(s) the item is authored for, REQUIRED for a wearable; a garment that fits every body passes male,female')
+    .option('--slug <slug>', 'url slug (default: derived from the title)')
+    .option('--description <text>', 'item description')
+    .option('--thumbnail <file>', 'thumbnail image (png/jpg/webp); rendered from the mesh when omitted, required for an avatar')
+    .option('--price-lix <n>', 'list on the marketplace at this LIX price (charges a non-refundable publish fee)')
+    .option('--personal', 'keep it private and free instead of listing it (no publish fee)')
+    .option('--tags <a,b,c>', 'comma-separated search keywords')
+    .option('--allow-oversize', 'relax the mesh size/polycount ceilings for a deliberately heavy asset')
+    .option('--dry-run', 'validate everything locally and print what WOULD be sent; no upload, no fee')
+    .option('--json', 'machine-readable output')
+    .action(async (mesh, opts) => {
+    const publishOptions = {
+        mesh: (0, node_path_1.resolve)(mesh),
+        thumbnail: opts.thumbnail ? (0, node_path_1.resolve)(opts.thumbnail) : undefined,
+        kind: parseItemKind(opts.kind),
+        title: opts.title,
+        slot: opts.slot,
+        genders: opts.gender !== undefined ? (0, lib_1.parseGenders)(opts.gender) : undefined,
+        slug: opts.slug,
+        description: opts.description,
+        priceLix: opts.priceLix !== undefined ? parsePriceLix(opts.priceLix) : null,
+        keepPersonal: opts.personal === true,
+        tags: opts.tags !== undefined ? (0, lib_1.parseTags)(opts.tags) : undefined,
+        allowOversize: opts.allowOversize === true,
+    };
+    // --dry-run stops before ANY network call, so it works logged out — the
+    // point is to check the mesh and the metadata, not the account.
+    if (opts.dryRun) {
+        try {
+            const plan = (0, lib_1.planItemPublish)(publishOptions);
+            if (opts.json) {
+                console.log(JSON.stringify({
+                    dryRun: true,
+                    endpoint: plan.endpoint,
+                    payload: plan.payload,
+                    mesh: plan.mesh,
+                    thumbnail: plan.thumbnail,
+                    warnings: plan.warnings,
+                }, null, 2));
+                return;
+            }
+            console.log(`✔ Dry run — nothing uploaded, no fee charged.`);
+            console.log(`  POST ${plan.endpoint}`);
+            console.log(`  mesh:      ${plan.mesh.file} (${(plan.mesh.sizeBytes / 1024).toFixed(1)} KiB, ${plan.mesh.contentType})`);
+            console.log(`  thumbnail: ${plan.thumbnail ? `${plan.thumbnail.file} (${(plan.thumbnail.sizeBytes / 1024).toFixed(1)} KiB, ${plan.thumbnail.contentType})` : '(none — server-rendered)'}`);
+            console.log(`  payload:   ${JSON.stringify(plan.payload, null, 2).replace(/\n/g, '\n             ')}`);
+            for (const warning of plan.warnings)
+                console.log(`  • ${warning}`);
+            const status = (0, lib_1.authStatus)();
+            if (!status.loggedIn)
+                console.log('  • not logged in — run `helix login` before the real publish');
+        }
+        catch (err) {
+            fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return;
+    }
+    const creds = requireAuth();
+    const mismatch = (0, config_1.credsEnvMismatchWarning)(creds.apiUrl);
+    if (mismatch)
+        fail(`✖ Refusing to publish:\n${mismatch}`);
+    try {
+        const result = await (0, lib_1.publishItem)(publishOptions, creds, {
+            onProgress: (msg) => !opts.json && console.log(msg),
+        });
+        if (opts.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log(`✔ Published ${result.kind} "${result.title}" (${result.slug})`);
+        if (result.slot)
+            console.log(`  slot:   ${result.slot}`);
+        // Echoed from the SERVER's row, not from what was sent — so a value the
+        // server normalised, dropped or never stored is visible here.
+        if (result.genders.length)
+            console.log(`  gender: ${result.genders.join(', ')}`);
+        console.log(`  status: ${result.status}`);
+        console.log(result.priceLix === null
+            ? '  price:  (personal — not listed)'
+            : `  price:  ${result.priceLix} LIX (publish fee ${result.publishFeeLix} LIX)`);
+        console.log(`  id:     ${result.id}`);
+        for (const warning of result.verification.warnings)
+            console.log(`  ⚠ ${warning}`);
+    }
+    catch (err) {
+        fail(err instanceof lib_1.ApiError
+            ? err.render()
+            : `✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+// --- helix assets ----------------------------------------------------------
+// Operational asset work lives here. MCP surfaces may point agents at these
+// commands, but they must not reimplement Vault, Dreamer, download, or receipt
+// behavior in the transport package.
+const assets = program
+    .command('assets')
+    .description('Discover, install, and generate HELIX platform assets');
+function optionalNumber(value, name) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        fail(`✖ ${name} must be a number, got '${value}'`);
+    return parsed;
+}
+function commaList(value) {
+    const values = value
+        ?.split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+    return values?.length ? values : undefined;
+}
+function printJson(value) {
+    console.log(JSON.stringify(value, null, 2));
+}
+assets
+    .command('materials')
+    .description('Search the versioned HELIX material catalog')
+    .option('-q, --query <text>', 'search id, name, category, and tags')
+    .option('--category <category>', 'exact material category')
+    .option('--limit <n>', 'maximum results')
+    .action(async (opts) => {
+    try {
+        printJson(await (0, lib_1.listMaterials)(config_1.DEFAULT_API_URL, {
+            q: opts.query,
+            category: opts.category,
+            limit: optionalNumber(opts.limit, '--limit'),
+        }));
+    }
+    catch (err) {
+        fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+assets
+    .command('material')
+    .description('Resolve one material id to its immutable map URLs')
+    .argument('<id>', 'material id from `helix assets materials`')
+    .action(async (id) => {
+    try {
+        printJson(await (0, lib_1.resolveMaterial)(config_1.DEFAULT_API_URL, id));
+    }
+    catch (err) {
+        fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+assets
+    .command('search')
+    .description('Search reusable HELIX Vault assets')
+    .argument('[query]', 'free-text search')
+    .option('--kind <a,b>', 'comma-separated kinds')
+    .option('--skeleton <id>', 'required skeleton')
+    .option('--engine <engine>', 'target engine')
+    .option('--license <license>', 'license filter')
+    .option('--source <source>', 'source filter')
+    .option('--origin <origin>', 'origin/provenance filter')
+    .option('--creator-id <id>', 'creator id')
+    .option('--page <n>', 'page number')
+    .option('--limit <n>', 'page size')
+    .action(async (query, opts) => {
+    const creds = (0, config_1.loadCredentials)();
+    const apiUrl = creds?.apiUrl ?? config_1.DEFAULT_API_URL;
+    try {
+        printJson(await (0, lib_1.searchVaultAssets)(apiUrl, {
+            q: query,
+            kind: commaList(opts.kind),
+            skeleton: opts.skeleton,
+            engine: opts.engine,
+            license: opts.license,
+            source: opts.source,
+            origin: opts.origin,
+            creatorId: opts.creatorId,
+            page: optionalNumber(opts.page, '--page'),
+            limit: optionalNumber(opts.limit, '--limit'),
+        }, creds ?? undefined));
+    }
+    catch (err) {
+        fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+assets
+    .command('get')
+    .description('Read one HELIX Vault asset')
+    .argument('<asset-id>', 'Vault asset UUID')
+    .action(async (assetId) => {
+    const creds = (0, config_1.loadCredentials)();
+    const apiUrl = creds?.apiUrl ?? config_1.DEFAULT_API_URL;
+    try {
+        printJson(await (0, lib_1.getVaultAsset)(apiUrl, assetId, creds ?? undefined));
+    }
+    catch (err) {
+        fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+assets
+    .command('install')
+    .description('Install one Vault artifact into a world and write its provenance receipt')
+    .argument('<asset-id>', 'Vault asset UUID')
+    .option('-C, --world <dir>', 'world project directory', '.')
+    .action(async (assetId, opts) => {
+    const creds = (0, config_1.loadCredentials)();
+    const apiUrl = creds?.apiUrl ?? config_1.DEFAULT_API_URL;
+    try {
+        printJson(await (0, lib_1.installVaultAsset)((0, node_path_1.resolve)(opts.world), apiUrl, assetId, creds ?? undefined));
+    }
+    catch (err) {
+        fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+assets
+    .command('generate')
+    .description('Generate and publish a new prop or character through Dreamer')
+    .argument('<kind>', 'prop or character')
+    .argument('<prompt>', 'asset prompt')
+    .option('--title <title>', 'asset title')
+    .option('--additional-prompt <text>', 'additional generation guidance')
+    .option('--target-polycount <n>', 'target triangle count')
+    .option('--visibility <visibility>', 'public, unlisted, or private', 'public')
+    .action(async (kind, prompt, opts) => {
+    if (kind !== 'prop' && kind !== 'character') {
+        fail(`✖ kind must be prop or character, got '${kind}'`);
+    }
+    if (!['public', 'unlisted', 'private'].includes(opts.visibility)) {
+        fail(`✖ --visibility must be public, unlisted, or private`);
+    }
+    const creds = requireAuth();
+    try {
+        printJson(await (0, lib_1.generateAndPublishAsset)(creds, {
+            kind,
+            prompt,
+            title: opts.title,
+            additionalPrompt: opts.additionalPrompt,
+            targetPolycount: optionalNumber(opts.targetPolycount, '--target-polycount'),
+        }, {
+            visibility: opts.visibility,
+        }));
+    }
+    catch (err) {
+        fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+assets
+    .command('resume')
+    .description('Resume and publish an existing Dreamer asset job')
+    .argument('<job-id>', 'Dreamer job id')
+    .option('--visibility <visibility>', 'public, unlisted, or private', 'public')
+    .action(async (jobId, opts) => {
+    if (!['public', 'unlisted', 'private'].includes(opts.visibility)) {
+        fail(`✖ --visibility must be public, unlisted, or private`);
+    }
+    const creds = requireAuth();
+    try {
+        printJson(await (0, lib_1.resumeAndPublishAsset)(creds, jobId, {
+            visibility: opts.visibility,
+        }));
+    }
+    catch (err) {
+        fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+assets
+    .command('generate-image')
+    .description('Generate a standalone image through Dreamer')
+    .argument('<prompt>', 'image prompt')
+    .option('--additional-prompt <text>', 'additional generation guidance')
+    .option('--project-id <id>', 'Dreamer project id')
+    .action(async (prompt, opts) => {
+    const creds = requireAuth();
+    try {
+        printJson(await (0, lib_1.generateImage)(creds, {
+            prompt,
+            additionalPrompt: opts.additionalPrompt,
+            projectId: opts.projectId,
+        }));
+    }
+    catch (err) {
+        fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+    }
+});
+for (const generation of [
+    { command: 'generate-audio', kind: 'audio' },
+    { command: 'generate-environment', kind: 'gaussian_splat' },
+]) {
+    assets
+        .command(generation.command)
+        .description(generation.kind === 'audio'
+        ? 'Generate standalone audio through Dreamer'
+        : 'Generate an experimental Gaussian-splat environment through Dreamer')
+        .argument('<prompt>', 'generation prompt')
+        .option('--additional-prompt <text>', 'additional generation guidance')
+        .option('--project-id <id>', 'Dreamer project id')
+        .option('--title <title>', 'asset title')
+        .option('--loop', 'request loopable output (audio)')
+        .option('--duration-seconds <n>', 'requested duration (audio)')
+        .action(async (prompt, opts) => {
+        const creds = requireAuth();
+        try {
+            printJson(await (0, lib_1.generateStandaloneAsset)(creds, {
+                kind: generation.kind,
+                prompt,
+                additionalPrompt: opts.additionalPrompt,
+                projectId: opts.projectId,
+                title: opts.title,
+                loop: opts.loop,
+                durationSeconds: optionalNumber(opts.durationSeconds, '--duration-seconds'),
+            }));
+        }
+        catch (err) {
+            fail(`✖ ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}
 async function printCatalog(kind, system, apiUrlOpt) {
     const apiUrl = apiUrlOpt ?? (0, config_1.loadCredentials)()?.apiUrl ?? config_1.DEFAULT_API_URL;
     try {