@parallax-ai/cloud

TypeScript SDK and CLI for Parallax Cloud: deploy branches, wait for builds, roll back production, and manage environment variables and custom domains from scripts and CI.

• Node 18+ (uses the built-in fetch), zero runtime dependencies, ESM + CJS, typed.
• Authenticates with a Cloud access token (pk_...). Create one at https://cloud.parallax.kr/account/tokens. Other Parallax API keys are rejected (INSUFFICIENT_SCOPE).

pnpm add @parallax-ai/cloud      # or run the CLI with npx -p @parallax-ai/cloud (see CLI)
export PARALLAX_TOKEN=pk_...

SDK

import { ParallaxCloud } from '@parallax-ai/cloud';

const cloud = new ParallaxCloud(); // token from PARALLAX_TOKEN

// Deploy the production branch and stream the build log.
const project = await cloud.projects.get('my-app'); // id or slug
const queued = await cloud.deployments.create('my-app', { branch: project.productionBranch });
const done = await cloud.deployments.waitUntilDone(queued.id, {
  onLog: line => console.log(line.text),
});
if (done.status !== 'ready') throw new Error(done.errorMessage ?? 'build failed');
console.log(done.url);

// Instant rollback (no rebuild): previous ready production deployment.
await cloud.deployments.rollback('my-app');

// Environment variables (applied on the next deployment).
await cloud.env.set('my-app', { key: 'API_URL', value: 'https://api.example.com', targets: ['production'] });
await cloud.env.set('my-app', { key: 'API_URL', value: 'https://staging.example.com', targets: ['preview'], branch: 'develop' });

// Custom domain: returns the TXT + CNAME records to add.
const domain = await cloud.domains.add('my-app', { hostname: 'www.example.com' });

| Resource | Methods | |---|---| | cloud | me(), frameworks() | | cloud.projects | list, get, create, update, delete, branches | | cloud.deployments | list, iterate, get, create, logs, waitUntilDone, cancel, redeploy, promote, rollback | | cloud.env | list, create, update, delete, set, unset | | cloud.domains | list, add, verify, update, remove, find | | cloud.github | installations, repositories, branches, detect |

Errors are ParallaxCloudError with status, code (e.g. PROJECT_NOT_FOUND, DEPLOYMENT_NOT_READY) and message. GET requests retry on 408/429/5xx (default 2 retries); writes are never retried.

Options: new ParallaxCloud({ token, baseUrl, timeoutMs, maxRetries, fetch }).

CLI

The bin is parallax-cloud, but the npm package is @parallax-ai/cloud. Always name the scoped package (npx -p @parallax-ai/cloud ...): a bare npx parallax-cloud resolves the unscoped npm name parallax-cloud, which is not ours, and would run someone else's code with your PARALLAX_TOKEN.

npx -p @parallax-ai/cloud parallax-cloud whoami
npx -p @parallax-ai/cloud parallax-cloud projects
npx -p @parallax-ai/cloud parallax-cloud deploy my-app --prod --wait          # exit 1 if the build fails
npx -p @parallax-ai/cloud parallax-cloud deploy my-app --branch feature/x     # preview
npx -p @parallax-ai/cloud parallax-cloud deployments my-app --target production
npx -p @parallax-ai/cloud parallax-cloud logs <deployment-id> --follow
npx -p @parallax-ai/cloud parallax-cloud rollback my-app --yes
npx -p @parallax-ai/cloud parallax-cloud promote <deployment-id> --yes
echo "$SECRET" | npx -p @parallax-ai/cloud parallax-cloud env add my-app SENTRY_AUTH_TOKEN --secret --target production
npx -p @parallax-ai/cloud parallax-cloud env rm my-app OLD_KEY
npx -p @parallax-ai/cloud parallax-cloud domains add my-app www.example.com
npx -p @parallax-ai/cloud parallax-cloud domains verify my-app www.example.com

With the package installed locally (pnpm add -D @parallax-ai/cloud), pnpm exec parallax-cloud ... works too.

Every command accepts --json, --token and --api-url. Run parallax-cloud --help for the full list. Exit codes: 0 success, 1 failure, 2 usage error.

GitHub Actions

Git pushes already deploy automatically once a repository is imported. Use the CLI when a workflow needs to gate on the result, e.g. run end-to-end tests against the preview URL:

- id: deploy
  run: npx -y -p @parallax-ai/cloud parallax-cloud deploy my-app --branch "${{ github.head_ref || github.ref_name }}" --preview --wait
  env:
    PARALLAX_TOKEN: ${{ secrets.PARALLAX_TOKEN }}
- run: npx playwright test
  env:
    BASE_URL: ${{ steps.deploy.outputs.url }}

deploy (and redeploy --wait) writes deployment-id, url and status to $GITHUB_OUTPUT; with --wait the status is final.

Development

pnpm --filter @parallax-ai/cloud typecheck
pnpm --filter @parallax-ai/cloud test
pnpm --filter @parallax-ai/cloud build

Types in src/types.ts mirror core/server/src/modules/cloud/cloud.serializers.ts; change them together.