@spatius/cli 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spatialwalk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# Spatius CLI
+
+Create avatars and render videos from a coding agent or terminal. The CLI handles
+Studio login, app credentials, temporary uploads, polling, and MP4 downloads.
+
+Requires Node.js 22+, a Spatius Studio account, and separately approved Avatar
+and Video API access. Avatar creation uses your existing Avatar Creations balance.
+The CLI is experimental.
+
+## Get started
+
+After the npm release:
+
+```sh
+npm install -g @spatius/cli@beta
+spatius auth login
+spatius setup
+```
+
+Approve login at `https://app.spatius.ai` in your local browser. Studio API
+requests use `https://api.studio.spatius.ai`; development origin settings are
+documented in the [workflow guide](docs/workflows.md). Credentials stay in private user configuration
+storage; commands never print API keys. Setup reuses a dedicated `Spatius CLI` app.
+Use `spatius setup --app-id <id>` to select another app you own.
+
+```sh
+spatius avatars create --image ./portrait.png --name Presenter
+spatius avatars jobs wait <avatar-job-id>
+spatius videos create --avatar-id <avatar-id> --audio ./speech.wav --background ./background.png
+spatius videos wait <video-job-id>
+spatius videos download <video-job-id> --output ./video.mp4
+```
+
+Inputs accept local files or public HTTP(S) URLs. Local files are uploaded to
+temporary storage and remain available for 24 hours after upload completion.
+Video output follows the service's retention deadline, currently seven days
+after render submission. Save your MP4 before it expires.
+
+Commands return JSON on stdout; progress and errors go to stderr. Save the
+`operationId` and `jobId` returned by creation. Resume an interrupted creation with
+`spatius videos create --resume <operation-id>` or
+`spatius avatars create --resume <operation-id>`; do not start a fresh creation
+just because a command timed out.
+
+## Use with coding agents
+
+```sh
+npx skills add spatius-ai/spatius-cli --skill spatius-shared spatius-avatar spatius-video
+spatius schema
+spatius schema videos create
+```
+
+The three skills cover setup, avatar creation, and video generation. The npm
+package includes the matching skills under `skills/`; use those files when an
+exact version match is needed. The GitHub installer above follows the repository
+default branch. Skills and CLI behavior ship together. `--dry-run` previews a
+creation without uploading or submitting it. `--help` describes the installed CLI's options.
+
+See the [workflow guide](docs/workflows.md) for input requirements and recovery,
+and the [Spatius API documentation](https://docs.spatius.ai/api-reference/video-generation)
+for service behavior. Repository development instructions are in
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+Prereleases use the npm `beta` channel. After a stable release, install it with
+`npm install -g @spatius/cli`. The executable is always `spatius`. Maintainers can
+find the release workflow and first-time setup in the
+[deployment guide](docs/deployment.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,26 @@
+# Third-party notices
+
+The Studio loopback authentication implementation adapts the protocol and code
+from [create-spatius-app](https://github.com/spatius-ai/create-spatius-app).
+
+MIT License
+
+Copyright (c) 2026 spatialwalk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/chunk-YILIK7FE.js

@@ -0,0 +1,479 @@
+// src/commands.ts
+import { Command, Option } from "commander";
+
+// src/core/errors.ts
+var CliError = class extends Error {
+  constructor(code, message, options = {}) {
+    super(message);
+    this.code = code;
+    this.options = options;
+    this.name = "CliError";
+  }
+  code;
+  options;
+};
+function asCliError(error) {
+  if (error instanceof CliError) return error;
+  if (error instanceof Error && error.name === "AbortError")
+    return new CliError("INTERRUPTED", "Operation interrupted.", {
+      exitCode: 130
+    });
+  return new CliError(
+    "INTERNAL_ERROR",
+    "The operation could not be completed.",
+    {
+      recovery: "Retry a read operation, or inspect the saved operation before retrying a creation."
+    }
+  );
+}
+
+// src/commands.ts
+var timeout = {
+  flags: "--timeout <seconds>",
+  description: "Wait deadline in seconds (default: 600).",
+  type: "number"
+};
+var resume = {
+  flags: "--resume <operation-id>",
+  description: "Resume a saved operation without supplying new input."
+};
+var wait = {
+  flags: "--wait",
+  description: "Wait for the admitted job to finish."
+};
+var dryRun = {
+  flags: "--dry-run",
+  description: "Validate and preview without network requests or local state changes."
+};
+var pages = [
+  {
+    flags: "--page-size <number>",
+    description: "Results per page (1\u2013100).",
+    type: "number"
+  },
+  {
+    flags: "--page-token <token>",
+    description: "Next page token returned by the preceding list; keep page size unchanged."
+  }
+];
+var status = {
+  flags: "--status <statuses>",
+  description: "Comma-separated job status filters."
+};
+var str = (v, key) => v[key];
+var num = (v, key) => v[key];
+var bool = (v, key) => v[key] === true;
+function pageOptions(v) {
+  return {
+    pageSize: num(v, "pageSize"),
+    pageToken: str(v, "pageToken"),
+    statuses: str(v, "status")?.split(",")
+  };
+}
+function settings(v) {
+  return Object.fromEntries(
+    [
+      "width",
+      "height",
+      "fit",
+      "backgroundColor",
+      "backgroundFit",
+      "leadInSeconds",
+      "leadOutSeconds"
+    ].filter((key) => v[key] !== void 0).map((key) => [key, v[key]])
+  );
+}
+var definitions = [
+  {
+    path: "auth login",
+    description: "Authorize this local CLI through Spatius Studio.",
+    output: "Authenticated user and selected app metadata; no credentials.",
+    example: "spatius auth login",
+    flags: [
+      {
+        flags: "--no-browser",
+        description: "Print the approval URL without opening a browser."
+      },
+      {
+        ...timeout,
+        description: "Browser approval timeout in seconds (default: 300)."
+      }
+    ],
+    run: async (_, v, c) => c.auth.login({
+      noBrowser: v.browser === false,
+      timeoutMs: (num(v, "timeout") ?? 300) * 1e3,
+      onAuthorize: (url) => c.progress({
+        event: "authorization_required",
+        url,
+        requiresHuman: true
+      }),
+      signal: c.signal
+    })
+  },
+  {
+    path: "auth status",
+    description: "Inspect the active Studio login.",
+    output: "Authentication and account metadata.",
+    example: "spatius auth status",
+    run: async (_, __, c) => c.auth.status()
+  },
+  {
+    path: "auth logout",
+    description: "Revoke refresh access and remove local credentials.",
+    output: "Logged-out state.",
+    example: "spatius auth logout",
+    run: async (_, __, c) => c.auth.logout()
+  },
+  {
+    path: "setup",
+    description: "Create or reuse a Studio app and API key for this account.",
+    output: "appId, userId, and reuse information; no API key.",
+    example: "spatius setup",
+    flags: [
+      {
+        flags: "--app-id <id>",
+        description: "Select an existing app owned by the authenticated user."
+      },
+      {
+        flags: "--retry-uncertain",
+        description: "After reconciliation, allow one new app/key creation; an earlier request may already have created it."
+      }
+    ],
+    run: async (_, v, c) => c.auth.setup({
+      appId: str(v, "appId"),
+      retryUncertain: bool(v, "retryUncertain")
+    })
+  },
+  {
+    path: "apps list",
+    description: "List owned Studio apps without exposing their API keys.",
+    output: "Array of appId, name, and createdAt.",
+    example: "spatius apps list",
+    run: async (_, __, c) => c.auth.listApps()
+  },
+  {
+    path: "assets upload",
+    description: "Upload a local input to temporary storage.",
+    output: "Upload ID, accepted parts, status, and completed URL/expiration.",
+    example: "spatius assets upload ./speech.wav --kind audio",
+    args: [{ name: "file", required: true }],
+    flags: [
+      {
+        flags: "--kind <kind>",
+        description: "Input purpose.",
+        choices: ["avatar-image", "audio", "background"]
+      },
+      {
+        flags: "--resume <upload-id>",
+        description: "Resume an existing upload of this same local file."
+      }
+    ],
+    run: async (a, v, c) => {
+      const kind = str(v, "kind");
+      if (!kind)
+        throw new CliError("INVALID_ARGUMENT", "--kind is required.", {
+          exitCode: 2
+        });
+      return c.workflows.upload(a[0], {
+        kind,
+        resume: str(v, "resume")
+      });
+    }
+  },
+  {
+    path: "assets get",
+    description: "Inspect an owned temporary upload.",
+    output: "Upload status and accepted parts.",
+    example: "spatius assets get 00000000-0000-4000-8000-000000000001",
+    args: [{ name: "id", required: true }],
+    run: async (a, _, c) => c.workflows.getUpload(a[0])
+  },
+  {
+    path: "assets abort",
+    description: "Abort an unfinished upload and release storage after cleanup.",
+    output: "Aborted upload state.",
+    example: "spatius assets abort 00000000-0000-4000-8000-000000000001",
+    args: [{ name: "id", required: true }],
+    run: async (a, _, c) => c.workflows.abortUpload(a[0])
+  },
+  {
+    path: "avatars create",
+    description: "Create an avatar from a local JPEG/PNG or public URL.",
+    output: "operationId, jobId, status, createdAt; optional completed job.",
+    example: "spatius avatars create --image ./portrait.png --name Presenter",
+    flags: [
+      {
+        flags: "--image <file-or-url>",
+        description: "Opaque JPEG/PNG, at most 5 MiB, shorter side at least 340 pixels."
+      },
+      { flags: "--name <name>", description: "Avatar display name." },
+      resume,
+      wait,
+      timeout,
+      dryRun
+    ],
+    run: async (_, v, c) => c.workflows.createAvatar({
+      image: str(v, "image"),
+      name: str(v, "name"),
+      resume: str(v, "resume"),
+      wait: bool(v, "wait"),
+      timeout: num(v, "timeout"),
+      dryRun: bool(v, "dryRun")
+    })
+  },
+  {
+    path: "avatars get",
+    description: "Read an account avatar.",
+    output: "Public Avatar API detail.",
+    example: "spatius avatars get 00000000-0000-4000-8000-000000000001",
+    args: [{ name: "id", required: true }],
+    run: async (a, _, c) => c.workflows.getAvatar(a[0])
+  },
+  {
+    path: "avatars list",
+    description: "List account avatars.",
+    output: "Avatars and pagination.nextPageToken.",
+    example: "spatius avatars list --page-size 20",
+    flags: pages,
+    run: async (_, v, c) => c.workflows.listAvatars(pageOptions(v))
+  },
+  {
+    path: "videos create",
+    description: "Render an avatar with audio and an optional background.",
+    output: "operationId, jobId, status, createdAt; optional completed job.",
+    example: "spatius videos create --avatar-id 00000000-0000-4000-8000-000000000001 --audio ./speech.wav",
+    flags: [
+      {
+        flags: "--avatar-id <id>",
+        description: "Public, assigned, or explicitly permitted avatar UUID."
+      },
+      {
+        flags: "--audio <file-or-url>",
+        description: "Supported audio input, at most 500 MiB."
+      },
+      {
+        flags: "--background <file-or-url>",
+        description: "Optional JPEG/PNG/WebP background, at most 50 MiB."
+      },
+      { flags: "--name <name>", description: "Video job name." },
+      {
+        flags: "--request-id <uuid>",
+        description: "Retry identity; generated and saved when omitted."
+      },
+      {
+        flags: "--width <pixels>",
+        description: "Even width, 64\u20131920 (default 1024).",
+        type: "number"
+      },
+      {
+        flags: "--height <pixels>",
+        description: "Even height, 64\u20131920 (default 1024).",
+        type: "number"
+      },
+      {
+        flags: "--fit <fit>",
+        description: "Avatar fit (default crop).",
+        choices: ["crop", "contain"]
+      },
+      {
+        flags: "--background-color <hex>",
+        description: "Six-digit RGB color (default #000000)."
+      },
+      {
+        flags: "--background-fit <fit>",
+        description: "Background fit (default cover).",
+        choices: ["cover", "contain", "stretch"]
+      },
+      {
+        flags: "--lead-in-seconds <seconds>",
+        description: "Additional initial idle time, 0\u201360.",
+        type: "number"
+      },
+      {
+        flags: "--lead-out-seconds <seconds>",
+        description: "Additional final idle time, 0\u201360.",
+        type: "number"
+      },
+      resume,
+      wait,
+      timeout,
+      dryRun
+    ],
+    run: async (_, v, c) => c.workflows.createVideo({
+      avatarId: str(v, "avatarId"),
+      audio: str(v, "audio"),
+      background: str(v, "background"),
+      name: str(v, "name"),
+      requestId: str(v, "requestId"),
+      video: settings(v),
+      resume: str(v, "resume"),
+      wait: bool(v, "wait"),
+      timeout: num(v, "timeout"),
+      dryRun: bool(v, "dryRun")
+    })
+  },
+  ...["avatar", "video"].flatMap((kind) => {
+    const prefix = kind === "avatar" ? "avatars jobs" : "videos";
+    return [
+      {
+        path: `${prefix} get`,
+        description: `Read a ${kind} job.`,
+        output: "Job detail; a successful video includes a fresh download URL.",
+        example: `spatius ${prefix} get 00000000-0000-4000-8000-000000000001`,
+        args: [{ name: "id", required: true }],
+        run: async (a, _, c) => c.workflows.getJob(kind, a[0])
+      },
+      {
+        path: `${prefix} list`,
+        description: `List ${kind} jobs.`,
+        output: "Jobs and pagination.nextPageToken; no download URLs.",
+        example: `spatius ${prefix} list --status processing`,
+        flags: [...pages, status],
+        run: async (_, v, c) => c.workflows.listJobs(kind, pageOptions(v))
+      },
+      {
+        path: `${prefix} wait`,
+        description: `Wait for an existing ${kind} job without submitting another.`,
+        output: "Terminal job detail. Deadline reached exits 3 and preserves the job.",
+        example: `spatius ${prefix} wait 00000000-0000-4000-8000-000000000001 --timeout 600`,
+        args: [{ name: "id", required: true }],
+        flags: [timeout],
+        run: async (a, v, c) => c.workflows.waitJob(kind, a[0], { timeout: num(v, "timeout") })
+      }
+    ];
+  }),
+  {
+    path: "videos download",
+    description: "Fetch a fresh MP4 link and save the output atomically.",
+    output: "Saved file path and video job identity.",
+    example: "spatius videos download 00000000-0000-4000-8000-000000000001 --output ./video.mp4",
+    args: [{ name: "id", required: true }],
+    flags: [
+      {
+        flags: "--output <path>",
+        description: "Destination MP4 file (required)."
+      },
+      { flags: "--force", description: "Replace an existing destination." }
+    ],
+    run: async (a, v, c) => {
+      const output = str(v, "output");
+      if (!output)
+        throw new CliError("INVALID_ARGUMENT", "--output is required.", {
+          exitCode: 2
+        });
+      return c.workflows.download(a[0], { output, force: bool(v, "force") });
+    }
+  }
+];
+function commandSchema(path) {
+  const found = path ? definitions.filter((d) => d.path === path) : definitions;
+  if (!found.length)
+    throw new CliError(
+      "UNKNOWN_COMMAND",
+      "No command matches that schema path.",
+      {
+        exitCode: 2,
+        recovery: "Run spatius schema to discover available commands."
+      }
+    );
+  return {
+    schemaVersion: 1,
+    executable: "spatius",
+    outputEnvelope: {
+      schemaVersion: 1,
+      ok: true,
+      data: "command-specific result"
+    },
+    errorEnvelope: {
+      schemaVersion: 1,
+      ok: false,
+      error: {
+        code: "string",
+        message: "string",
+        retryable: "boolean",
+        recovery: "string?",
+        details: "object?"
+      }
+    },
+    streams: { result: "stdout", error: "stderr", progress: "stderr" },
+    exitCodes: {
+      0: "success",
+      1: "operation failure",
+      2: "invalid arguments",
+      3: "wait deadline",
+      130: "interrupted"
+    },
+    commands: found.map(
+      ({ path: path2, description, args, flags, output, example }) => ({
+        path: path2,
+        description,
+        arguments: args ?? [],
+        options: flags ?? [],
+        output,
+        examples: [example]
+      })
+    )
+  };
+}
+function buildProgram(getContext, emit, version) {
+  const root = new Command().name("spatius").description("Avatar and video workflows for coding agents.").version(version).option("--json", "Use structured JSON output (the default).").exitOverride();
+  const groups = /* @__PURE__ */ new Map([["", root]]);
+  for (const def of definitions) {
+    const parts = def.path.split(" ");
+    let parent = root;
+    for (let i = 0; i < parts.length - 1; i++) {
+      const key = parts.slice(0, i + 1).join(" ");
+      let group = groups.get(key);
+      if (!group) {
+        group = parent.command(parts[i]);
+        groups.set(key, group);
+      }
+      parent = group;
+    }
+    const cmd = parent.command(parts.at(-1)).description(def.description);
+    for (const arg of def.args ?? [])
+      cmd.argument(arg.required ? `<${arg.name}>` : `[${arg.name}]`);
+    for (const flag of def.flags ?? []) {
+      const option = new Option(flag.flags, flag.description);
+      if (flag.choices) option.choices(flag.choices);
+      if (flag.type === "number")
+        option.argParser((value) => {
+          const parsed = Number(value);
+          if (!value.trim() || !Number.isFinite(parsed))
+            throw new CliError(
+              "INVALID_ARGUMENT",
+              "Expected a finite number.",
+              { exitCode: 2 }
+            );
+          return parsed;
+        });
+      if (flag.default !== void 0) option.default(flag.default);
+      cmd.addOption(option);
+    }
+    cmd.action(async (...args) => {
+      const count = def.args?.length ?? 0;
+      const values = args[count];
+      if (typeof values.timeout === "number" && values.timeout <= 0)
+        throw new CliError("INVALID_ARGUMENT", "--timeout must be positive.", {
+          exitCode: 2
+        });
+      emit(
+        await def.run(args.slice(0, count), values, getContext())
+      );
+    });
+  }
+  root.command("schema").description(
+    "Describe commands and structured output for this CLI version."
+  ).argument("[command...]").action(
+    (parts) => emit(commandSchema(parts.length ? parts.join(" ") : void 0))
+  );
+  return root;
+}
+
+export {
+  CliError,
+  asCliError,
+  definitions,
+  commandSchema,
+  buildProgram
+};