@worldlabsai/cli 0.1.0 → 0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 Use the World Labs Developer API from a terminal or coding agent with a manually issued API key. The published package has zero npm runtime dependencies; the public SDK is bundled.
 
-With Node 24 or newer, install the CLI and configure your key:
+With Node 22 or newer, install the CLI and configure your key:
 
 ```sh
 npm install -g @worldlabsai/cli && worldlabs setup
@@ -10,7 +10,7 @@ npm install -g @worldlabsai/cli && worldlabs setup
 
 On Windows, run these commands in Command Prompt.
 
-`setup` opens the API keys page, prompts you to paste a new key without echoing it, validates it with `assets.list`, and saves it in a plaintext file in your user configuration directory. It can also install the general skill for Codex or Claude Code; you can skip skill installation. Use `worldlabs setup --help` for options.
+`setup` opens the API keys page, prompts you to paste a new key without echoing it, validates it with `assets.list`, and saves it in a plaintext file in your user configuration directory. It can also install the World Labs skill for a coding agent. Use `worldlabs setup --help` for options.
 
 ## Onboarding
 
@@ -21,7 +21,7 @@ flowchart TD
     C --> D[Paste key into hidden prompt]
     D --> E[Validate with assets.list]
     E --> F[Save credentials file]
-    F --> G[Optionally install Codex or Claude Code skill]
+    F --> G[Optionally install the World Labs skill for your coding agent]
     F --> H[Upload assets and run tasks]
 ```
 
@@ -29,20 +29,20 @@ On the API keys page, choose only the scopes required for your work: task submis
 
 ## Commands
 
-| Command                                                                                     | Purpose                                                                                                                          |
-| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `setup [--client codex\|claude-code]`                                                       | Configure the API key and optionally install the agent skill. Without `--client`, noninteractive setup skips skill installation. |
-| `auth login [--no-browser]`                                                                 | Open the API keys page, or print its URL for manual opening.                                                                     |
-| `auth status`                                                                               | Check the key through `assets.list` without printing it. This does not validate every generation scope.                          |
-| `auth logout`                                                                               | Remove the locally stored key. Revoke the key on the website to invalidate it.                                                   |
-| `tasks list`                                                                                | List tasks available through the public SDK.                                                                                     |
-| `tasks run <name> --request file.json [--idempotency-key key] [--wait] [--timeout seconds]` | Submit a task request; optionally wait for its operation. Some SDK tasks require beta entitlement.                               |
-| `assets upload file [--mime type]`                                                          | Upload a local file.                                                                                                             |
-| `assets download id --out file`                                                             | Download an asset to a local path.                                                                                               |
-| `assets list [--page-token token]`                                                          | List accessible assets.                                                                                                          |
-| `operations get id`                                                                         | Read an operation.                                                                                                               |
-| `operations wait id [--timeout seconds]`                                                    | Poll an operation until it finishes or the timeout expires. The default timeout is 600 seconds.                                  |
-| `skills install\|uninstall --client codex\|claude-code`                                     | Install or remove the general agent skill.                                                                                       |
+| Command                                                                                     | Purpose                                                                                                 |
+| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `setup [--client <agent>] [--api-key-stdin] [--yes]`                                        | Configure the API key and optionally install the World Labs skill. `--yes` accepts installer prompts.   |
+| `auth login [--no-browser] [--api-key-stdin]`                                               | Open the API keys page, or print its URL for manual opening. `--api-key-stdin` reads a piped key.       |
+| `auth status`                                                                               | Check the key through `assets.list` without printing it. This does not validate every generation scope. |
+| `auth logout`                                                                               | Remove the locally stored key. Revoke the key on the website to invalidate it.                          |
+| `tasks list`                                                                                | List tasks available through the public SDK.                                                            |
+| `tasks run <name> --request file.json [--idempotency-key key] [--wait] [--timeout seconds]` | Submit a task request; optionally wait for its operation. Some SDK tasks require beta entitlement.      |
+| `assets upload file [--mime type]`                                                          | Upload a local file.                                                                                    |
+| `assets download id --out file`                                                             | Download an asset to a local path.                                                                      |
+| `assets list [--page-token token]`                                                          | List accessible assets.                                                                                 |
+| `operations get id`                                                                         | Read an operation.                                                                                      |
+| `operations wait id [--timeout seconds]`                                                    | Poll an operation until it finishes or the timeout expires. The default timeout is 600 seconds.         |
+| `skills install\|uninstall [--client <agent>] [--yes]`                                      | Install or remove the World Labs skill globally. `--yes` accepts installer prompts.                     |
 
 Use `--request -` to read task JSON from standard input. Results go to stdout; diagnostics go to stderr, so a result can be saved without mixing in progress messages:
 
