CLI & API reference

Programmatic access to BuildStack: the dbs CLI, the REST API, the GitHub Action, and outbound webhooks. All of it authenticates with an API key — create one in a project's API keys panel. See API keys & the dbs CLI for the basics; this page is the reference.

Authentication

Every call carries your API key as a bearer token:

Authorization: Bearer dbs_xxxxxxxx

The CLI reads it from dbs login --key … or the DBS_API_KEY environment variable. Keys are shown once and stored hashed — rotate by revoking and creating a new one.

The dbs CLI

# install (or use npx to run without installing)
npm install -g @dalysie-forge/cli

# authenticate
dbs login --key $DBS_API_KEY

# build a project from a local directory
dbs build ./my-app --project PROJECT_ID --format aab

Run dbs --help or dbs <command> --help for the full, always-current list of commands and flags (the CLI is the source of truth for its own reference).

GitHub Action

Use the bundled action to build from a workflow:

- uses: Dalysie/dalysie-forge/apps/cli/action@develop
  with:
    api-key: ${{ secrets.BUILDSTACK_API_KEY }}
    project: PROJECT_ID
    format: aab

Store the key as a repository secret, never inline.

REST API

Base URL: https://api.mybuildstack.com/api

Building is a two-step flow — get an upload target, PUT your source, then start the build:

# 1. Request an upload target
curl -sX POST https://api.mybuildstack.com/api/projects/PROJECT_ID/source-uploads \
  -H "Authorization: Bearer $DBS_API_KEY"
# → { "uploadUrl": "https://…", "key": "sources/…" }

# 2. Upload your source tarball to the returned URL
curl -sX PUT "$UPLOAD_URL" --data-binary @source.tgz

# 3. Start a signed release build
curl -sX POST https://api.mybuildstack.com/api/projects/PROJECT_ID/builds \
  -H "Authorization: Bearer $DBS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "variant": "release", "format": "aab", "sign": true, "sourceKey": "sources/…" }'
# → { "id": "b_8f2a1c", "status": "queued" }

Poll the build, or list a project's builds:

curl -s https://api.mybuildstack.com/api/projects/PROJECT_ID/builds \
  -H "Authorization: Bearer $DBS_API_KEY"

Common build fields:

Webhooks

To react to builds in your own systems, add a webhook endpoint in the project's settings. BuildStack POSTs an event to your URL when a build changes state (for example when it finishes), so you can trigger a deploy, notify a channel, or update a dashboard. Deliveries are retried on failure.

Running whole workflows on BuildStack

The above triggers app builds. To run your existing GitHub Actions jobs on BuildStack compute instead of GitHub-hosted runners, see Run GitHub Actions CI on BuildStack.