---
title: Node.js SDK
description: Manage Capawesome Cloud from Node.js with the official SDK — apps, builds, channels, deployments, and more, fully typed and promise-based.
---

# Node.js SDK

The official Node.js SDK, [`@capawesome/cloud-sdk`](https://www.npmjs.com/package/@capawesome/cloud-sdk){:target="_blank"}, gives you a fully typed, promise-based interface to the [Capawesome Cloud API](../api.md). Use it to manage apps, Live Update channels and deployments, native builds, app store destinations, and more from your own backend or tooling — anywhere the [CLI](../cli/index.md) isn't a fit.

!!! info "API in development"

    The Capawesome Cloud API is still evolving and may change without notice. Response types intentionally expose only the most relevant properties to keep breaking changes to a minimum.

## Installation

Install the package from npm. It requires **Node.js 20 or later** and is published as **ESM only**:

```bash
npm install @capawesome/cloud-sdk
```

## Authentication

Create an [API token](../accounts/tokens.md) in the Console and pass it to the client. Read it from an environment variable rather than hard-coding it:

```ts
import { CapawesomeCloud } from "@capawesome/cloud-sdk";

const client = new CapawesomeCloud({
  token: process.env.CAPAWESOME_TOKEN!,
});
```

## Getting started

Most operations are scoped to an app via `appId`, and every method takes a single options object and returns a typed promise:

```ts
const apps = await client.apps.list({ organizationId: process.env.CAPAWESOME_ORGANIZATION_ID! });
const app = await client.apps.get({ appId });
```

### Configuration

The client accepts a few options beyond the token:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `token` | `string` | — | API token used to authenticate. |
| `baseUrl` | `string` | `https://api.cloud.capawesome.io` | Base URL of the API. |
| `timeout` | `number` | `60000` | Request timeout in milliseconds. Does not apply to streamed downloads. |
| `maxRetries` | `number` | `3` | Retries for transient failures (network, `429`, `5xx`) on idempotent requests. |

## Usage

Resources mirror the API's path hierarchy: app-scoped resources are nested under `client.apps.*`, and top-level resources such as `client.jobs` sit directly on the client.

### Trigger a build and wait for it

A native build runs as a background **job**, so trigger it, then poll the job until it finishes:

```ts
const build = await client.apps.builds.create({
  appId,
  platform: "ios",
  gitRef: "main",
});

let job = await client.jobs.get({ jobId: build.jobId! });
while (job.status === "queued" || job.status === "pending" || job.status === "in_progress") {
  await new Promise((resolve) => setTimeout(resolve, 5000));
  job = await client.jobs.get({ jobId: job.id });
}
```

### Promote a build to a channel

Create a deployment to publish a build to a Live Update channel — optionally as a gradual rollout:

```ts
const deployment = await client.apps.deployments.create({
  appId,
  appBuildId,
  appChannelName: "production",
  rolloutPercentage: 0.5,
});
```

### Download a build artifact

Binary downloads return a `ReadableStream`, so large files stream straight to disk without buffering in memory:

```ts
import { Writable } from "node:stream";
import { createWriteStream } from "node:fs";

const stream = await client.apps.builds.artifacts.download({ appId, buildId, artifactId });
await stream.pipeTo(Writable.toWeb(createWriteStream("artifact.ipa")));
```

## Error handling

Any non-`2xx` response is thrown as a `CapawesomeCloudError` carrying the status code, message, and raw body:

```ts
import { CapawesomeCloudError } from "@capawesome/cloud-sdk";

try {
  await client.apps.get({ appId: "unknown" });
} catch (error) {
  if (error instanceof CapawesomeCloudError) {
    console.error(error.status); // 404
    console.error(error.message); // "App not found."
  }
}
```

## Reference

The SDK covers the full API surface — apps, channels, deployments, builds and artifacts, certificates, environments, automations, devices, webhooks, and jobs. For the complete list of resources and options, see the [package on npm](https://www.npmjs.com/package/@capawesome/cloud-sdk){:target="_blank"} and the [source on GitHub](https://github.com/capawesome-team/cloud-node){:target="_blank"}, or browse the underlying [Cloud API](../api.md).