@@ -50,19 +50,60 @@ Use `--request -` to read task JSON from standard input. Results go to stdout; d
 worldlabs tasks run atlasGenerate --request - --wait --json < request.json > result.json
 ```
 
-Use `--json` for machine-readable output. Task submission generates an idempotency key and prints it to stderr before sending the request. Save that value and pass it back with `--idempotency-key` to retry an uncertain submission. The bundled `@worldlabsai/client-next` SDK handles API retries and operation polling.
+Use `--json` for machine-readable output. Task submission generates an idempotency key and prints it to stderr before sending the request. Save that value and pass it back with `--idempotency-key` to retry an uncertain submission. The bundled `@worldlabsai/client` SDK handles API retries and operation polling.
 
-Skill updates and removal refuse to change a directory with local edits or unrelated files. Move a customized `worldlabs` skill aside before reinstalling.
+## Install agent skills
 
-The installed skill includes task descriptions and an upload/submit/result example. It points to
-[How To Use Atlas](https://marble5.worldlabs.ai/docs/how-to-use-atlas) for maintained guidance on model inputs, cameras, and task combinations.
+Install the World Labs skill from [worldlabsai/skills](https://github.com/worldlabsai/skills)
+using [Skills CLI](https://skills.sh). Installation is global and requires
+network access, npm, and Git. The installer detects available agents and handles
+client selection:
+
+```sh
+worldlabs skills install
+```
+
+To choose an agent directly, pass `--client`:
+
+```sh
+worldlabs skills install --client cursor
+worldlabs skills install --client gemini-cli
+```
+
+Pass `--yes` to accept installer prompts. Run the install command again to
+refresh the World Labs skill. To remove it, select the agent you installed it
+for:
+
+```sh
+worldlabs skills uninstall --client cursor
+```
+
+Start a new agent session after installation to load the skill. Older
+CLI-managed installations are moved to a local backup, whose path is printed
+in the terminal. If installation fails or is cancelled, the CLI waits for the
+installer to stop, then restores the old skill unless
+the installer has already written a replacement; in that case, it keeps both
+copies and reports the backup path. If an older installation has local edits,
+installation stops and leaves it in place.
+
+If the CLI cannot confirm that the installer has stopped, it retains the backup
+without restoring it. Stop any remaining installer processes before restoring
+that backup manually.
+
+The public skill points to [How To Use Atlas](https://docs.atlas-beta.worldlabs.ai/how-to-use-atlas) for maintained guidance on model inputs, cameras, and task combinations.
 
 ## Configuration
 
 The CLI uses `https://api.atlas-beta.worldlabs.ai` by default. Saved keys live in separate files per API origin under `~/.config/worldlabs/credentials/`. On macOS/Linux, new directories use mode `700` and new files use mode `600`. On Windows, files inherit the directory permissions. Keys are plaintext, so programs running as your user can read them. `auth status` shows the saved file location.
 
-Set `WORLDLABS_CONFIG_DIR` to use another configuration directory, such as a temporary directory for tests. Keep it outside repositories. `WLT_API_KEY` takes precedence over saved keys for automation. Generated Windows skill commands use PowerShell.
+Set `WORLDLABS_CONFIG_DIR` to use another configuration directory, such as a temporary directory for tests. Keep it outside repositories. `WLT_API_KEY` takes precedence over saved keys for automation.
+
+To save a key without the hidden prompt, for example from a secret manager or where no one can type into the terminal, pipe it to `--api-key-stdin`. The CLI checks it and saves it like `auth login`; the key stays out of the command line and shell history:
+
+```sh
+worldlabs auth login --api-key-stdin < key.txt
+```
 
 For development or a nonproduction deployment, set `WORLDLABS_API_ORIGIN` and, when needed, `WORLDLABS_API_KEYS_URL`. The key page defaults to `https://atlas-beta.worldlabs.ai/api-keys`. Do not commit credentials, client IDs, or nonproduction hostnames.
 
