Cubicle
The Cubicle class of @cubicle/sdk: its constructor, properties and methods.
A client for the Cubicle API. It keeps no state between processes: every request carries the API key, and nothing is written to disk.
Use one client per process: all of its waits share one poll budget
(maxPollsPerSecond).
Example
import { Cubicle } from "@cubicle/sdk"
const cubicle = new Cubicle() // reads CB_SDK_API_URL and CB_SDK_API_KEY
const box = await cubicle.boxes.create({ name: "job-1" })
try {
const result = await box.exec(["uname", "-a"])
console.log(result.exitCode, result.stdout)
} finally {
await box.delete()
}See
Constructors
Constructor
new Cubicle(options?): Cubicle;Creates a client. It sends no request until you call a method.
Parameters
| Parameter | Type | Description |
|---|---|---|
options? | CubicleOptions | Each option overrides its environment variable or default. |
Returns
Cubicle
Throws
CubicleError with code missing_api_url or missing_api_key when
neither the option nor its environment variable is set, and invalid_option when a
value is out of range or apiUrl is not an http or https URL.
Example
import { Cubicle } from "@cubicle/sdk"
// CB_SDK_API_URL and CB_SDK_API_KEY are set in the environment.
const cubicle = new Cubicle()
// Or pass options; they win over the environment.
const acme = new Cubicle({ apiUrl: "https://api.cubicle.sh", org: "acme" })Properties
| Property | Modifier | Type | Description |
|---|---|---|---|
boxes | readonly | Boxes | Box management: create, list, start, stop, exec, snapshot, delete and more. |
operations | readonly | Operations | Reading and waiting for exec, snapshot and restore operations. |
Methods
listBases()
listBases(options?): Promise<CreationBase[]>;Base images, and whether a healthy Node has each one now; free capacity is not
considered. Pass an ID as baseImage to boxes.create.
Parameters
| Parameter | Type | Description |
|---|---|---|
options? | { org?: string; signal?: AbortSignal; } | - |
options.org? | string | Organization name or ID. Defaults to the client's org, then the API key's organization. |
options.signal? | AbortSignal | Aborts the request. |
Returns
Promise<CreationBase[]>
Throws
CubicleError with code org_required when no organization can be chosen.
listSnapshots()
listSnapshots(options?): Promise<CreationSnapshot[]>;Completed snapshots the caller may create Boxes from: those of Boxes it has a grant on,
or every one in the organization for an owner or admin. Pass an ID as snapshotId to
boxes.create. A Box's own snapshots, including pending ones, come from
Boxes.listSnapshots.
Parameters
| Parameter | Type | Description |
|---|---|---|
options? | { org?: string; signal?: AbortSignal; } | - |
options.org? | string | Organization name or ID. Defaults to the client's org, then the API key's organization. |
options.signal? | AbortSignal | Aborts the request. |
Returns
Promise<CreationSnapshot[]>
Throws
CubicleError with code org_required when no organization can be chosen.
me()
me(options?): Promise<Me>;The caller's identity and organizations; apiKey is set for API keys.
Parameters
| Parameter | Type | Description |
|---|---|---|
options? | { signal?: AbortSignal; } | - |
options.signal? | AbortSignal | Aborts the request. |
Returns
Promise<Me>
Throws
CubicleApiError with code unauthenticated when the key is invalid,
expired or revoked.
Example
const me = await cubicle.me()
console.log(me.identity, me.apiKey?.scope) // => "acme/ci" "write"