SDK and CLI

@glboost/sdk

npm install @glboost/sdk

import { createClient, uploadModel, waitForReady, assetUrl } from '@glboost/sdk';
import { readFile } from 'node:fs/promises';

const client = createClient({ apiKey: process.env.GLBOOST_API_KEY! });

const { assetId } = await uploadModel(client, { name: 'chair.glb', data: await readFile('chair.glb') });
const ready = await waitForReady(client, assetId);           // polls until no variant is queued
for (const v of ready.variants) console.log(v.preset, v.bytes, v.score?.grade);

console.log(assetUrl(assetId, { preset: 'gpu' }));         // https://cdn.glboost.com/<id>.glb?p=gpu

uploadModel runs the same flow as the dashboard: it registers the version, PUTs the parts to the CDN, completes the multipart upload, and queues the variants; on a failure after the first step it aborts on both sides and rethrows. Pass assetId to replace an asset with a new version, note for the version note, and onProgress for a progress bar (byte-level in browsers, per part in Node). The project defaults to the key's (GET /api/v1/me); set projectId for org-wide keys with several projects, or project on the client.

const { url, exp } = await signUrl(client, assetId, { preset: 'gpu', ttlSeconds: 600 });

// Every endpoint, typed from the OpenAPI document:
const { data, error } = await client.api.GET('/api/v1/assets', { params: { query: { q: 'chair' } } });
const me = await client.me();

Helpers throw GLBoostApiError with the API's status and code; error.isPlanLimit is true for 402 and 413, with plan, used, limit, and upgradeUrl filled in. waitForReady throws GLBoostTimeoutError after its timeoutMs (10 minutes by default) and lists failed variants under failed instead of throwing. In a browser with a dashboard session, use createClient({ baseUrl: '' }) (cookies, same origin).

For tests, @glboost/sdk/testing exports createFakeApi(): an in-memory stand-in for the API and the CDN upload endpoints that speaks the same routes and shapes. createClient({ fetch: createFakeApi().fetch }) and your code uploads, waits, signs, and shares without a network.

glboost CLI

npm install -g glboost          # or: npx glboost …
glboost login                   # paste a key from Settings → API keys (or set GLBOOST_API_KEY)
glboost push models/*.glb --wait

File        Asset         Version  Original  compat   gpu      Grade  vs previous
----------  ------------  -------  --------  -------  -------  -----  --------------------------
chair.glb   k7m2p9q4r1s8  v2       4.20 MB   1.10 MB  620 KB   A      -12% (1.25 MB → 1.10 MB)

login [--key <key>]

Checks the key against GET /me and stores it in the OS config dir, readable by you only.

whoami

The org, plan, project, and key the CLI acts as.

push <files...> [--asset <id> | --match-by-name] [--note] [--preset <name>]... [--wait] [--timeout <s>]

Uploads each file or glob match (.glb, .gltf, .zip). --asset makes it a new version of that asset, --match-by-name of the asset named like the file; --preset queues extra variants; --wait waits for them and fills in sizes and grades.

assets ls [--q] [--tag] [--deleted]

List or search assets; --deleted lists the trash.

assets get <id>

Versions and variants with sizes and grades.

assets rm <id> [--permanent]

Trash an asset; --permanent purges a trashed one.

variants request <id> (--preset | --spec) [--version]

Queue a variant by preset or canonical spec.

sign <id> [--preset | --spec] [--ttl] [--version] [--download]

A signed CDN URL.

share create <id> [--password] [--expires] [--download none|optimized|all]

A share link.

score <id>

Grades and points of the newest version.

validate <file>

Khronos glTF-Validator on a local .glb or .gltf, no upload, no key; exits 1 on errors.

export <id> --format usdz|gltf-zip|c-array [--preset]

Queue an export of a variant.

Every command takes --json. Exit codes: 0 ok, 1 error, 2 a plan or size limit (the message names the plan and the upgrade URL). GLBOOST_API_KEY overrides the stored key, GLBOOST_BASE_URL the API origin, GLBOOST_CDN_BASE_URL the CDN in printed URLs. push --json prints a report with every variant and the previous version's sizes; the GitHub Action turns it into a pull-request comment. The endpoints behind all of this are in the API reference.