-See the [World Labs CLI skill](skills/worldlabs/SKILL.md).
+See the [World Labs skill](https://github.com/worldlabsai/skills).

package/dist/index.js

@@ -4,6 +4,14 @@
 import { readFileSync } from "node:fs";
 import { parseArgs as parseArgs2 } from "node:util";
 
+// ../client/dist/core/network-error.js
+var NetworkError = class extends TypeError {
+  name = "NetworkError";
+  constructor(cause) {
+    super(cause.message, { cause });
+  }
+};
+
 // ../client/dist/core/sleep.js
 var sleep = async (ms, signal) => {
   if (signal?.aborted) {
@@ -21,6 +29,11 @@ var sleep = async (ms, signal) => {
 };
 
 // ../client/dist/core/transport.js
+var validationIssue = (issue) => {
+  const location = typeof issue === "object" && issue !== null ? Reflect.get(issue, "loc") : void 0;
+  const message = typeof issue === "object" && issue !== null ? Reflect.get(issue, "msg") : issue;
+  return Array.isArray(location) ? `${location.join(".")}: ${String(message)}` : String(message);
+};
 var errorDetail = (body) => {
   if (typeof body !== "object" || body === null) {
     return void 0;
@@ -30,6 +43,9 @@ var errorDetail = (body) => {
     if (typeof value === "string" && value !== "") {
       return value;
     }
+    if (Array.isArray(value) && value.length > 0) {
+      return value.map((issue) => validationIssue(issue)).join("; ");
+    }
   }
   return void 0;
 };
@@ -56,35 +72,36 @@ var fillPath = (path, params) => path.replaceAll(/\{(?<name>\w+)\}/gu, (_, name)
   }
   return encodeURIComponent(value);
 });
-var compose = (middleware, fetch2) => {
+var compose = (middleware, fetch2, options) => {
   let next = fetch2;
   for (const layer of middleware.toReversed()) {
     const inner = next;
-    next = async (request) => await layer(request, inner);
+    next = async (request) => await layer(request, inner, options);
   }
   return next;
 };
 var parseBody = async (response) => {
-  const text2 = await response.text();
-  if (text2 === "") {
+  const text3 = await response.text();
+  if (text3 === "") {
     return void 0;
   }
   try {
-    return JSON.parse(text2);
+    return JSON.parse(text3);
   } catch {
-    return text2;
+    return text3;
   }
 };
 var RETRYABLE_STATUS_CODES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
-var retryDelay = (error, attempt) => {
-  const backoff = 1e3 * 2 ** attempt * (0.5 + Math.random() / 2);
+var MAX_RETRY_AFTER_MS = 1e4;
+var retryAfterMs = (error) => {
   const value = error instanceof ApiError ? error.response.headers.get("retry-after")?.trim() : void 0;
   if (!value) {
-    return backoff;
+    return void 0;
   }
   const delay = /^\d+$/u.test(value) ? Number(value) * 1e3 : Date.parse(value) - Date.now();
-  return Math.max(backoff, Number.isFinite(delay) ? delay : 0);
+  return Number.isFinite(delay) ? Math.max(0, delay) : void 0;
 };
+var retryDelay = (error, attempt) => Math.max(1e3 * 2 ** attempt * (0.5 + Math.random() / 2), retryAfterMs(error) ?? 0);
 var createTransport = (options) => {
   const fetch2 = options.fetch ?? (async (request) => await globalThis.fetch(request));
   const send = compose(options.middleware ?? [], fetch2);
@@ -93,7 +110,8 @@ var createTransport = (options) => {
   return {
     fetch: fetch2,
     send,
-    request: async (path, { body, params, query, retry = false, ...init } = {}) => {
+    request: async (path, requestOptions = {}) => {
+      const { body, params, query, retry = false, ...init } = requestOptions;
       const url = new URL(baseUrl + fillPath(path, { ...boundParams, ...params }));
       for (const [key, value] of Object.entries(query ?? {})) {
         if (value !== void 0 && value !== null) {
@@ -110,14 +128,14 @@ var createTransport = (options) => {
         ...body === void 0 ? {} : { body: JSON.stringify(body) }
       });
       let networkError;
-      const sendRequest = retry ? compose(options.middleware ?? [], async (attempt) => {
+      const sendRequest = compose(options.middleware ?? [], async (attempt) => {
         try {
           return await fetch2(attempt);
         } catch (error) {
           networkError = error;
           throw error;
         }
-      }) : send;
+      }, requestOptions);
       for (let attempt = 0; ; attempt += 1) {
         request.signal.throwIfAborted();
         networkError = void 0;
@@ -139,8 +157,11 @@ var createTransport = (options) => {
           return parsed;
         } catch (error) {
           request.signal.throwIfAborted();
-          const transient = error instanceof ApiError ? RETRYABLE_STATUS_CODES.has(error.response.status) : error instanceof TypeError && error === networkError;
+          const networkFailure = error instanceof TypeError && error === networkError;
+          const transient = error instanceof ApiError ? RETRYABLE_STATUS_CODES.has(error.response.status) && (retryAfterMs(error) ?? 0) <= MAX_RETRY_AFTER_MS : networkFailure;
           if (!retry || attempt >= 3 || !transient) {
+            if (networkFailure)
+              throw new NetworkError(error);
             throw error;
           }
           await sleep(retryDelay(error, attempt), request.signal);
@@ -281,6 +302,7 @@ var createOperations = (transport, operationPath2) => {
      *
      * An operation can finish with an API-reported task error; inspect `error` before
      * reading `response`. Aborting stops local waiting without canceling the task.
+     * With `retryNetworkErrors`, network failures resume polling until cancellation.
      * HTTP 502, 503, and 504 polling failures are retried up to three times in a row;
      * a successful poll resets the retry count.
      *
@@ -303,6 +325,9 @@ var createOperations = (transport, operationPath2) => {
           gatewayErrors = 0;
           return current;
         } catch (error) {
+          signal?.throwIfAborted();
+          if (options?.retryNetworkErrors && error instanceof NetworkError)
+            return operation;
           gatewayErrors += 1;
           if (!(error instanceof ApiError) || ![502, 503, 504].includes(error.response.status) || gatewayErrors > 3) {
             throw error;
@@ -315,7 +340,7 @@ var createOperations = (transport, operationPath2) => {
 };
 
 // ../client/dist/core/tasks.js
-var submitTask = async (transport, path, body, { idempotencyKey = crypto.randomUUID(), signal, wait } = {}) => {
+var submitTask = async (transport, path, body, { idempotencyKey = crypto.randomUUID(), signal, wait, retry = true } = {}) => {
   if (idempotencyKey.trim() === "") {
     throw new Error("Idempotency key must not be empty");
   }
@@ -324,7 +349,7 @@ var submitTask = async (transport, path, body, { idempotencyKey = crypto.randomU
     headers: { "Idempotency-Key": idempotencyKey },
     method: "POST",
     query: { wait },
-    retry: true,
+    retry,
     ...signal ? { signal } : {}
   });
 };
@@ -393,6 +418,18 @@ var createTasks = (transport) => ({
    * @beta Requires beta access for your account.
    */
   images2PosedRGBD: async (body, options) => await submitTask(transport, "/api/v2/tasks:images2PosedRGBD", body, options),
+  /**
+   * Submit the posedImages2Splats task
+   * Retries network failures and HTTP 429/502/503/504 up to three times with the same key and body.
+   *
+   * @param body - Task inputs and settings.
+   * @param options - Abort signal, idempotency key, and server-wait preference.
+   * @returns An operation to pass to `client.operations.wait` for the typed result.
+   * Check the completed operation's `error` before reading its `response`.
+   * @throws {ApiError} If the API rejects the submission or retries are exhausted.
+   * @beta Requires beta access for your account.
+   */
+  posedImages2Splats: async (body, options) => await submitTask(transport, "/api/v2/tasks:posedImages2Splats", body, options),
   /**
    * Submit the splats2Mesh task
    * Retries network failures and HTTP 429/502/503/504 up to three times with the same key and body.
@@ -429,6 +466,9 @@ var createClient = (options) => {
   };
 };
 
+// src/auth.ts
+import { text } from "node:stream/consumers";
+
 // src/config.ts
 var CliError = class extends Error {
   name = "CliError";
@@ -529,13 +569,20 @@ async function prompt(message, hidden = false) {
     terminal: true
   });
   const controller = new AbortController();
-  reader.once("SIGINT", () => controller.abort());
+  let interrupted = false;
+  reader.once("SIGINT", () => {
+    interrupted = true;
+    controller.abort();
+  });
+  reader.once("close", () => controller.abort());
   process.stderr.write(message);
   try {
     const answer = await reader.question("", { signal: controller.signal });
     return answer.trim();
   } catch {
-    throw new CliError("Cancelled.");
+    throw new CliError(
+      interrupted ? "Cancelled." : "Input closed before an answer. For automation, set WLT_API_KEY or pipe the key to worldlabs auth login --api-key-stdin."
+    );
   } finally {
     reader.close();
     if (hidden) process.stderr.write("\n");
@@ -573,12 +620,25 @@ async function authStatus() {
     ...process.env.WLT_API_KEY?.trim() ? {} : { credentialFile: credentialPath(configuration().apiOrigin) }
   };
 }
-async function login(noBrowser) {
+async function pipedApiKey() {
+  if (process.stdin.isTTY) {
+    throw new CliError(
+      "--api-key-stdin reads a piped key, for example: worldlabs auth login --api-key-stdin < key.txt"
+    );
+  }
+  const input = await text(process.stdin);
+  const apiKey = input.trim();
+  if (!apiKey) throw new CliError("No API key on standard input.");
+  if (/\s/u.test(apiKey)) throw new CliError("Standard input must contain only the API key.");
+  return apiKey;
+}
+async function login(noBrowser, pipedKey) {
+  if (pipedKey) return await saveValidatedKey(pipedKey);
   if (process.env.WLT_API_KEY?.trim()) return await authStatus();
   const { apiOrigin, apiKeysUrl } = configuration();
   if (!process.stdin.isTTY || !process.stderr.isTTY) {
     throw new CliError(
-      "Run worldlabs auth login in your own terminal to paste a key privately. Agents should never ask for keys in chat."
+      "Run worldlabs auth login in your own terminal to paste a key privately. Agents should never ask for keys in chat. To read a key from a file or secret manager instead, pipe it to worldlabs auth login --api-key-stdin."
     );
   }
   process.stderr.write(
@@ -591,6 +651,10 @@ The key will be saved in plaintext at ${credentialPath(apiOrigin)}.
   if (!noBrowser) await openBrowser(apiKeysUrl);
   const apiKey = await prompt("Paste API key (hidden): ", true);
   if (!apiKey) throw new CliError("No key entered.");
+  return await saveValidatedKey(apiKey);
+}
+async function saveValidatedKey(apiKey) {
+  const { apiOrigin } = configuration();
   await createClient({ apiKey, baseUrl: apiOrigin }).assets.list({
     pageSize: 1,
     signal: AbortSignal.timeout(3e4)
@@ -618,7 +682,7 @@ import { randomUUID as randomUUID2 } from "node:crypto";
 import { openAsBlob } from "node:fs";
 import { open as open2, readFile, rm as rm2 } from "node:fs/promises";
 import nodePath2 from "node:path";
-import { text } from "node:stream/consumers";
+import { text as text2 } from "node:stream/consumers";
 import { pipeline } from "node:stream/promises";
 import { parseArgs } from "node:util";
 var mimeTypes = {
@@ -626,9 +690,11 @@ var mimeTypes = {
   ".jpeg": "image/jpeg",
   ".png": "image/png",
   ".webp": "image/webp",
+  ".exr": "image/x-exr",
   ".mp4": "video/mp4",
-  ".ply": "application/octet-stream",
-  ".spz": "application/octet-stream"
+  ".glb": "model/gltf-binary",
+  ".ply": "model/x-ply",
+  ".spz": "model/x-spz"
 };
 function timeout(value) {
   const seconds = value === void 0 ? 600 : Number(value);
@@ -665,7 +731,7 @@ async function runApiCommand(args2) {
       throw new CliError("Unknown task. Run worldlabs tasks list.");
     }
     const body = JSON.parse(
-      values.request === "-" ? await text(process.stdin) : await readFile(values.request, "utf8")
+      values.request === "-" ? await text2(process.stdin) : await readFile(values.request, "utf8")
     );
     if (!body || typeof body !== "object" || Array.isArray(body)) {
       throw new CliError("Task request must be a JSON object.");
@@ -759,24 +825,30 @@ Reuse this key and request if submission is interrupted.
   throw new CliError("Unknown command or arguments. Run worldlabs --help.");
 }
 
+// src/node-version.ts
+var MINIMUM_NODE_MAJOR = 22;
+function nodeVersionProblem(version2) {
+  if (Number(version2.split(".")[0]) >= MINIMUM_NODE_MAJOR) return void 0;
+  return `worldlabs requires Node.js ${MINIMUM_NODE_MAJOR} or newer, but this is Node.js ${version2}. Install the current Node.js LTS from https://nodejs.org and run the command again.`;
+}
+
 // src/skills.ts
-import { createHash as createHash2, randomUUID as randomUUID3 } from "node:crypto";
-import { cp, lstat as lstat2, mkdir as mkdir2, readFile as readFile2, readdir, rename as rename2, rm as rm3, writeFile as writeFile2 } from "node:fs/promises";
+import { execFile, spawn as spawn2 } from "node:child_process";
+import { createHash as createHash2 } from "node:crypto";
+import { lstat as lstat2, mkdtemp, readFile as readFile2, readdir, rename as rename2, rmdir } from "node:fs/promises";
 import { homedir as homedir2 } from "node:os";
 import nodePath3 from "node:path";
-import { fileURLToPath } from "node:url";
 var marker = ".worldlabs-install.json";
-var source = fileURLToPath(new URL("../skills/worldlabs/", import.meta.url));
-function skillTarget(client) {
-  if (client === "codex") {
-    return nodePath3.join(
-      process.env.CODEX_HOME ?? nodePath3.join(homedir2(), ".codex"),
-      "skills",
-      "worldlabs"
+var InstallerTerminationError = class extends CliError {
+  name = "InstallerTerminationError";
+};
+function skillClient(client) {
+  if (client !== void 0 && !/^[a-z0-9][a-z0-9-]*$/u.test(client)) {
+    throw new CliError(
+      "--client must be an agent name, such as codex, claude-code, cursor, or gemini-cli."
     );
   }
-  if (client === "claude-code") return nodePath3.join(homedir2(), ".claude", "skills", "worldlabs");
-  throw new CliError("Choose --client codex or --client claude-code.");
+  return client;
 }
 async function fingerprint(root) {
   const hash = createHash2("sha256");
@@ -797,93 +869,213 @@ async function fingerprint(root) {
   await visit("");
   return hash.digest("hex");
 }
-async function manageSkills(action, target) {
-  const parent = nodePath3.dirname(target);
-  const lock = `${target}.lock`;
-  await mkdir2(parent, { recursive: true });
+async function cleanupLegacySkill(client) {
+  const root = client === "codex" ? process.env.CODEX_HOME ?? nodePath3.join(homedir2(), ".codex") : nodePath3.join(homedir2(), ".claude");
+  const target = nodePath3.join(root, "skills", "worldlabs");
+  let stat;
   try {
-    await mkdir2(lock);
-  } catch {
+    stat = await lstat2(target);
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw error;
+  }
+  if (!stat.isDirectory() || stat.isSymbolicLink()) return;
+  let expected;
+  try {
+    expected = JSON.parse(await readFile2(nodePath3.join(target, marker), "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw new CliError(
+      `Cannot verify the old skill at ${target}. Move it aside before continuing.`
+    );
+  }
+  if (await fingerprint(target) !== expected) {
     throw new CliError(
-      `Skill installation is locked at ${lock}. Remove the lock only if no installer is running.`
+      `Old skill has local changes at ${target}. Move it aside before continuing.`
     );
   }
-  const staging = nodePath3.join(parent, `.worldlabs-${randomUUID3()}`);
-  const backup = `${staging}-backup`;
+  const backupContainer = await mkdtemp(
+    nodePath3.join(nodePath3.dirname(target), ".worldlabs-backup-")
+  );
+  const backup = nodePath3.join(backupContainer, "worldlabs");
   try {
-    let exists = false;
-    try {
-      await lstat2(target);
-      exists = true;
-    } catch (error) {
-      if (error.code !== "ENOENT") throw error;
-    }
-    if (exists) {
-      const actual = await fingerprint(target);
-      let expected;
+    await rename2(target, backup);
+  } catch (error) {
+    await rmdir(backupContainer).catch(() => null);
+    throw error;
+  }
+  process.stderr.write(`Moved the old CLI-managed skill to ${backup}
+`);
+  return { target, backup };
+}
+function runSkillsInstaller(args2, signal) {
+  signal.throwIfAborted();
+  const env = { ...process.env, DISABLE_TELEMETRY: "1" };
+  delete env.WLT_API_KEY;
+  const windows = process.platform === "win32";
+  return new Promise((resolve, reject) => {
+    const child = spawn2(
+      windows ? "cmd.exe" : "npx",
+      windows ? ["/d", "/s", "/c", `npx.cmd ${args2.join(" ")}`] : args2,
+      { env, detached: !windows, stdio: ["inherit", "pipe", "pipe"] }
+    );
+    child.stdout.pipe(process.stderr, { end: false });
+    child.stderr.pipe(process.stderr, { end: false });
+    let forceTimer;
+    let stopTimer;
+    let settled = false;
+    const finish = (error) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(forceTimer);
+      clearTimeout(stopTimer);
+      child.stdout.unpipe(process.stderr);
+      child.stderr.unpipe(process.stderr);
+      signal.removeEventListener("abort", cancel);
+      if (error) reject(error);
+      else resolve();
+    };
+    const cannotStop = () => {
+      child.stdout.destroy();
+      child.stderr.destroy();
+      child.unref();
+      finish(
+        new InstallerTerminationError(
+          "Could not stop the skills installer. Legacy backups were retained; stop the installer before restoring them."
+        )
+      );
+    };
+    const killGroup = (terminationSignal) => {
+      if (!child.pid) return;
       try {
-        expected = JSON.parse(await readFile2(nodePath3.join(target, marker), "utf8"));
-      } catch {
-        throw new CliError(`Refusing to replace an unowned skill: ${target}`);
+        process.kill(-child.pid, terminationSignal);
+      } catch (error) {
+        if (error.code !== "ESRCH") cannotStop();
       }
-      if (actual !== expected) {
-        throw new CliError(`Skill has local changes. Move it aside before continuing: ${target}`);
+    };
+    const cancel = () => {
+      if (!child.pid) return;
+      stopTimer = setTimeout(cannotStop, 5e3).unref();
+      if (windows) {
+        execFile(
+          "taskkill",
+          ["/PID", String(child.pid), "/T", "/F"],
+          { timeout: 4e3 },
+          (error) => {
+            if (error && !settled) cannotStop();
+          }
+        );
+      } else {
+        forceTimer = setTimeout(() => killGroup("SIGKILL"), 2e3).unref();
+        killGroup(signal.reason);
       }
-    }
-    if (action === "uninstall") {
-      if (exists) await rm3(target, { recursive: true });
-      return { path: target, removed: exists };
-    }
-    await cp(source, staging, { recursive: true });
-    const entry = fileURLToPath(
-      new URL(import.meta.url.endsWith(".ts") ? "index.ts" : "index.js", import.meta.url)
+    };
+    signal.addEventListener("abort", cancel, { once: true });
+    child.once(
+      "error",
+      () => finish(
+        new CliError("Could not start the skills installer. Check that npm and npx are available.")
+      )
     );
-    const windows = process.platform === "win32";
-    const shell = windows ? "powershell" : "sh";
-    const quote = (value) => `'${value.replaceAll("'", windows ? "''" : String.raw`'\''`)}'`;
-    const command = `${windows ? "& " : ""}${quote(process.execPath)} ${quote(entry)}`;
-    for (const name of await readdir(staging, { recursive: true })) {
-      const path = nodePath3.join(staging, name);
-      const stat = await lstat2(path);
-      if (stat.isFile()) {
-        const content = await readFile2(path, "utf8");
-        await writeFile2(
-          path,
-          content.replaceAll("{{CLI}}", () => command).replaceAll("{{SHELL}}", shell)
-        );
+    child.once(
+      "close",
+      (code) => finish(
+        code === 0 && !signal.aborted ? void 0 : new CliError("Skills installer did not complete. See its output above.")
+      )
+    );
+  });
+}
+async function manageSkills(action, client, yes = false) {
+  skillClient(client);
+  const moved = [];
+  const controller = new AbortController();
+  const cancel = (signal) => controller.abort(signal);
+  process.on("SIGINT", cancel);
+  process.on("SIGTERM", cancel);
+  try {
+    for (const candidate of client ? [client] : ["codex", "claude-code"]) {
+      if (candidate === "codex" || candidate === "claude-code") {
+        const record = await cleanupLegacySkill(candidate);
+        if (record) moved.push(record);
       }
+      if (controller.signal.aborted) throw new CliError("Skills installation cancelled.");
     }
-    await writeFile2(nodePath3.join(staging, marker), JSON.stringify(await fingerprint(staging)));
-    if (exists) await rename2(target, backup);
-    try {
-      await rename2(staging, target);
-    } catch (error) {
-      if (exists) await rename2(backup, target);
-      throw error;
+    const args2 = [
+      "--yes",
+      "skills@1.7.2",
+      ...action === "install" ? ["add", "worldlabsai/skills", "--skill", "worldlabs"] : ["remove", "worldlabs"],
+      ...client ? ["--agent", client] : [],
+      "--global",
+      ...yes ? ["--yes"] : []
+    ];
+    await runSkillsInstaller(args2, controller.signal);
+  } catch (error) {
+    if (error instanceof InstallerTerminationError) throw error;
+    for (const { target, backup } of moved.toReversed()) {
+      try {
+        await lstat2(target);
+        process.stderr.write(
+          `Could not restore the old skill because a skill now exists at ${target}. Backup retained at ${backup}
+`
+        );
+      } catch (restoreCheckError) {
+        if (restoreCheckError.code !== "ENOENT") {
+          process.stderr.write(
+            `Could not check the old skill location ${target}. Backup retained at ${backup}
+`
+          );
+          continue;
+        }
+        try {
+          await rename2(backup, target);
+          await rmdir(nodePath3.dirname(backup)).catch(() => null);
+        } catch {
+          process.stderr.write(
+            `Could not restore the old skill at ${target}. Backup retained at ${backup}
+`
+          );
+        }
+      }
     }
-    await rm3(backup, { recursive: true, force: true });
-    return { path: target, next: "Start a new agent session to load the worldlabs skill." };
+    throw error;
   } finally {
-    await rm3(staging, { recursive: true, force: true });
-    await rm3(lock, { recursive: true, force: true });
+    process.off("SIGINT", cancel);
+    process.off("SIGTERM", cancel);
+    if (controller.signal.aborted) {
+      process.kill(process.pid, controller.signal.reason);
+    }
   }
+  return {
+    client,
+    ...moved.length ? { legacyBackups: moved.map(({ backup }) => backup) } : {},
+    next: "Start a new agent session after changing skills."
+  };
 }
 
 // src/setup.ts
-async function setup(client, noBrowser) {
-  let target;
-  if (client !== void 0) {
-    target = skillTarget(client);
-  } else if (process.stdin.isTTY && process.stderr.isTTY) {
-    const choice = await prompt("Install agent skill: 1) Codex  2) Claude Code  3) Skip [3]: ");
-    if (choice === "1" || choice === "2") {
-      target = skillTarget(choice === "1" ? "codex" : "claude-code");
-    } else if (choice && choice !== "3") {
-      throw new CliError("Choose 1, 2, or 3.");
+async function setup(client, noBrowser, yes = false, keyFromStdin = false) {
+  const target = skillClient(client);
+  const pipedKey = keyFromStdin ? await pipedApiKey() : void 0;
+  let installSkill = target !== void 0;
+  if (!installSkill && process.stdin.isTTY && process.stderr.isTTY) {
+    const answer = await prompt("Install the World Labs agent skill? [y/N]: ");
+    const choice = answer.toLowerCase();
+    if (choice && !["y", "yes", "n", "no"].includes(choice)) {
+      throw new CliError("Choose yes or no.");
+    }
+    installSkill = choice === "y" || choice === "yes";
+  }
+  const auth = await login(noBrowser, pipedKey);
+  let skill;
+  if (installSkill) {
+    try {
+      skill = await manageSkills("install", target, yes);
+    } catch (error) {
+      throw new CliError(
+        `API authentication succeeded, but skill installation failed. ${error instanceof Error ? error.message : "Retry worldlabs skills install."}`
+      );
     }
   }
-  const auth = await login(noBrowser);
-  const skill = target ? await manageSkills("install", target) : void 0;
   return {
     ...auth,
     ...skill ? { skill } : {},
@@ -898,9 +1090,9 @@ var { version } = JSON.parse(
 var help = `worldlabs - World Labs Developer API CLI
 
 Usage: worldlabs [--json] <command>
-  setup [--client codex|claude-code] [--no-browser]
-  skills install|uninstall --client codex|claude-code
-  auth login [--no-browser]
+  setup [--client <agent>] [--no-browser] [--api-key-stdin] [--yes]
+  skills install|uninstall [--client <agent>] [--yes]
+  auth login [--no-browser] [--api-key-stdin]
   auth status
   auth logout
   config show
@@ -913,30 +1105,53 @@ Usage: worldlabs [--json] <command>
   --version
   --help
 
+Skills use Skills CLI client detection when --client is omitted (e.g. codex, claude-code, cursor, gemini-cli).
 Use --request - to read task JSON from standard input.
 
-Saved login uses a plaintext file in your user configuration directory. Automation can set WLT_API_KEY.
+Saved login uses a plaintext file in your user configuration directory. Automation can set WLT_API_KEY,
+or save a key without the prompt by piping it to --api-key-stdin.
 `;
 async function main(args2) {
+  const unsupported = nodeVersionProblem(process.versions.node);
+  if (unsupported) throw new CliError(unsupported);
   if (args2.length === 0 || args2.includes("--help")) return help;
   if (args2.length === 1 && args2[0] === "--version") return version;
   const [command, action, ...rest] = args2;
   if (command === "setup") {
     const { values } = parseArgs2({
       args: args2.slice(1),
-      options: { client: { type: "string" }, "no-browser": { type: "boolean" } }
+      options: {
+        client: { type: "string" },
+        "no-browser": { type: "boolean" },
+        "api-key-stdin": { type: "boolean" },
+        yes: { type: "boolean" }
+      }
     });
-    return await setup(values.client, Boolean(values["no-browser"]));
+    return await setup(
+      values.client,
+      Boolean(values["no-browser"]),
+      Boolean(values.yes),
+      Boolean(values["api-key-stdin"])
+    );
   }
   if (command === "skills" && (action === "install" || action === "uninstall")) {
-    const { values } = parseArgs2({ args: rest, options: { client: { type: "string" } } });
-    return await manageSkills(action, skillTarget(values.client));
+    const { values } = parseArgs2({
+      args: rest,
+      options: { client: { type: "string" }, yes: { type: "boolean" } }
+    });
+    return await manageSkills(action, skillClient(values.client), Boolean(values.yes));
   }
   if (command === "config" && action === "show" && !rest.length) return configuration();
   if (command === "auth") {
     if (action === "login") {
-      const { values } = parseArgs2({ args: rest, options: { "no-browser": { type: "boolean" } } });
-      return await login(Boolean(values["no-browser"]));
+      const { values } = parseArgs2({
+        args: rest,
+        options: { "no-browser": { type: "boolean" }, "api-key-stdin": { type: "boolean" } }
+      });
+      return await login(
+        Boolean(values["no-browser"]),
+        values["api-key-stdin"] ? await pipedApiKey() : void 0
+      );
     }
     if (action === "status" && !rest.length) return await authStatus();
     if (action === "logout" && !rest.length) return await logout();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@worldlabsai/cli",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "World Labs command line interface",
   "license": "Apache-2.0",
   "bin": {
@@ -8,16 +8,15 @@
   },
   "files": [
     "dist/index.js",
-    "skills",
     "LICENSE"
   ],
   "type": "module",
   "engines": {
-    "node": ">=24"
+    "node": ">=22"
   },
   "publishConfig": {
-    "access": "restricted",
+    "access": "public",
     "registry": "https://registry.npmjs.org/",
-    "tag": "next"
+    "tag": "latest"
   }
 }

package/skills/worldlabs/SKILL.md

@@ -1,43 +0,0 @@
----
-name: worldlabs
-description: Generate and edit scene images, estimate cameras and depth, or extract meshes with the World Labs CLI.
----
-
-# World Labs
-
-Use `{{CLI}}` for the Developer API. Run commands in `{{SHELL}}`. Run `{{CLI}} --help` for command syntax.
-
-## Choose a task
-
-| Task | Purpose |
-| --- | --- |
-| `atlasTextToImage` | Generate starting images from a description of an environment. |
-| `images2PosedRGBD` | Estimate cameras and depth from images of a scene. |
-| `atlasGenerate` | Generate new viewpoints using posed RGBD context. |
-| `atlasChisel` | Generate posed images from a prompt and optional depth layouts. |
-| `atlasMasked` | Fill masked regions across posed images. |
-| `splats2Mesh` | Extract a mesh from a Gaussian splat scene. |
-
-Read [How To Use Atlas](https://marble5.worldlabs.ai/docs/how-to-use-atlas) before choosing model inputs, calculating cameras, or chaining tasks. It explains scene data, model behavior, and the requirements that affect results. Follow its task or camera links when you need exact fields or geometry calculations. `{{CLI}} tasks list` reports SDK task names; account access can differ.
-
-## Submit and inspect
-
-Upload a local image:
-
-```{{SHELL}}
-{{CLI}} assets upload photo.jpg --json > asset.json
-```
-
-Write `request.json` as `{"frames":[{"imageAsset":{"assetId":"<id>"}}]}`, replacing `<id>` with the uploaded asset's `id` from `asset.json`.
-
-```{{SHELL}}
-{{CLI}} tasks run images2PosedRGBD --request request.json --wait --json > result.json
-```
-
-Use `--request -` to read JSON from stdin. Results go to stdout; diagnostics and the submission's idempotency key go to stderr. Preserve the key and reuse it with `--idempotency-key <key>` and the same request if submission is interrupted.
-
-A timeout stops local waiting, not server work. Resume with `{{CLI}} operations wait <operation-id> --json`. Check a completed operation's `error` before reading `response`. Download returned assets with `{{CLI}} assets download <asset-id> --out result.png`. Inspect the outputs before using them in another task; keep each image, camera, depth, and confidence together.
-
-## Authentication
-
-Check `{{CLI}} auth status`. If login is needed, have the user run `{{CLI}} auth login` in their own terminal and enter the key privately. Never request keys in chat or put them in command arguments. Automation can supply `WLT_API_KEY`. The key selects the API project and billing; a successful status check verifies asset access, not every task permission.